Quiero 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.

¿Cómo integrar empleados?

Para integrar empleados a través de la API, hay diferentes endpoints disponibles. A continuación, se presenta un desglose de distintos escenarios y los endpoints que son útiles en cada uno de ellos.

Añadir una lista de empleados

Para registrar nuevos empleados en el sistema, se pueden utilizar los siguientes endpoints:

Teniendo en cuenta que cada una de las opciones requiere unos campos específicos, la elección de un endpoint u otro dependerá de la información que se quiera integrar en Orquest.

Modificar los datos de una lista de empleados ya existente

Los endpoints disponibles para realizar modificaciones en una lista de empleados son los mismos que en el escenario anterior:

La versión compleja incluye más datos que la simple y permite, entre otras cosas, incorporar el parámetro lag, esencial para determinar el número de días previos a la petición que se considerarán al gestionar la información enviada.

En esta sección se exponen algunas de las operaciones que se pueden realizar en la integración de empleados y que tienen en cuenta dicho parámetro.

Añadir un empleado

Para incorporar un nuevo empleado al sistema, se pueden utilizar los endpoints ya expuestos en los escenarios anteriores, incluyendo solo los datos del empleado que se desea integrar:

Además, se pueden utilizar los siguientes endpoints:

Teniendo en cuenta que cada una de las opciones requiere unos campos específicos, la elección de un endpoint u otro dependerá de la información que se quiera integrar en Orquest.

Modificar los datos de un empleado

Todos los endpoints de los escenarios anteriores permiten modificar la información de un empleado:

Cada uno de estos endpoints requiere información específica del empleado que se va a integrar. Por ello, es recomendable revisar qué información es obligatoria y recabarla antes de realizar la petición.

¿Qué operaciones se pueden realizar en la integración de empleados?

Teniendo en cuenta la complejidad de los endpoints de empleados expuestos anteriormente, la API de Orquest permite realizar operaciones concretas como las que se exponen a continuación:

  • Añadir, modificar o eliminar un contrato.

  • Añadir, modificar o eliminar una asociación a servicio.

  • Añadir, modificar o eliminar una cesión.

  • Añadir, modificar o eliminar disponibilidad.

Añadir un nuevo contrato

Para agregar un nuevo contrato a un empleado que ya tiene contratos anteriores, las opciones disponibles son las siguientes:

  • Enviar toda la información

  • Enviar solo la nueva información

Utilizando cualquiera de los endpoints, se incluye en el cuerpo de la petición tanto la información de los contratos anteriores como la del nuevo contrato.

Se envían los datos del nuevo contrato, sin incluir contratos anteriores, considerando el parámetro lag con un valor que aborde el periodo de vigencia del nuevo contrato. En este caso, el valor del lag siempre será mayor que 0.

Al tener que incluir el parámetro lag, los endpoints que se pueden utilizar son los siguientes:

Modificar la información de un contrato

Las opciones disponibles en este escenario varían en función de los datos que se hayan definido para el empleado.

  • Si el empleado solo tiene un contrato, es decir, el que se va a modificar, se puede enviar la información desde cualquiera de los endpoints disponibles. De este modo, se sobrescriben los datos del contrato.

  • Si hay datos de contratos anteriores, puede enviarse toda la información o solo la información que se vaya a modificar:

  • Enviar toda la información

  • Enviar solo la nueva información

Se puede utilizar cualquiera de los endpoints incluyendo en el cuerpo de la petición tanto la información anterior —que no se altera— como la del contrato que se quiere modificar.

Se envían los nuevos datos del contrato considerando el parámetro lag con un valor que aborde el periodo de vigencia del contrato que se quiere modificar. En estos casos, el lag siempre es mayor que 0.

Al tener que incluir el parámetro lag, los endpoints que se pueden utilizar son los siguientes:

Eliminar un contrato

Para eliminar un contrato del sistema, basta con no incluir dicho elemento en el cuerpo de la petición cuando se envíe la información actualizada. La API de Orquest sobrescribirá los datos, excluyendo del sistema aquellos elementos que no se encuentren en la petición.

Al igual que en los escenarios anteriores, puede enviarse toda la información actualizada desde cualquiera de los endpoints disponibles o utilizar peticiones con el parámetro lag para enviar solo la información del periodo que contempla el contrato que se desea eliminar.

Añadir, modificar o eliminar una asociación a servicio

Para realizar cualquiera de estas operaciones relativas a las asociaciones a servicio, es necesario seguir los mismos pasos que con la integración de contratos.

