Consultar asociaciones a servicio activas

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

GET /api/v1/businesses/{businessId}/services/{serviceId}/service-associations/active

Si los datos incluidos en la petición son correctos —tanto el businessId como el serviceId—, la respuesta contendrá todas las asociaciones a servicio cuya fecha de finalización sea igual o posterior a la fecha actual del sistema.

Ejemplo de respuesta

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

[
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-21",
        "splitPresence": true,
        "unplannable": false,
        "roles": [],
        "disponibility": [
            {
                "from": "2021-06-21",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": true
                    }
                ],
                "type": "DAY_TYPE"
            }
        ],
        "service": "0001",
        "person": {
            "name": "John",
            "surname": "Smith",
            "email": "anonymized01@orquest.com",
            "employeeId": "0001",
            "virtual": false
        }
    },
    {
        "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,
                        "available": true
                    }
                ],
                "type": "SHIFT_PATTERN",
                "timeFramePatternId": "f314b8b2-2011-43af",
                "weekStart": 1,
                "blockedType": "NON_EXTENSIBLE_TIME"
            }
        ],
        "service": "0001",
        "person": {
            "name": "Sam",
            "surname": "Cole",
            "employeeId": "0002",
            "virtual": false
        }
    },
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2026-03-11",
        "to": "2027-03-11",
        "splitPresence": true,
        "unplannable": true,
        "card": "123458",
        "roles": [],
        "disponibility": [
            {
                "from": "2026-03-11",
                "to": "2027-03-11",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": true
                    }
                ],
                "type": "DAY_TYPE"
            }
        ],
        "regularCessions": [
            {
                "product": "081818",
                "minutes": 360,
                "days": [
                    "TUESDAY",
                    "FRIDAY"
                ]
            }
        ],
        "service": "0001",
        "person": {
            "name": "Alex",
            "surname": "Bloom",
            "birthday": "2021-12-01",
            "employeeId": "0003",
            "seniority": "2021-12-01",
            "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 cada uno de los empleados y de las asociaciones: tipo de disponibilidad, cesiones regulares, información personal, etc.

Aspectos que tener en cuenta

La petición devolverá todas las asociaciones a servicio y cesiones en las que el ownerProduct coincida con los productos del servicio indicado en la URL.

Si hay cesiones regulares a productos de otros servicios, también aparecerán en la respuesta.

Si el servicio indicado en la URL no existe en el negocio, la petición devolverá un error 404 Not Found, especificando en el mensaje not exits.

Si no hay asociaciones a servicio activas, 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?