Registrar una lista de fichajes

Este endpoint permite registrar una colección de fichajes no nulos.

POST /api/v1/import/business/{businessId}/clockguardrecords

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 
[
  {
    "employeeId": "string",
    "locationId": "string",
    "clockguardType": "string",
    "recordType": "string",
    "date": "string",
    "lat": 0,
    "lon": 0,
    "device": "string",
    "orquestId": 0,
    "error": "string"
  }
]
Detalles

  • employeeId*: identificador del empleado vinculado con el registro.

  • locationId: identificador de la tarea donde se realiza el registro, si procede.

  • clockguardType*: tipo de actividad que se registra. Los valores admitidos para este campo son WORK, REST y OTHER.

  • recordType*: tipo de registro que se realiza. Los valores admitidos para este campo son IN y OUT.

  • date*: fecha y hora a la que se realiza el registro, en UTC y en formato yyyy-MM-ddTHH:mm:ss.SSSZ.

  • lat: latitud geográfica desde donde se envía el registro. Puede ser null.

  • lon: longitud geográfica desde donde se envía el registro. Puede ser null.

  • device: identificador del dispositivo de registro de fichajes.

  • orquestId: identificador interno del fichaje consolidado en Orquest. No es necesario enviar este campo, ya que se genera de manera automática en el sistema.

  • error: mensaje de error acerca del registro, si procede.

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:

[
  {
    "employeeId": "1006357",
    "locationId": "04",
    "clockguardType": "WORK",
    "recordType": "IN",
    "date": "2024-06-15T09:00:00Z",
    "lat": 37.389091,
    "lon": -5.984459,
    "device": "12345",
    "error": "No error"
  },
  {
    "employeeId": "1006357",
    "locationId": "04",
    "clockguardType": "WORK",
    "recordType": "OUT",
    "date": "2024-06-15T14:00:00Z",
    "lat": 37.389091,
    "lon": -5.984459,
    "device": "12345",
    "error": "No error"
  }
]

Si la petición es exitosa, la respuesta será un estado 200 OK con el desglose de los fichajes que han sido registrados en el sistema.

El nivel de detalle de la respuesta dependerá de los datos que se hayan enviado en la petición y de la configuración de negocio. Por ejemplo, si el negocio tiene activa la autoconsolidación de fichajes, la respuesta contendrá el identificador interno del fichaje consolidado (orquestId).

Aspectos que tener en cuenta

Las horas se deben enviar en UTC y la publicación se realiza considerando la zona horaria del servicio.

El tamaño máximo permitido para esta petición es de 4000 elementos.

Los fichajes enviados a través de la API pueden mostrarse en el sistema como fichajes registrados o como fichajes consolidados. Este comportamiento depende de la configuración de negocio (Configuration parameters) y, para cambiarlo, será necesario consultar con el equipo de Orquest.

Si alguno de los registros de la petición tiene errores, la petición devolverá un estado 200 OK indicando en la respuesta el tipo de error:

  • Si el registro está duplicado con un registro previo: clock_guard_duplicated.

  • Si el registro de salida no se puede emparejar con un registro de entrada: error.previous_checkin_not_found.

El sistema permite el envío de registros de fichajes que solapen entre sí: estos se almacenarán y visualizarán tal como se hayan incluido en la petición enviada.

Si el formato de hora o fecha no es correcto, la petición devolverá un error 400 Bad Request.

Si el identificador de empleado indicado no es correcto, la petición devolverá un error 400 Bad Request.

Si el campo clockguardType no se define con los valores correctos, la petición devolverá un error 406 Not Acceptable, indicando en el mensaje must match \"(OTHER|REST|WORK)\".

Si el campo recordType no se define con los valores correctos, la petición devolverá un error 406 Not Acceptable, indicando en el mensaje must match \"(IN|OUT)\".

Enlaces de interés

¿Qué es un fichaje?

¿Cómo integrar fichajes?