Consultar asociaciones a servicio por empleado

Este endpoint permite consultar las asociaciones a servicio de un empleado.

GET /api/v1/business/{businessId}/person/{personId}/service-associations

Si los datos incluidos en la petición son correctos —tanto el businessId como el personId—, la respuesta contendrá todas las asociaciones a servicio del empleado pasado por parámetro.

Ejemplo de respuesta

A continuación, se muestra un ejemplo de respuesta:

[
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-19",
        "splitPresence": true,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2021-06-19",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 600,
                        "duration": 600,
                        "available": true
                    },
                    {
                        "dayType": "TUESDAY",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": false
                    }
                ],
                "type": "DAY_TYPE"
            }
        ],
        "regularCessions": [
            {
                "product": "0003-G",
                "minutes": 240,
                "days": [
                    "TUESDAY"
                ]
            }
        ],
        "service": "0001",
        "person": {
            "name": "Olivia",
            "surname": "García",
            "group": "",
            "email": "",
            "employeeId": "1006350",
            "virtual": false
        }
    },
    {
        "ownerProduct": "0001-G",
        "product": "0002-G",
        "from": "2025-01-21",
        "to": "2025-01-28",
        "splitPresence": false,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2025-01-21",
                "to": "2025-01-28",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 600,
                        "duration": 600,
                        "available": true
                    }
                ],
                "type": "DAY_TYPE"
            }
        ],
        "service": "0002",
        "person": {
            "name": "Olivia",
            "surname": "García",
            "group": "",
            "email": "",
            "employeeId": "1006350",
            "virtual": false
        }
    }
]
Detalles

  • ownerProduct*: identificador externo del producto o sección al que pertenece el empleado.

  • product*: identificador externo del producto o sección donde va a trabajar el empleado. Puede ser igual al ownerProduct; si es distinto, se trata de una cesión.

  • from*: fecha de inicio de la asociación a servicio en formato yyyy-MM-dd.

  • to: fecha de finalización de la asociación a servicio en formato yyyy-MM-dd. Puede ser null, indicando que no hay fecha de fin establecida.

  • splitPresence: determina si se trata de un turno partido. El valor por defecto es true.

  • unplannable: determina si el empleado será ignorado por el planificador, por lo que deberá planificarse a mano. El valor por defecto es false.

  • card: identificador de la tarjeta del empleado en sistemas de fichajes.

  • roles: lista de identificadores de roles que se atribuirán al empleado en esta asociación a servicio.

  • disponibility: disponibilidad del empleado durante un intervalo concreto.

    • from*: fecha de inicio del periodo de la disponibilidad en formato yyyy-MM-dd.

    • to: fecha de finalización del periodo de la disponibilidad en formato yyyy-MM-dd. Puede ser null siempre que la asociación a servicio también lo sea.

    • ranges: lista de disponibilidades por tipo de día. Para cada tipo, incluye la siguiente información:

      • dayType*: tipo de día al que se aplica la disponibilidad. Puede ser un tipo de día del sistema (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) o uno definido a nivel de negocio.

      • startMinuteDay*: inicio de la disponibilidad en minutos a partir de las 00:00 en hora local. Por ejemplo, 600 para las 10:00.

      • duration*: duración del rango en minutos.

      • available: determina si el empleado está disponible (true) o no disponible (false) en el rango y tipo de día indicados. El valor por defecto es true.

    • type: tipo de disponibilidad efectiva: DAY_TYPE, SHIFT_PATTERN o CALENDAR.

    • timeFramePatternId: identificador interno del patrón de turno o disponibilidad aplicado. Solo para disponibilidad de tipo SHIFT_PATTERN.

    • weekStart: semana de inicio. Solo para disponibilidad de tipo SHIFT_PATTERN.

    • blockedType: tipo de bloqueo aplicado al patrón (NONE, EXTENSIBLE_WORK, NON_EXTENSIBLE_WORK, EXTENSIBLE_TIME, NON_EXTENSIBLE_TIME, DAILY_WORKED, FREE, WORKING_HOURS). Solo para disponibilidad de tipo SHIFT_PATTERN.

  • regularCessions: determina si el empleado trabaja algunos días a la semana en otro producto o sección de manera sistemática. En caso de que existan cesiones regulares, se definen a través de los siguientes campos:

    • product: identificador externo del producto o sección de destino donde el empleado va a trabajar.

    • minutes: número de minutos que el empleado trabajará en el producto o sección de destino.

    • days: lista de tipos de día que el empleado trabajará cedido. Posibles valores: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.

  • metadata: cualquier dato adicional relativo a la asociación a servicio. La estructura de estos metadatos debe ser configurada previamente por el equipo de Orquest.

  • id: identificador externo de la asociación a servicio.

  • service: identificador externo del servicio.

  • person: datos básicos del empleado:

    • name: nombre del empleado.

    • surname: apellido(s) del empleado.

    • group: si se han definido grupos dentro del negocio, el grupo al que pertenece el empleado.

    • email: el email de empleado, si se ha establecido uno.

    • birthday: la fecha de nacimiento con formato yyyy-MM-dd.

    • employeeId*: identificador externo del empleado.

    • metadata: datos adicionales sobre el empleado. La estructura de este campo debe ser previamente configurada por el equipo de Orquest.

    • seniority: antigüedad del empleado en formato yyyy-MM-dd.

    • virtual: determina si se trata de un empleado real o uno virtual utilizado, por ejemplo, para realizar simulaciones.

