Registrar listado de incidencias

Este endpoint permite registrar una lista de incidencias para un mismo empleado.

POST /api/v1/import/incidences

A continuación, se expone una explicación detallada de cada uno de los campos que pueden conformar el cuerpo de la petición, siendo algunos de ellos obligatorios para que esta se realice de manera exitosa.

Los campos obligatorios están marcados con un asterisco (*).

Cuerpo de la petición

Análisis del JSON

Análisis del JSON
`{ "lag": 0, "business": "string", "employeeId": "string", "incidences": [ { "type": "string", "initTime": "string", "endTime": "string", "workedMinutes": 0, "from": "string", "to": "string", "id": "string", "orquestId": 0 } ] }` Detalles lag: número de días previos a la fecha actual que se consideran al gestionar la petición. business: identificador configurado en Orquest para el negocio. employeeId*: identificador del empleado vinculado con la incidencia. incidences*: lista de incidencias vinculadas al empleado. Por cada una de las incidencias que se quieran registrar, se deben cumplimentar los siguientes campos: type*: identificador del tipo de incidencia. Debe estar configurado previamente en Orquest. initTime: hora de inicio de la incidencia. Debe estar en formato `HH:mm` con la siguiente expresión regular: `^([01]\d\|2[0-3]):[0-5]\d$`. Se considera la hora local, es decir, la zona horaria del servicio. endTime: hora de finalización de la incidencia. Debe estar en formato `HH:mm` con la siguiente expresión regular: `^([01]\d\|2[0-3]):[0-5]\d$`. Se considera la hora local, es decir, la zona horaria del servicio. workedMinutes*: tiempo, en minutos, que la incidencia computa. from**: fecha en la que comienza la incidencia. Debe estar en formato `yyyy-MM-dd`. to: fecha en la que finaliza la incidencia. Debe estar en formato `yyyy-MM-dd`. id: identificador externo de la incidencia. orquestId: identificador de la incidencia en Orquest.

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

Detalles

lag*: número de días previos a la fecha actual que se consideran al gestionar la petición.
business*: identificador configurado en Orquest para el negocio.
employeeId*: identificador del empleado vinculado con la incidencia.
incidences*: lista de incidencias vinculadas al empleado. Por cada una de las incidencias que se quieran registrar, se deben cumplimentar los siguientes campos:
- type*: identificador del tipo de incidencia. Debe estar configurado previamente en Orquest.
- initTime: hora de inicio de la incidencia. Debe estar en formato HH:mm con la siguiente expresión regular: ^([01]\d|2[0-3]):[0-5]\d$. Se considera la hora local, es decir, la zona horaria del servicio.
- endTime: hora de finalización de la incidencia. Debe estar en formato HH:mm con la siguiente expresión regular: ^([01]\d|2[0-3]):[0-5]\d$. Se considera la hora local, es decir, la zona horaria del servicio.
- workedMinutes*: tiempo, en minutos, que la incidencia computa.
- from*: fecha en la que comienza la incidencia. Debe estar en formato yyyy-MM-dd.
- to*: fecha en la que finaliza la incidencia. Debe estar en formato yyyy-MM-dd.
- id: identificador externo de la incidencia.
- orquestId: identificador de la incidencia en Orquest.

Ejemplo de la petición

Una vez realizado el análisis de los distintos campos, se muestra un ejemplo del cuerpo de la petición:

{
  "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"
    }
  ]
}

Consideraciones

Esta petición generará una operación atómica que se puede revertir de forma automática si hay errores: el error se mostrará en la respuesta de la petición.

El campo lag no es solo un margen temporal: dentro de esa ventana de días previos a la fecha actual, cualquier incidencia del empleado que no esté incluida en la lista de la petición se eliminará del sistema. Se recomienda incluir siempre todas las incidencias del empleado dentro del rango cubierto por lag, no solo las nuevas o modificadas.

Si el identificador de empleado indicado no existe en el negocio, la petición devolverá un estado 200 OK indicando en la respuesta el error not_valid_person.

Si varias incidencias de la lista tienen errores de validación, solo se reporta el de la primera incidencia que falla.

Códigos de error

Además de los errores comunes, este endpoint puede devolver los siguientes códigos:

Código Mensaje Descripción

Código	Mensaje	Descripción
`406 Not Acceptable`	Lag mut be positive or zero	El campo `lag` tiene un valor negativo. (Literal tal cual lo devuelve el backend, con la errata "mut" en vez de "must".)
Business in employee incidences cannot be null	Falta el campo `business`.
EmployeeId in employee incidences cannot be null	Falta el campo `employeeId`.
List of incidences in employee incidences cannot be null	Falta el campo `incidences`.
Type in incidence cannot be null	Falta el campo `type` en alguna incidencia de la lista.
Worked minutes cannot be null / Worked minutes should be positive or zero	Falta el campo `workedMinutes` en alguna incidencia, o tiene un valor negativo.
From in incidence cannot be null / To in incidence cannot be null	Falta el campo `from` o `to` en alguna incidencia.
Init Time is invalid. Format should be: HH:mm / End Time is invalid. Format should be: HH:mm	El campo `initTime` o `endTime` de alguna incidencia no tiene el formato `HH:mm` esperado.
Incidence range is invalid	El rango definido entre `from` y `to` de alguna incidencia no es válido.
`400 Bad Request`	has_not_type	El tipo de incidencia indicado en `type` de alguna incidencia no está definido en el catálogo de incidencias del negocio.
`409 Conflict`	-	Se ha producido un conflicto al guardar las incidencias. Se recomienda revisar que los datos enviados no violen ninguna restricción de integridad.

406 Not Acceptable

Lag mut be positive or zero

El campo lag tiene un valor negativo. (Literal tal cual lo devuelve el backend, con la errata "mut" en vez de "must".)

Business in employee incidences cannot be null

Falta el campo business.

EmployeeId in employee incidences cannot be null

Falta el campo employeeId.

List of incidences in employee incidences cannot be null

Falta el campo incidences.

Type in incidence cannot be null

Falta el campo type en alguna incidencia de la lista.

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

Falta el campo workedMinutes en alguna incidencia, o tiene un valor negativo.

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

Falta el campo from o to en alguna incidencia.

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

El campo initTime o endTime de alguna incidencia no tiene el formato HH:mm esperado.

Incidence range is invalid

El rango definido entre from y to de alguna incidencia no es válido.

400 Bad Request

has_not_type

El tipo de incidencia indicado en type de alguna incidencia no está definido en el catálogo de incidencias del negocio.

409 Conflict

Se ha producido un conflicto al guardar las incidencias. Se recomienda revisar que los datos enviados no violen ninguna restricción de integridad.

Enlaces de interés

¿Qué es una incidencia?

¿Qué es el lag en una petición?

¿Cómo integrar incidencias?