Add a list of incidences

This endpoint allows registering a list of incidences for the same employee.

POST /api/v1/import/incidences

Below is a detailed explanation of each of the fields that can make up the request body, with some being mandatory for the request to be successful.

Mandatory fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "lag": 0,
  "business": "string",
  "employeeId": "string",
  "incidences": [
    {
      "type": "string",
      "initTime": "string",
      "endTime": "string",
      "workedMinutes": 0,
      "from": "string",
      "to": "string",
      "id": "string",
      "orquestId": 0
    }
  ]
}
Details

  • lag*: number of days prior to the current date considered when managing the request.

  • business*: identifier configured in Orquest for the business.

  • employeeId*: identifier of the employee linked to the incidence.

  • incidences*: list of incidences linked to the employee. For each of the incidences to be registered, the following fields must be filled:

    • type*: identifier of the incidence type. It must be configured previously in Orquest.

    • initTime: start time of the incidence. It must be in HH:mm format with the following regular expression: ^([01]\d|2[0-3]):[0-5]\d$. Refers to local time, that is, the time zone of the service.

    • endTime: end time of the incidence. It must be in HH:mm format with the following regular expression: ^([01]\d|2[0-3]):[0-5]\d$. Refers to local time, that is, the time zone of the service.

    • workedMinutes*: time, in minutes, that the incidence computes.

    • from*: start date of the incidence. It must be in yyyy-MM-dd format.

    • to*: end date of the incidence. It must be in yyyy-MM-dd format.

    • id: external identifier of the incidence.

    • orquestId: identifier of the incidence in Orquest.

Request example

Once the analysis of the different fields has been done, an example of the request body is shown:

{
  "lag": 0,
  "business": "BUSINESSID",
  "employeeId": "C14A658",
  "incidences": [
    {
      "type": "01",
      "initTime": "09:00",
      "endTime": "10:00",
      "workedMinutes": 60,
      "from": "2024-05-01",
      "to": "2024-05-01",
      "id": "C14-12547"
    },
    {
      "type": "03",
      "workedMinutes": 0,
      "from": "2024-05-12",
      "to": "2024-05-30",
      "id": "C14-12549"
    }
  ]
}

Considerations

This request will generate an atomic operation that can be automatically reversed if there are errors: the error will be displayed in the response of the request.

The lag field is not just a time margin: within that window of days prior to the current date, any incidence of the employee that is not included in the request list will be removed from the system. It is recommended to always include all the employee’s incidences within the range covered by lag, not only the new or modified ones.

If the indicated employee identifier does not exist in the business, the request will return a 200 OK status, indicating the not_valid_person error in the response.

If several incidences in the list have validation errors, only the error of the first failing incidence is reported.

Error codes

In addition to the common errors, this endpoint can return the following codes:

Code Message Description

406 Not Acceptable

Lag mut be positive or zero

The lag field has a negative value. (Literal as returned by the backend, with the typo "mut" instead of "must".)

Business in employee incidences cannot be null

The business field is missing.

EmployeeId in employee incidences cannot be null

The employeeId field is missing.

List of incidences in employee incidences cannot be null

The incidences field is missing.

Type in incidence cannot be null

The type field is missing in one of the incidences in the list.

Worked minutes cannot be null / Worked minutes should be positive or zero

The workedMinutes field is missing in one of the incidences, or it has a negative value.

From in incidence cannot be null / To in incidence cannot be null

The from or to field is missing in one of the incidences.

Init Time is invalid. Format should be: HH:mm / End Time is invalid. Format should be: HH:mm

The initTime or endTime field of one of the incidences does not have the expected HH:mm format.

Incidence range is invalid

The range defined between from and to of one of the incidences is not valid.

400 Bad Request

has_not_type

The incidence type indicated in type of one of the incidences is not defined in the business’s incidence catalog.

409 Conflict

-

A conflict occurred while saving the incidences. It is recommended to review that the data sent does not violate any integrity constraint.

Useful links

What is an incidence?

What is the lag in a request?

How to integrate incidences?