De este modo, puede enviarse toda la información actualizada desde cualquiera de los endpoints disponibles o utilizar las peticiones complejas con el parámetro lag para enviar solo la información del periodo que contempla las asociaciones a servicio que se quieran añadir, modificar o eliminar.

Añadir, modificar o eliminar una cesión

Una cesión, tal y como se detalla aquí, se entiende como una asociación a servicio en la que el empleado estará relacionado con el producto al que pertenece (ownerProduct) y, de manera temporal, con un producto al que ha sido cedido (product).

Para añadir o modificar una cesión, se siguen los mismos pasos expuestos anteriormente, considerando que la cesión debe comenzar y terminar dentro del intervalo definido por una asociación a servicio. En el siguiente ejemplo, se muestra el cuerpo de la petición que incluye una asociación a servicio y una cesión (mismo ownerProduct, diferente product) dentro del periodo de la asociación a servicio.

Ver ejemplo 
"serviceAssociations": [
      {
        "ownerProduct": "0001-G",
        "product": "0001-G",
        "from": "2021-06-25",
        "to": null,
        "splitPresence": null,
        "unplannable": null,
        "card": null,
        "roles": null
      },
      {
        "ownerProduct": "0001-G",
        "product": "0002-G",
        "from": "2024-03-01",
        "to": "2024-03-31",
        "splitPresence": null,
        "unplannable": null,
        "card": null,
        "roles": null
      }
]

Para eliminar una cesión, basta con no incluir los datos relativos a este elemento en el cuerpo de la petición cuando se envíe la información actualizada.

Todos los endpoints de empleados admiten esta operación:

  • Incluyendo toda la información (simples o complejos con lag = 0).

  • Incluyendo solo la información cambiante (complejos con lag > 0).

Añadir, modificar o eliminar disponibilidad

El campo disponibility indica, dentro de una asociación a servicio o cesión, la disponibilidad del empleado dependiendo del tipo de día durante un periodo de tiempo concreto. Para añadir o modificar periodos de disponibilidad de un empleado, será necesario enviar los datos obligatorios para este campo dentro de la asociación a servicio o cesión.

Ver ejemplo 
  "serviceAssociations": [
    {
      "ownerProduct": "0001-G",
      "product": "0001-G",
      "from": "2021-06-25",
      "to": null,
      "splitPresence": null,
      "unplannable": null,
      "card": null,
      "roles": null,
      "disponibility": [
        {
          "from": "2021-06-25",
          "to": "2023-06-01",
          "ranges": [
            {
              "dayType": "ALL",
              "startMinuteDay": 600,
              "duration": 600
            },
            {
              "dayType": "MONDAY",
              "startMinuteDay": 450,
              "duration": 600
            }

          ]
        },
        {
          "from": "2023-06-02",
          "to": null,
          "ranges": [
            {
              "dayType": "ALL",
              "startMinuteDay": 660,
              "duration": 600
            },
            {
              "dayType": "MONDAY",
              "startMinuteDay": 600,
              "duration": 600
            }

          ]
        }
      ]
    }
  ]

Para eliminar un periodo de disponibilidad, basta con no incluir los datos relativos a este elemento en el cuerpo de la petición cuando se envíe la información actualizada.

Todos los endpoints de empleados admiten esta operación:

  • Incluyendo toda la información (simples o complejos con lag = 0).

  • Incluyendo solo la información cambiante (complejos con lag > 0).

Posibles mensajes de error

Algunos de los mensajes de error que pueden aparecer en la integración de empleados son los siguientes:

Mensaje Significado

cession_no_contained_in_association

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

contract_overlapped

Algunos de los contratos están solapados.

email_not_valid

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

role_not_valid

El rol no es válido o no existe.

has_not_service_id

El servicio no existe o no ha sido indicado.

has_not_valid_type

El tipo no existe o no ha sido indicado.

not_valid_person

El objeto person no es válido.

not_valid_metadata

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

overlapped_associations

Algunas asociaciones a servicio están solapadas.

service_not_exits

El servicio no es válido o no existe.

interval_disponibility_out_of_association

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

person_advice

El objeto person no tiene datos válidos.

interval_day_overlapped

Algunos intervalos de disponibilidad están solapados.

Preguntas frecuentes

¿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:

  • Utilizar 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.

Si aplica, los diferentes campos del contrato se sobrescribirán con los valores establecidos en el tipo de contrato.

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.

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.