Quiero integrar fichajes

¿Qué son los fichajes?

Tal y como se detalla aquí, los fichajes hacen referencia a los registros de entrada o salida de un empleado en su lugar de trabajo, ya sea para tiempo trabajado o para descansos.

¿Cómo integrar fichajes?

Para registrar nuevos fichajes en el sistema, se puede utilizar el siguiente endpoint:

  • Registrar una lista de fichajes. Permite añadir una lista de fichajes siempre que se incluya el identificador del empleado y los datos relativos al fichaje (tipo de registro, tipo de actividad, fecha, etc.).

Estos fichajes, por defecto, aparecerán como consolidados en el sistema y deberían ser la agrupación de dos registros, uno de entrada ("recordType": "IN") y otro de salida ("recordType": "OUT").

Para cambiar este comportamiento y que los registros no se consoliden en la integración, será necesario modificar la configuración de negocio (propiedades del importador).

¿Qué operaciones se pueden realizar en la integración de fichajes?

Añadir un fichaje de tiempo trabajado

Para añadir un nuevo fichaje de tiempo trabajado, basta con indicarlo en el tipo de actividad de la petición: "clockguardType": "WORK".

Ver ejemplo 
[
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "IN",
    "date": "2024-06-15T09:00:00Z"
  },
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "OUT",
    "date": "2024-06-15T14:00:00Z"
  }
]

Añadir un fichaje de descanso

Para añadir un descanso, basta con indicarlo en el tipo de actividad de la petición: "clockguardType": "REST".

Ver ejemplo 
[
  {
    "employeeId": "1006357",
    "clockguardType": "REST",
    "recordType": "IN",
    "date": "2024-06-15T14:00:00Z"
  },
  {
    "employeeId": "1006357",
    "clockguardType": "REST",
    "recordType": "OUT",
    "date": "2024-06-15T16:00:00Z"
  }
]

Eliminar fichajes

Considerando la distinción entre registro y fichaje consolidado expuesta aquí, las opciones para eliminarlos son las siguientes:

  • Eliminar registros de fichajes. Permite eliminar los registros de fichajes de un producto para un día determinado. Si el registro ha sido consolidado, solo se eliminará el registro, no la consolidación.

  • Eliminar fichajes consolidados. Permite eliminar los fichajes consolidados vinculados a un producto en un día concreto. Se eliminan los fichajes consolidados, pero no los registros.

  • Eliminar colección de fichajes. Permite eliminar los fichajes consolidados cuyos identificadores se indiquen en la URL. Se eliminan los fichajes consolidados, pero no los registros.

  • Eliminar un fichaje. Permite eliminar el fichaje consolidado cuyo identificador se indique en la URL. Se elimina el fichaje consolidado, pero no el registro.

Consultar fichajes

Para consultar los fichajes consolidados, se pueden utilizar los siguientes endpoints:

Preguntas frecuentes

¿Qué zona horaria se considera para la integración?

Las horas se deben enviar en UTC y la publicación en el sistema se realiza considerando el huso horario del servicio.

Por ejemplo, en un servicio cuya zona horaria es UTC+2, se registra el siguiente fichaje:

[
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "IN",
    "date": "2024-06-13T18:00:00Z"
  },
  {
    "employeeId": "1006357",
    "clockguardType": "WORK",
    "recordType": "OUT",
    "date": "2024-06-13T20:00:00Z"
  }
]

El resultado en el sistema es un fichaje de 20:00 a 22:00.

La consulta de este fichaje también se devuelve en UTC:

[
    {
        "employeeId": "1006357",
        "type": "WORK",
        "checkIn": "2024-06-13T18:00:00.000Z",
        "checkOut": "2024-06-13T20:00:00.000Z",
        "orquestId": 230359810
    }
]

¿Qué pasa si se crea un fichaje erróneo?

Si hay errores en el registro, por ejemplo, mismo tipo de fichaje (IN), la API devuelve los datos tal y como se han registrado. Sin embargo, ese fichaje no se tendría en cuenta en cuestiones de planificación o contadores, ya que estaría incompleto.

