Quiero integrar incidencias
¿Qué son las incidencias?
Tal y como se detalla aquí, las incidencias representan cualquier ausencia de un empleado: vacaciones, día de asuntos propios, baja por maternidad, etc.
¿Cómo integrar incidencias?
Para registrar nuevas incidencias en el sistema, se pueden utilizar los siguientes endpoints:
-
Registrar una incidencia. Permite añadir una sola incidencia para un empleado.
-
Registrar listado de incidencias. Permite añadir varias incidencias para un empleado considerando el parámetro lag.
-
Actualizar una incidencia. Permite actualizar la información de una incidencia previamente registrada.
¿Qué operaciones se pueden realizar en la integración de incidencias?
Añadir una ausencia
Una vez que la incidencia está registrada en el catálogo de incidencias del negocio (Configuración de negocio > Tipos de incidencia), es posible aplicarla a un empleado a través de los siguientes endpoints:
Ver ejemplo
En el catálogo de incidencias del negocio existe el tipo de incidencia CITA MÉDICA con identificador (type) 01.
Para aplicarla al empleado con identificador 1006356, se realiza la siguiente petición:
POST /api/v1/import/incidence{
"business": "BUSINESSID",
"employeeId": "1006356",
"type": "01",
"initTime": "12:00",
"endTime": "14:00",
"workedMinutes": 120,
"from": "2024-07-02",
"to": "2024-07-02",
"id": "0156"
}Tras el registro, esta ausencia aparecerá en el calendario de incidencias del servicio (Gestión de empleados > Calendario de incidencias) y, en función de su configuración de negocio, se aplicarán los parámetros necesarios para el empleado: no permitir que se asignen turnos, establecer un margen entre la incidencia y el turno, etc.
Añadir varias ausencias
Para añadir varias ausencias a un mismo empleado —siempre que estas estén registradas en el catálogo de incidencias del negocio—, se puede utilizar el siguiente endpoint:
|
Esta petición incluye el parámetro lag, por lo que habrá que tenerlo en cuenta para la correcta gestión de los datos dentro de Orquest. |
Ver ejemplo
En el catálogo de incidencias del negocio existe el tipo de incidencia CITA MÉDICA con identificador (type) 01 y VACACIONES con identificador (type) 02 .
Para aplicar varias ausencias con estos tipos al empleado con identificador 1006356, se realiza la siguiente petición:
POST /api/v1/import/incidences{
"lag": 0,
"business": "BUSINESSID",
"employeeId": "1006356",
"incidences": [
{
"type": "01",
"workedMinutes": 30,
"initTime": "09:30",
"endTime": "10:30",
"from": "2024-07-08",
"to": "2024-07-08",
"id": "015601"
},
{
"type": "02",
"workedMinutes": 0,
"from": "2024-07-15",
"to": "2024-07-20",
"id": "025601"
},
{
"type": "02",
"workedMinutes": 0,
"from": "2024-08-01",
"to": "2024-08-15",
"id": "025602"
}
]
}Tras el registro, en el calendario de incidencias del servicio (Gestión de empleados > Calendario de incidencias), aparecerán las siguientes ausencias para el empleado:
-
2024-07-08: CITA MÉDICA de 9:30 a 10:30 con 30 minutos trabajados.
-
2024-07-15 al 2024-07-20: periodo de VACACIONES.
-
2024-08-01 al 2024-08-15: periodo de VACACIONES.
Del mismo modo que en el escenario anterior, en función de la configuración de negocio, se aplicarán los parámetros necesarios para el empleado: no permitir que se asignen turnos, establecer un margen entre la incidencia y el turno, etc.
|
Como se ha establecido en la petición |
Eliminar incidencias
Para eliminar incidencias registradas en el sistema, se pueden utilizar los siguientes endpoints:
-
Eliminar una incidencia a través de su identificador externo. Si el identificador externo de la incidencia es correcto, la petición eliminará el registro. Si el identificador no es correcto, la petición devolverá un error
404 Not Foundcon el siguiente mensaje: Could not find any incidence with id --- for business ---. -
Eliminar las incidencias de un empleado. Si el identificador del empleado es correcto, la petición eliminará todos los registros de incidencias comprendidas en el intervalo de tiempo indicado en la petición. Si el identificador de empleado no es correcto, la petición devolverá un error
404 Not Foundcon el siguiente mensaje: Could not find employee with id ---.
Ver ejemplo
En el calendario de incidencias, el empleado con identificador 1006356 tiene una ausencia de tipo VACACIONES con identificador (type) 02 del 2024-07-15 al 2024-07-20.
Si se realiza la siguiente petición:
DELETE /api/v1/business/{businessId}/employees/1006356/incidences?from=2024-07-16&to=2024-07-16Como el intervalo especificado en la petición contempla las fechas para las que está definida esta ausencia (2024-07-16), se elimina la ausencia completa del calendario de incidencias.
Consultar incidencias
Las incidencias registradas para los empleados de un negocio se pueden consultar por servicio o por producto a través de los siguientes endpoints:
-
Consultar incidencias de un servicio. Devuelve las incidencias registradas para un servicio.
-
Consultar incidencias de un producto. Devuelve las incidencias registradas para un producto.
En cualquiera de las peticiones, el rango de consulta no debe exceder los 30 días.
Preguntas frecuentes
¿Qué zona horaria se considera para la integración?
En la integración de incidencias, se considera la zona horaria configurada para el servicio. Por ejemplo, para un servicio en UTC+2, se envía la siguiente incidencia:
POST /api/v1/import/incidence{
"business": "BUSINESSID",
"employeeId": "1006357",
"type": "01",
"initTime": "17:00",
"endTime": "19:00",
"workedMinutes": 0,
"from": "2024-07-05",
"to": "2024-07-05",
"id": "0157"
}El resultado en el calendario de incidencias será una ausencia de tipo 01 de las 17:00 a las 19:00, tal y como aparece en el cuerpo de la petición.
¿Qué diferencia hay entre la consulta por servicio y la consulta por producto?
La diferencia entre consultar las incidencias por servicio y consultarlas por producto radica en la segmentación de los datos obtenidos.
La elección entre una consulta y otra dependerá de las necesidades de análisis y gestión del negocio, ya que el nivel de detalle de los datos obtenidos es el mismo.
¿Es obligatorio establecer un identificador para la incidencia?
No, el identificador externo no es obligatorio para la integración de incidencias en Orquest, pero sí altamente recomendable. Además, en caso de querer eliminar incidencias a través del identificador, será necesario haberlo definido previamente.