Como se puede ver en el ejemplo, los datos de la respuesta dependen de la información que se haya definido para el empleado. En este caso, hay una asociación a servicio al producto 0001-G desde el 2021-06-19, con una cesión regular de cuatro horas los martes en 0003-G y una cesión desde el 2025-01-21 al 2025-01-28 al producto 0002-G.

Aspectos que tener en cuenta

La petición devolverá todas las asociaciones a servicio y cesiones del empleado. Si hay cesiones regulares definidas dentro de alguna de las asociaciones, también aparecerán en la respuesta.

Si el identificador de empleado indicado en la URL no existe en el negocio, la petición devolverá un error 404 Not Found, especificando en el mensaje Employee not found.

Si no hay asociaciones a servicio para el empleado (ni activas ni finalizadas), la petición devolverá un array vacío [].

Disponibilidad efectiva

Dentro de cada intervalo de disponibilidad, es posible la convivencia entre rangos de disponibilidad por tipo de día y disponibilidad efectiva por patrón de turnos o calendario de asignaciones. El tipo (type) indicará cuál es la disponibilidad efectiva en cada caso: DAY_TYPE, SHIFT_PATTERN o CALENDAR.

Ver ejemplo 
[
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-25",
        "splitPresence": true,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2025-11-02",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 0,
                        "duration": 1440
                    }
                ],
                "type": "SHIFT_PATTERN",
                "timeFramePatternId": "f314b8b2-2011-43af",
                "weekStart": 1,
                "blockedType": "NON_EXTENSIBLE_TIME"
            }
        ],
        "service": "0001",
        "person": {
            "name": "Sam",
            "surname": "Cole",
            "employeeId": "0002",
            "virtual": false
        }
    }
]

En este ejemplo, aunque el empleado tenga disponibilidad por defecto todos los días (ALL) de 00:00 a 00:00, su disponibilidad efectiva está definida por patrón de turnos (SHIFT_PATTERN), lo que hace que también se devuelvan los demás campos relacionados con este tipo de disponibilidad: timeFramePatternId, weekStart y blockedType.

Para consultar los detalles de la disponibilidad efectiva, se recomienda utilizar las siguientes peticiones:

Enlaces de interés

¿Qué es una asociación a servicio? ¿Y una cesión?

¿Qué es la disponibilidad de un empleado?