Obtener disponibilidad efectiva por servicio

Este endpoint permite consultar la disponibilidad efectiva de los empleados de un servicio en un periodo de tiempo no superior a 31 días.

GET /api/v1/businesses/{businessId}/services/{serviceId}/effectiveDisponibilities?from={yyyy-MM-dd}&to={yyyy-MM-dd}

Si los datos incluidos en la petición son correctos —tanto el businessId como el serviceId—, la respuesta contendrá la disponibilidad de todos los empleados del servicio, detallando la siguiente información:

serviceId: identificador externo del servicio.
from: fecha de inicio del periodo para el que se realiza la petición.
to: fecha de fin del periodo para el que se realiza la petición.
disponibilityIntervals: conjunto de intervalos de disponibilidad definidos dentro del periodo de tiempo consultado.
- day: día de la disponibilidad.
- type: tipo de disponibilidad definido para este día. Los posibles valores son DAY_TYPE (tipo de día), SHIFT_PATTERN (patrones de turnos), AVAILABILITY_PATTERN (patrón de disponibilidad) y CALENDAR (calendario de asignaciones).
- personId: identificador externo del empleado al que corresponde la disponibilidad.
- free: si se trata de un día libre (true) o no (false).
- intervals: intervalos de la disponibilidad.
  - from: fecha y hora de inicio de la disponibilidad.
  - to: fecha y hora de fin de la disponibilidad.

A continuación, se muestra un ejemplo de la petición:

GET /api/v1/businesses/BUSINESSID/services/SERVICEID/effectiveDisponibilities?from=2025-05-01&to=2025-05-03

Fragmento de respuesta:

{
    "serviceId": "SERVICEID",
    "from": "2025-05-01",
    "to": "2025-05-03",
    "disponibilityIntervals": [
        {
            "day": "2025-05-01",
            "type": "DAY_TYPE",
            "personId": "XX1",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-01T08:00:00.000Z",
                    "to": "2025-05-01T13:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-02",
            "type": "DAY_TYPE",
            "personId": "XX1",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-02T08:00:00.000Z",
                    "to": "2025-05-02T13:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-03",
            "type": "DAY_TYPE",
            "personId": "XX1",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-03T08:00:00.000Z",
                    "to": "2025-05-03T13:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-01",
            "type": "CALENDAR",
            "personId": "XX2",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-01T07:00:00.000Z",
                    "to": "2025-05-01T08:00:00.000Z"
                },
                {
                    "from": "2025-05-01T13:00:00.000Z",
                    "to": "2025-05-01T18:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-02",
            "type": "CALENDAR",
            "personId": "XX2",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-02T07:00:00.000Z",
                    "to": "2025-05-02T08:00:00.000Z"
                },
                {
                    "from": "2025-05-02T13:00:00.000Z",
                    "to": "2025-05-02T18:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-03",
            "type": "CALENDAR",
            "personId": "XX2",
            "free": true,
            "intervals": []
        },
        {
            "day": "2025-05-01",
            "type": "AVAILABILITY_PATTERN",
            "personId": "XX3",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-01T16:00:00.000Z",
                    "to": "2025-05-01T22:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-02",
            "type": "AVAILABILITY_PATTERN",
            "personId": "XX3",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-02T16:00:00.000Z",
                    "to": "2025-05-02T22:00:00.000Z"
                }
            ]
        },
        {
            "day": "2025-05-03",
            "type": "AVAILABILITY_PATTERN",
            "personId": "XX3",
            "free": false,
            "intervals": [
                {
                    "from": "2025-05-03T16:00:00.000Z",
                    "to": "2025-05-03T22:00:00.000Z"
                }
            ]
        }
    ]
}

Tal y como se aprecia en el ejemplo, la petición devolverá la disponibilidad de cada uno de los empleados del servicio para cada día del periodo indicado en la URL.

Aspectos que tener en cuenta

Si un empleado tiene varios intervalos de disponibilidad definidos para el rango especificado en la URL, la petición devolverá las especificaciones de cada uno de ellos.

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

Si el intervalo de tiempo indicado en la URL es superior a 31 días, la petición devolverá un error 400 Bad Request, especificando en el mensaje The maximum days to calculate must be 31 days.

Si no hay intervalos de disponibilidad definidos para el servicio o para el rango de fechas de la petición, el campo disponibilityIntervals contendrá un array vacío [].

Enlaces de interés

¿Qué es la disponibilidad de un empleado?