Integrar empleados

¿Qué son los empleados?

Tal y como se detalla aquí, los empleados son personas contratadas para desempeñar un trabajo específico dentro de un negocio. La información vinculada a los empleados es toda aquella relativa a asignaciones, aptitudes, fichajes, contratos, asociaciones a servicio, peticiones e incidencias.

¿Qué endpoints están disponibles?

Para integrar empleados a través de la API, hay cuatro endpoints disponibles, organizados en dos dimensiones: si se integra un solo empleado o una lista, y si se necesita el conjunto completo de campos o solo los datos esenciales.

Individual Lista

Simple

PUT /simple/employee

PUT /simple/employees

Complejo

PUT /employee

PUT /employees

Todos los endpoints comparten los campos base de persona, contratos y asociaciones a servicio. Los complejos amplían ese conjunto con:

  • Parámetro lag (requerido): permite enviar solo la información del periodo afectado sin sobrescribir el resto.

  • Flags de comportamiento: partial, ignoreContracts, ignoreServiceAssociations, ignoreWithoutOuterId.

  • Campos adicionales en persona: metadata, virtual.

  • Usuario vinculado (user): crea o actualiza el usuario de acceso a Orquest asociado al empleado.

  • Campos adicionales en asociaciones a servicio: card, roles, regularCessions, metadata.

  • Campos adicionales en contratos: weeklyContract, dailyContract, regularPeriodMultiplier, regularPeriodStartDate, additionalPeriodMultiplier, additionalPeriodStartDate, completed, additionalDailyContract, additionalWeeklyContract, regularCountingDayType, additionalCountingDayType.

Para enviar solo la información de un periodo concreto sin sobrescribir datos ya existentes, se recomienda utilizar un endpoint complejo con lag > 0.

Operaciones

La API de integración permite gestionar el ciclo de vida de un empleado dentro de Orquest: incorporación, posibles traslados, actualizaciones contractuales, etc. Las operaciones más recurrentes se detallan a continuación.

Alta de un empleado

El alta de un empleado en Orquest suele incluir tres bloques de información: datos personales, asociaciones a servicio y contratos.

Para que el empleado sea planificable desde el primer día, la petición debe incluir tanto una asociación a servicio como un contrato vigente: sin asociación a servicio, el empleado no aparece en el servicio ni puede recibir turnos; sin contrato vigente, no puede ser planificado aunque la asociación esté activa.

La asociación a servicio vincula al empleado con un producto (sección), por lo que este debe tener un identificador externo definido en Orquest previamente para que la petición sea exitosa: Configuración de tienda > Productos > Id. externo.

El flujo para dar de alta a un empleado es el siguiente:

  1. Elegir el endpoint según la necesidad: complejo/simple y lista/individual.

  2. Construir la petición con los tres bloques recomendados y sus respectivos campos obligatorios.

    • person: name, surname, employeeId.

    • serviceAssociations: al menos ownerProduct, product y from.

    • contracts: al menos from y el resto de los campos obligatorios según la petición.

  3. Enviar la petición y comprobar la respuesta de la API.

Sin asociación a servicio, el empleado solo aparecerá en el nodo raíz del negocio y no será visible ni planificable en ningún servicio.
Traslado de un empleado

Hay tres tipos de traslados relativos a la asociación a servicio del empleado:

Traslado permanente a otro producto

Implica añadir una nueva asociación a servicio al producto de destino y cerrar la asociación anterior. El cuerpo de la petición debe incluir el objeto serviceAssociations actualizado:

  1. Fecha de finalización (to) de la asociación actual.

  2. Nueva asociación a servicio con ownerProduct y product correspondientes.

Cesión

Implica añadir una asociación a servicio en la que se mantiene el origen (ownerProduct), pero se cambia el destino (product). La cesión debe comenzar y terminar dentro del intervalo de la asociación a servicio principal.

La petición se construye incluyendo la asociación a servicio existente y la cesión como una segunda entrada en serviceAssociations, con ownerProduct apuntando al producto original y product al producto de destino, y con fechas from y to dentro del periodo de la asociación principal.

"serviceAssociations": [
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2025-01-01",
        "to": null
    },
    {
        "ownerProduct": "0001-G",
        "product": "0002-G",
        "from": "2026-03-01",
        "to": "2026-03-31"
    }
]

Cesión regular

Implica que el empleado trabaja de forma recurrente en otro producto siempre los mismos días y durante el mismo tiempo. Se configura mediante el campo regularCessions dentro de la asociación a servicio principal, disponible solo en endpoints complejos.

La petición se construye incluyendo la asociación a servicio con el campo regularCessions, el producto de destino (product), los días de la semana (daysOfWeek) y los minutos de dedicación (minutes).