¿Qué diferencia hay entre la consulta por servicio y la consulta por producto?

La diferencia entre consultar los fichajes por servicio y consultarlos por producto radica en el nivel de detalle y la segmentación de los datos obtenidos.

  • Consultar los fichajes por servicio: se enfoca en los fichajes de la tienda/restaurante/taller, etc. sin distinguir —necesariamente— entre las diferentes secciones o departamentos dentro de la misma. Si en el momento del registro se incluye la tarea (location) donde se ha realizado el fichaje, esta consulta también aportará información sobre el identificador del producto.

  • Consultar los fichajes por producto: se enfoca en los fichajes de una sección concreta. Si en el momento del registro se incluye la tarea (location) donde se ha realizado el fichaje, esta consulta aportará información detallada sobre dicha tarea.

  • Servicio

  • Producto

[
    {
        "employeeId": "1006357",
        "type": "WORK",
        "checkIn": "2024-06-16T14:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349899
    },
    {
        "employeeId": "1006356",
        "type": "WORK",
        "checkIn": "2024-06-16T15:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349904
    },
    {
        "employeeId": "1006357",
        "productId": "0001",
        "locationId": "04",
        "type": "WORK",
        "checkIn": "2024-06-15T09:00:00.000Z",
        "latIn": 37.389091,
        "lonIn": -5.984459,
        "deviceIn": "12345",
        "checkOut": "2024-06-15T14:00:00.000Z",
        "latOut": 37.389091,
        "lonOut": -5.984459,
        "deviceOut": "12345",
        "orquestId": 230349910
    }
]
[
    {
        "employeeId": "1006357",
        "type": "WORK",
        "checkIn": "2024-06-16T14:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349899
    },
    {
        "employeeId": "1006356",
        "type": "WORK",
        "checkIn": "2024-06-16T15:00:00.000Z",
        "checkOut": "2024-06-16T19:00:00.000Z",
        "orquestId": 230349904
    },
    {
        "employeeId": "1006357",
        "location": {
            "color": "#c5f2ff",
            "description": "inventario anual",
            "name": "INVENTARIO",
            "shortName": "INV",
            "requiredLevel": 0,
            "priority": 1,
            "type": "UNPLANNED",
            "shouldAvoidOvercover": false,
            "system": false,
            "product": "0001-G",
            "id": "04"
        },
        "type": "WORK",
        "checkIn": "2024-06-15T09:00:00.000Z",
        "latIn": 37.389091,
        "lonIn": -5.984459,
        "deviceIn": "12345",
        "checkOut": "2024-06-15T14:00:00.000Z",
        "latOut": 37.389091,
        "lonOut": -5.984459,
        "orquestId": 230349910
    }
]

La elección entre una consulta y otra dependerá de las necesidades de análisis y gestión del negocio.

¿De dónde se obtiene el orquestId?

En la consulta de fichajes, tanto por servicio como por producto, la respuesta contiene el orquestId o identificador interno de cada fichaje, necesario para las peticiones en las que estos se eliminan a través de su identificador.

Buenas prácticas

Para garantizar una correcta gestión de los fichajes y evitar inconsistencias en la información procesada, se recomienda seguir estas buenas prácticas al enviar datos vía API:

  • Evitar envíos duplicados. Cada registro debe enviarse (deseablemente) una única vez, con el fin de prevenir registros repetidos que puedan afectar el emparejamiento de entradas y salidas.

  • Mantener el orden cronológico. Los registros deben enviarse en el orden en que ocurrieron, asegurando que los registros de entrada precedan a los de salida. El desorden en los datos puede generar emparejamientos incorrectos o dificultades en el procesamiento.

  • Garantizar la integridad de los datos. Los registros incompletos o erróneos pueden interferir en la correcta identificación de los pares de fichaje.

El cumplimiento de estas prácticas optimiza el procesamiento de la información y garantiza que los fichajes sean registrados de manera confiable y consistente en el sistema.