Obtener cambios incrementales

Este endpoint devuelve las asignaciones que han sufrido cambios desde la fecha indicada en la petición hasta la fecha actual.

GET /api/v1/businesses/{businessId}/assignments/incremental?since={yyyy-MM-ddTHH:mm:ss.SSS}

Si los datos incluidos en la petición son correctos, la respuesta contendrá las asignaciones que han cambiado desde la fecha indicada en el parámetro since hasta la fecha actual. Este parámetro debe ser una fecha dentro de los últimos 45 días en formato UTC.

Se trata de una respuesta paginada, por lo que, después de la primera llamada, en los encabezados de respuesta aparecerá un cursor a la página siguiente (next) que indica la URL de la siguiente petición incremental de asignaciones. Para obtener la siguiente página de datos, se debe realizar una petición a esa URL con el cursor:

GET /api/v1/businesses/{businessId}/assignments/incremental?cursor=*******

Será necesario repetir este proceso hasta que la respuesta no contenga la cabecera next, lo que indica que la paginación ha terminado y que no hay más datos que mostrar.

Ejemplo de respuesta

[
    {
        "product": "0001-G",
        "day": "2024-07-17",
        "assignments": [
            {
                "person": "1006355",
                "orquestId": 3456,
                "presence": {
                    "worked": false,
                    "timeFrames": [
                        {
                            "startMinuteDay": 0,
                            "duration": 1425,
                            "paid": false,
                            "worked": false
                        }
                    ]
                },
                "virtual": false
            }
        ]
    },
    {
        "product": "0002-G",
        "day": "2024-07-03",
        "assignments": [
            {
                "person": "1006356",
                "orquestId": 1234,
                "presence": {
                    "worked": true,
                    "timeFrames": [
                        {
                            "startMinuteDay": 570,
                            "duration": 180,
                            "paid": true,
                            "location": {
                                "color": "#738ac8",
                                "description": "Opening boxes, reviewing funds",
                                "name": "KITCHEN OPENING",
                                "shortName": "KO",
                                "requiredLevel": 3,
                                "priority": 4,
                                "type": "VARIABLE",
                                "shouldAvoidOvercover": true,
                                "system": false,
                                "category": "ADMINISTRATIVE",
                                "product": "0002-G",
                                "id": "KITCHEN_OPENING",
                                "zone": "General"
                            },
                            "worked": true
                        }
                    ]
                },
                "virtual": false
            }
        ]
    }
]
Detalles

  • product: identificador externo del producto o sección al que pertenecen las asignaciones agrupadas.

  • day: día al que corresponden las asignaciones agrupadas, en formato yyyy-MM-dd.

  • assignments: listado de asignaciones para el producto y día indicados. Cada elemento contiene la siguiente información:

    • person: identificador externo del empleado.

    • orquestId: identificador interno de la asignación en Orquest.

    • presence: tipo de asignación que contiene los periodos de trabajo (timeFrames) con sus ubicaciones. Contiene los siguientes campos:

      • worked: si el tipo de asignación o presencia es trabajada (true) o si es un día de descanso (false).

      • timeFrames: conjunto de intervalos de tiempo que contiene las tareas que se van a realizar. Para cada intervalo, se incluye la siguiente información:

        • startMinuteDay: comienzo del intervalo en minutos transcurridos desde el inicio del día (00:00).

        • duration: duración del intervalo en minutos.

        • paid: si el intervalo, sea de trabajo o descanso, es pagado (true) o no (false).

        • worked: determina si el timeFrame tiene tarea asignada (true) o no (false).

        • location: tarea que se va a realizar en el intervalo definido. Por cada tarea, se incluye la siguiente información:

          • color: color configurado en Orquest para la tarea.

          • description: descripción de la tarea definida en Orquest.

          • name: nombre de la tarea en Orquest.

          • shortName: abreviatura de la tarea en Orquest.

          • requiredLevel: nivel de aptitud requerido para realizar la tarea. Va de 0 (sin necesidad de formación) a 3 (nivel máximo de formación) y debe ser previamente configurado en Orquest.

          • priority: prioridad de cobertura de la tarea. Va de 0 (baja) a 5 (alta) y debe ser previamente configurada en Orquest.

          • maxResources: límite de personas para la tarea.

          • type: tipo de tarea, si es fija, variable o no planificable (FIXED, VARIABLE, NON_PLANIFIABLE).

          • shouldAvoidOvercover: si este parámetro es true, la tarea no se sobrecubrirá.

          • system: determina si la tarea ha sido creada por el sistema (true) o por el usuario (false).

          • category: categoría de la tarea previamente configurada en Orquest.

          • product: identificador externo del producto o sección.

          • id: identificador externo de la tarea.

          • metadata: cualquier dato adicional que se haya configurado previamente para la tarea en Orquest. La estructura de los metadatos debe configurarse previamente.

          • zone: lugar físico del servicio (tienda, restaurante, etc.) donde se realiza la tarea.

    • virtual: indica si el empleado es virtual (true) o real (false).

Las asignaciones se agrupan por producto y día.

El objetivo de este endpoint es que un cliente pueda hacer peticiones recurrentes para mantener actualizados sus datos sin tener que realizar procesos de actualización excesivamente complejos. Gracias a esta petición, por tanto, se ofrece un listado que muestra el estado actual de las asignaciones para que solo se tengan que sobreescribir los datos desactualizados.

Por ejemplo, si se borra una asignación para un empleado en un día concreto, la API devuelve las asignaciones de todo el día para el producto implicado.

Consideraciones

Orquest solo almacena los últimos 45 días de cambios incrementales. Si el cliente no realiza una petición de cambios incrementales en ese periodo de tiempo, tendrá que realizar una petición completa de asignaciones.

Debido a la complejidad de los datos, es difícil saber si un elemento ha cambiado cuando se hacen modificaciones masivas. Por ejemplo, al publicar un borrador, las asignaciones pueden cambiar en bloque, pero el resultado parece no haber cambiado porque una asignación idéntica ha reemplazado a otra.

Como las asignaciones se agrupan en conceptos mayores, es posible registrar un cambio en un día sin importar cuántas asignaciones individuales hayan cambiado para ese día. Por eso, es común recibir entidades que parecen no haber cambiado porque forman parte de un concepto mayor que sí ha cambiado.

El uso de este endpoint requiere que la funcionalidad sea activada previamente por el equipo de Orquest, dado su coste de cómputo y memoria al realizar auditorías sobre ciertas entidades. Por tanto, será necesario analizar el caso de uso y gestionar su habilitación.

Enlaces de interés

¿Qué es una asignación?