"serviceAssociations": [
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2025-01-01",
        "regularCessions": [
            {
                "product": "0003-G",
                "minutes": 240,
                "daysOfWeek": ["WEDNESDAY"]
            }
        ]
    }
]
Baja de un empleado

La API no permite la eliminación de empleados del sistema, por lo que la baja se realiza cerrando la relación del empleado con el negocio: sin asociación a servicio vigente, el empleado deja de ser visible y planificable en el servicio; sin contrato vigente, deja de poder recibir turnos. De este modo, el registro histórico se conserva íntegro.

En la petición deberá definirse el campo to con la fecha de finalización de la asociación a servicio y el contrato según corresponda.

El empleado permanece en el sistema con sus datos históricos, lo que permite consultar su actividad pasada aunque ya no esté activo.
Actualizar un contrato

Para modificar los datos de un contrato existente, solo hay que incluir el contrato con los campos actualizados en la petición. Si el empleado tiene más de un contrato, es posible incluir todos los contratos en la petición o usar los endpoints complejos con lag > 0 para acotar el periodo afectado.

Para finalizar un contrato hay dos opciones:

  • Establecer el campo to con la fecha de fin: disponible en todos los endpoints.

  • Establecer el campo completed en true: disponible solo en endpoints complejos. Si se envía true y la fecha de finalización del contrato, se considerará liquidado en esa fecha; si no se incluye fecha de fin, el contrato se considerará liquidado en la fecha de la petición.

Para añadir un nuevo contrato a un empleado que ya tiene contratos, incluirlo junto con los anteriores (peticiones simples o complejas con lag = 0) o enviar solo el nuevo con lag ajustado a su periodo de vigencia (solo endpoints complejos).

Actualizar disponibilidad

El campo disponibility define, dentro de una asociación a servicio o cesión, la disponibilidad del empleado durante un periodo de tiempo concreto.

"serviceAssociations": [
    {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-25",
        "to": null,
        "disponibility": [
            {
                "from": "2021-06-25",
                "to": "2023-06-01",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 600,
                        "duration": 600,
                        "available": true
                    },
                    {
                        "dayType": "MONDAY",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": false
                    }
                ]
            },
            {
                "from": "2026-01-01",
                "ranges": [
                    {
                        "dayType": "ALL",
                        "startMinuteDay": 0,
                        "duration": 1440,
                        "available": true
                    }
                ],
                "type": "SHIFT_PATTERN",
                "timeFramePatternId": "d01e1e08-b2e4-48d1",
                "weekStart": 1,
                "blockedType": "NON_EXTENSIBLE_TIME"
            }
        ]
    }
]

Esto generará dos intervalos de disponibilidad:

  • Del 2021-06-25 al 2023-06-01: disponible todos los días (ALL) de 10:00 a 20:00 hora local, no disponible los lunes (MONDAY).

  • A partir del 2026-01-01: disponibilidad efectiva por el patrón de turnos que se corresponde con el identificador de la petición.

Para eliminar la disponibilidad existente, será necesario enviar un array vacío: "disponibility": [].

Si se envía null o no se incluye el campo, la disponibilidad definida previamente permanece en el sistema.

Todos los endpoints admiten esta operación, tanto los simples como los complejos.

No se permiten intervalos solapados para un mismo tipo de entidad. En consecuencia, no podrán coexistir asociaciones a servicio, contratos o periodos de disponibilidad con fechas que se superpongan.

Preguntas frecuentes

¿Cómo elegir el endpoint correcto?

Se recomienda usar la matriz de la sección ¿Qué endpoints están disponibles? como referencia rápida. Algunos consejos:

  • Cuando sea necesario enviar los datos del usuario vinculado o usar el parámetro lag: usar un endpoint complejo.

  • Cuando solo se necesitan datos personales, contratos y asociaciones: cualquier endpoint es válido, pero los simples requieren menos campos.

  • Si se integran varios empleados a la vez: usar los endpoints de lista.

  • Si es necesario utilizar flags de comportamiento: usar un endpoint complejo.

¿Qué pasa si se crea un empleado sin asociación a servicio?

El empleado solo aparecerá en el nodo principal del negocio. Para recuperarlo, hay dos opciones:

  • Usar cualquiera de los endpoints disponibles para modificar la información del empleado y añadir una asociación a servicio.

  • Vincularlo desde la interfaz gráfica de usuario: Diagrama organizativo > Personas > Ver empleados sin asociación > Recuperar empleado.

¿Cómo funciona el parámetro lag en las peticiones?

El parámetro lag determina el número de días previos a la fecha de la petición que se considerará al gestionar información en Orquest. Para más información sobre su comportamiento, se recomienda visitar el siguiente enlace, donde se ofrecen ejemplos aclaratorios al respecto.

