# Payroll

The Payroll endpoints implement a **bi-directional flow**
between an external payroll system and Dyflexis:

- **Payroll → Dyflexis (employee sync).** The payroll system
  is typically the source of truth for the workforce.
  Employee and contract data can be synced from the payroll
  system into Dyflexis so that scheduling, time-tracking,
  and absence administration all operate on the same
  employee master that payroll uses. The endpoints for this
  direction live under
  [**Employees**](#tag/Employees) and
  [**Employment contracts**](#tag/Employment-contracts).
- **Dyflexis → Payroll (confirmed hours).** Once a payroll
  period closes in Dyflexis, Dyflexis makes **all confirmed
  hour information** for that period, aggregated per day
  and per department, available for the payroll system to
  pick up and process. Each finalised period is published
  on a queue you poll and acknowledge, so no period is
  missed or processed twice.

Concretely, this resource exposes hours aggregated per day
and per department for a payroll period, the queue of
finalised payroll periods waiting to be picked up by an
external payroll system, and the wage components that
periods produce.

Typical export flow (Dyflexis → Payroll):

1. Poll `GET /api2/payroll/queue/from/{lastQueueId}` for new items.
2. For each item, fetch the period hours from
   `GET /api/payroll/v3/hours-per-day/...` or
   `GET /api/payroll/v3/hours-per-department/...`.
3. Acknowledge the item with
   `POST /api2/payroll/queue/{queueId}/status`.


## List payroll employees

 - [GET /api/payroll/v3/employees](https://beta-developer.dyflexis.com/openapi/payroll/listpayrollemployees.md): Requires scope: payroll.

Fetches all active employees and their contracts. Returns up to 100 employees per page.

## Fetch hours per day

 - [GET /api/payroll/v3/hours-per-day/{officeUrl}/{contractTypeGroupName}/{period}](https://beta-developer.dyflexis.com/openapi/payroll/gethoursperday.md): Requires scope: payroll.

Returns a list of all hours, allowances, and expenses in the requested locked payroll period.
Only days that have either hours, allowances or expenses will be included.

## Fetch hours per department

 - [GET /api/payroll/v3/hours-per-department/{officeUrl}/{contractTypeGroupName}/{period}](https://beta-developer.dyflexis.com/openapi/payroll/gethoursperdepartment.md): Requires scope: payroll.

Returns a list of all hours, allowances, and expenses in the requested locked payroll period, grouped by department.
For the neutral hour types, for example sickness, leave or all the allowances are grouped by the primary department of the employee.
Only days that have hours, allowances, or expenses will be included.

## List wage components

 - [GET /api2/payroll/wage-components](https://beta-developer.dyflexis.com/openapi/payroll/listwagecomponents.md): Requires scope: payroll_hours.

Lists all available wage components with their user friendly display names.
This list can be used as an aid in mapping the wage component fields to their corresponding fields in other systems.

Wage components are defined by using the wage component dropdown for columns in the Chronos sheet.

## Fetch the payroll period queue

 - [GET /api2/payroll/queue/from/{lastQueueId}](https://beta-developer.dyflexis.com/openapi/payroll/getpayrollperiodqueue.md): Requires scope: payroll_hours.

Dyflexis allows the user to "send" a locked payroll period for external processing. These payroll periods are then added to a queue which you can fetch using this endpoint.

Each entry in this list has a unique queue id and a URL you can use to fetch the payroll information.

The endpoint will list all queue items that have been created after lastQueueId, limited to a maximum of 10 items, so you can easily see whether there are new queue items to process.
Use 0 as lastQueueId to get the very first 10 queue items.

You will need to keep track of which queue ids you have already processed in order to prevent processing remuneration information more than once.

## Update queue item status

 - [POST /api2/payroll/queue/{queueId}/status](https://beta-developer.dyflexis.com/openapi/payroll/updatepayrollqueuestatus.md): Requires scope: payroll_hours.

You can update the status of a queue item in Dyflexis when processing the payroll period queue.
The status is displayed in the Dyflexis payroll page.

## Payroll period ready

 - [POST payrollPeriodReady](https://beta-developer.dyflexis.com/openapi/payroll/payrollperiodreadyevent.md): > Webhook, Dyflexis sends this POST request to a URL you host. See the Webhooks guide for how to register your receiver and what it must return.

Sends a message when the payroll data is ready. You can use the
payload to call a desired endpoint.

The webhook can't be registered with this API. Please register
this webhook in Dyflexis.