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",
    "zoneId": "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.

  • zoneId: identificador externo de la zona. En caso de que la zona indicada no exista, el registro se guardará con tarea, pero sin zona, por lo que no podrá devolverse después en la consulta de fichajes.

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",
        "clockguardType": "WORK",
        "recordType": "IN",
        "date": "2026-04-09T08:00:00.000Z",
        "locationId": "02",
        "zoneId": "ZG"
    },
    {
        "employeeId": "1006357",
        "clockguardType": "WORK",
        "recordType": "OUT",
        "date": "2026-04-09T15:00:00.000Z",
        "locationId": "02",
        "zoneId": "ZG"
    }
]

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. En este caso, el registro no se persiste.

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

  • Si el identificador de empleado indicado no existe en el negocio: error.business_employee_not_found.

  • Si el fichaje se ha realizado fuera del radio de distancia permitido para la ubicación: clock_guard_distance_restricted.

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 registro corresponde a un día marcado como libre para el empleado, se descarta sin indicar ningún error en la respuesta: el elemento devuelto tendrá orquestId y error a null.

Si no se indica zona (zoneId), el fichaje se registrará para la tarea indicada (locationId) de la zona General.

Si la tarea (locationId) o la zona (zoneId) indicadas no se corresponden con las que hay en el sistema, el fichaje se registrará sin tarea asociada.

Códigos de error

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

Código Mensaje Descripción

400 Bad Request

-

El formato de fecha (date) de uno o más registros no es válido. Se recomienda usar el formato yyyy-MM-ddTHH:mm:ss.SSSZ.

406 Not Acceptable

The employee id cannot be null

Falta el campo employeeId en uno o más registros.

Clockguard type cannot be null

Falta el campo clockguardType en uno o más registros.

Record type cannot be null

Falta el campo recordType en uno o más registros.

Date cannot be null

Falta el campo date en uno o más registros.

must match "(OTHER|REST|WORK)"

El campo clockguardType no tiene uno de los valores admitidos (WORK, REST, OTHER).

must match "(IN|OUT)"

El campo recordType no tiene uno de los valores admitidos (IN, OUT).

-

La colección enviada supera el límite de 4000 elementos permitido. Se recomienda dividir la petición en lotes más pequeños.

409 Conflict

-

Se ha producido un conflicto al guardar uno o más registros. Se recomienda revisar que los datos enviados no violen ninguna restricción de integridad.

Enlaces de interés

¿Qué es un fichaje?

¿Cómo integrar fichajes?