¿Cómo se aplica un tipo de contrato?

Para aplicar un tipo de contrato, es necesario incluir el campo contractTypeId dentro del objeto contracts, considerando las siguientes premisas:

  • Orquest NO aplica tipos de contrato a contratos cuya fecha de fin es anterior a la actual del sistema.

  • El identificador del tipo de contrato debe coincidir con el que se haya configurado a nivel de negocio: Diagrama organizativo > Tipos de contrato > Id. externo.

  • Las restricciones que se hayan definido manualmente desaparecen al aplicar un tipo de contrato.

Si aplica, los siguientes campos del contrato se sobrescriben con los valores establecidos en el tipo de contrato:

  • regularMinutes

  • additionalMinutes

  • numberOfHolidays

  • numberOfPublicHolidays

Si se incluye algún valor distinto de 0, prevalece la información de la petición aunque se aplique el tipo de contrato. Por ejemplo, si el tipo de contrato no tiene días de vacaciones, pero en la petición se envía "numberOfHolidays": 7, se aplicará el tipo de contrato y se establecerán 7 días de vacaciones.

El resto de los campos obligatorios —según la petición— deberán enviarse y se aplicará el valor que se haya indicado.

Tras la integración por API de un contrato con tipo de contrato asociado, los cambios manuales que se realicen desde la interfaz de Orquest podrán provocar que el tipo de contrato deje de aplicarse. En este sentido, el tipo de contrato desaparece si se cambia manualmente algún campo dentro de las siguientes secciones:

  • Definición del contrato.

  • Periodo de control (Caducidad).

  • Vacaciones y festivos.

Si se han creado metadatos de contrato en el negocio, modificar cualquiera de ellos también provocará que desaparezca el tipo de contrato previamente aplicado.

¿Qué ocurre si se envía un empleado que ya existe en el sistema?

Siempre que coincida el identificador externo del empleado, la petición actualizará los datos con la información enviada. Si se incluye el parámetro lag con un valor mayor que 0, solo se modificará la información del periodo cubierto. Si se usa lag = 0 o un endpoint simple, se sobrescribirán todos los datos del empleado para el periodo actual.

Enviar información incompleta con lag = 0 puede eliminar datos existentes. Se recomienda enviar siempre la información completa o usar el lag de forma controlada.
¿Cómo se gestionan las categorías de empleado?

Cuando se envía una categoría de empleado que no existe en el sistema, Orquest crea automáticamente una nueva categoría cuyo nombre e identificador externo coinciden con el valor de personCategory especificado en el cuerpo de la petición.

No obstante, existe la posibilidad de configurar este comportamiento a nivel de negocio para evitar la creación automática y que la API devuelva un error en su lugar, evitando así la generación de duplicados.

Para cambiar el comportamiento por defecto, es necesario avisar al equipo de Orquest y que este realice el cambio en la configuración de negocio.

Para mantener un flujo limpio de integración, se recomienda:

  1. Consultar las categorías de empleado disponibles en el negocio.

  2. Enviar el identificador externo (no el nombre) de la categoría en el campo personCategory de los contratos del empleado.

Errores frecuentes

Mensaje Significado Solución recomendada

cession_no_contained_in_association

Alguna de las cesiones no está contenida en una asociación a servicio.

Verificar que las fechas de la cesión estén dentro del rango de la asociación a servicio correspondiente.

contract_overlapped

Algunos de los contratos están solapados.

Revisar las fechas de inicio y fin de los contratos y evitar que sus periodos se superpongan.

User email is not valid

La dirección de correo electrónico no es válida.

Comprobar el formato del correo electrónico (debe seguir el estándar RFC 5321).

role_not_valid

El rol no es válido o no existe.

Verificar que el rol enviado esté configurado en el negocio de Orquest.

Service or node forbidden

El servicio no existe o no ha sido indicado.

Comprobar que el identificador de servicio enviado existe en Orquest.

ContractType [] not found in business

El tipo de contrato no existe.

Verificar que el identificador externo del tipo de contrato sea válido y esté configurado.

not_valid_metadata

Los metadatos no son válidos, bien por estructura o por configuración.

Comprobar que los metadatos enviados coincidan con la configuración del negocio en Orquest.

overlapped_associations

Algunas asociaciones a servicio están solapadas.

Revisar las fechas de inicio y fin de las asociaciones y asegurarse de que no se solapan para el mismo producto.

interval_disponibility_out_of_association

El intervalo de disponibilidad no está contenido por la asociación a servicio.

Asegurarse de que las fechas del intervalo de disponibilidad estén dentro de las fechas de la asociación a servicio.

interval_day_overlapped

Algunos intervalos de disponibilidad están solapados.

Revisar los rangos de disponibilidad y eliminar los solapamientos entre intervalos.