Crear o modificar lista de empleados (complejo)

Este endpoint es uno de los más complejos de Orquest, pues permite no solo crear o modificar la lista de empleados como tal, sino también todos los datos vinculados a estos: usuarios, contratos, asociaciones a servicio, etc.

PUT /api/v2/businesses/{businessId}/employees

A continuación, se expone una explicación detallada de cada uno de los campos que pueden conformar el cuerpo de la petición, siendo algunos de ellos obligatorios para que esta se realice de manera exitosa.

Los campos obligatorios están marcados con un asterisco (*).

Cuerpo de la petición

Análisis del JSON 
"business": "string",
"lag": 0,
"partial": true,
"ignoreWithoutOuterId": false,
"ignoreServiceAssociations": false,
"ignoreContracts": false,
Detalles

  • business*: identificador configurado en Orquest para el negocio.

  • lag*: número de días previos a la fecha actual que se consideran al gestionar la petición.

  • partial: determina si se quiere resetear la información aplicada por los tipos de contrato. Es recomendable activarlo siempre.

  • ignoreWithoutOuterId: determina si se tienen en cuenta las entidades sin identificador de negocio.

  • ignoreServiceAssociations: determina si se actualizan las asociaciones a servicio del empleado. En caso de establecer true, no es necesario añadir información sobre asociaciones a servicio en la petición.

  • ignoreContracts: determina si se actualizan los contratos del empleado. En caso de establecer true, no es necesario añadir información sobre contratos en la petición.

Objeto person*

Incluye los datos personales del empleado identificado a través de su employeeId.

 
"person": {
      "name": "string",
      "surname": "string",
      "group": "string",
      "email": "string",
      "birthday": "string",
      "employeeId": "string",
      "metadata": {},
      "seniority": "string",
      "aptitudes": [
        {
          "productId": "string",
          "aptitudes": [
            {
              "locationId": "string",
              "level": 0
            }
          ]
        }
      ],
      "virtual": false
    }
Detalles

  • 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, con formato correcto.

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

  • employeeId*: identificador del empleado en el sistema externo.

  • metadata: datos adicionales sobre el empleado. La estructura de este campo debe ser previamente configurada a nivel de negocio.

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

  • aptitudes: conjunto de capacidades que posee el empleado en un producto determinado. Para añadir las aptitudes en un producto o sección concreta, deben especificarse los siguientes campos:

    • productId *: identificador externo del producto al que está vinculada la aptitud.

    • aptitudes *: cada una de las aptitudes que se definen para el empleado en el producto indicado. Será necesario añadir los siguientes datos:

      • locationId*: identificador de la tarea a la que está vinculada la aptitud.

      • level*: nivel de competencia en dicha tarea en un rango de 0 (no competente) a 3 (experto).

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

Objeto user

Incluye los datos que vinculan al empleado con un usuario de la aplicación de Orquest.

 
"user": {
      "username": "string",
      "email": "string",
      "nodes": [
        0
      ],
      "roles": [
        "string"
      ]
    }
Detalles

  • username* : nombre del usuario. Debe ser único.

  • email*: email del usuario. Debe ser único.

  • nodes: lista (array) de identificadores de nodos de Orquest en los que el empleado tendrá acceso como usuario. Si tiene acceso al nodo raíz, por defecto tendrá acceso al resto de los nodos del árbol organizativo.

  • roles: lista (array) de roles que se atribuirán al usuario una vez creado. Estos roles se configuran a nivel de negocio.

Objeto serviceAssociations

Incluye la información relativa a las asociaciones a servicio establecidas para el empleado.

 
"serviceAssociations": [
      {
        "ownerProduct": "string",
        "product": "string",
        "from": "string",
        "to": "string",
        "splitPresence": true,
        "unplannable": true,
        "card": "string",
        "roles": [
          "string"
        ],
        "disponibility": [
          {
            "from": "string",
            "to": "string",
            "ranges": [
              {
                "dayType": "string",
                "startMinuteDay": 0,
                "duration": 0
              }
            ]
          }
        ],
        "regularCessions": [
          {
            "product": "string",
            "minutes": 0,
            "days": [
              "string"
            ]
          }
        ],
        "metadata": {},
        "id": "string"
      }
    ]
Detalles

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

  • product*: identificador del producto o sección donde va a trabajar el empleado. Puede ser igual al ownerProduct.

  • 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 (array) de identificadores de roles que se atribuirán al empleado en esta asociación a servicio.

  • disponibility: disponibilidad del empleado dependiendo del tipo de día durante un período concreto. Si no se define, la disponibilidad de un empleado por defecto es 24/7, teniendo en cuenta las restricciones de su contrato. Para cambiarla, será necesario enviar los siguientes datos:

    • 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 establecerse como null siempre que la asociación a servicio también lo sea.

    • ranges*: lista (array) de disponibilidades para cada tipo de día. Estos rangos deben estar definidos en el contrato e incluyen los siguientes parámetros:

      • dayType*: tipo de día al que se aplica la disponibilidad. Las opciones disponibles del sistema son las siguientes: ALL, WEEKENDS, WORKED, HOLIDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY. No obstante, se pueden definir otros tipos de día a nivel de negocio.

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

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

  • 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 deberán definir a través de los siguientes campos:

    • product*: identificador 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 (array) de tipos de día que el empleado trabajará cedido.

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

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

Objeto contracts

Incluye la información relativa a los contratos que se aplican al empleado, en términos de horas trabajadas, limitaciones laborales, etc.

 
"contracts": [
      {
        "from": "string",
        "to": "string",
        "regularMinutes": 0,
        "weeklyContract": true,
        "dailyContract": true,
        "countingDays": "string",
        "additionalMinutes": 0,
        "regularControlPeriod": "string",
        "regularPeriodMultiplier": 1,
        "regularPeriodStartDate": "string",
        "additionalControlPeriod": "string",
        "additionalPeriodMultiplier": 1,
        "additionalPeriodStartDate": "string",
        "calendarDaysOff": true,
        "numberOfHolidays": 0,
        "numberOfPublicHolidays": 0,
        "weeklyDaysInvolved": "string",
        "metadata": {},
        "costPerHour": 0,
        "personCategory": "string",
        "id": "string",
        "contractTypeId": "string",
        "completed": true
      }
    ]
Detalles

  • from*: fecha de inicio del contrato en formato yyyy-MM-dd.

  • to: fecha de finalización del contrato en formato yyyy-MM-dd. Puede enviarse como null si no hay una fecha de fin establecida.

  • regularMinutes*: número de minutos que se espera que el empleado trabaje según los términos de su contrato laboral. Este campo depende del periodo de control que se establezca para el contrato: anual, semanal o diario.

  • weeklyContract*: determina si el contrato se define de manera semanal (true) o anual (false).

  • dailyContract: determina si el contrato se define de manera diaria. Si el contrato no es diario ni semanal, se asume que es anual.

  • countingDays: en un contrato diario, indica qué días computan como trabajados. Su valor puede ser MONDAY_SUNDAY, MONDAY_SATURDAY o LABOR_DAYS.

  • additionalMinutes*: número de minutos adicionales que el empleado puede trabajar según los términos de su contrato laboral y que excede del tiempo regular del mismo. Este campo depende del periodo de control que se establezca para el contrato: anual, semanal o diario.

  • regularControlPeriod*: periodo de control para las horas regulares establecidas en el contrato. Puede ser WEEKLY, MONTHLY o YEARLY.

  • regularPeriodMultiplier: índice multiplicador para regularControlPeriod. Por ejemplo, si se establece 2 con regularControlPeriod semanal, determinaría que se trata de una quincena. Su valor por defecto es 1 y admite valor null o cualquier número entero igual o mayor que 1.

  • regularPeriodStartDate: fecha de inicio de regularControlPeriod en formato yyyy-MM-dd. Esta fecha se tiene en cuenta para un valor de regularPeriodMultiplier mayor que 1; si el valor del multiplicador es igual a 1, la fecha se ignora.

  • additionalControlPeriod*: periodo de control para las horas complementarias. Puede ser WEEKLY, MONTHLY o YEARLY.

  • additionalPeriodMultiplier: índice multiplicador para additionalControlPeriod. Por ejemplo, si se establece 2 con additionalControlPeriod semanal, determinaría que se trata de una quincena. Su valor por defecto es 1 y admite valor null o cualquier número entero igual o mayor que 1.

  • additionalPeriodStartDate: fecha de inicio de additionalControlPeriod en formato yyyy-MM-dd. Esta fecha se tiene en cuenta para un valor de additionalPeriodMultiplier mayor que 1; si el valor del multiplicador es igual a 1, la fecha se ignora.

  • calendarDaysOff*: determina si las vacaciones serán procesadas en días naturales (true) o laborables (false).

  • numberOfHolidays*: número de días de vacaciones que tiene el empleado en su contrato.

  • numberOfPublicHolidays*: número de días festivos que tiene el empleado en su contrato.

  • weeklyDaysInvolved*: días de la semana que serán computables. Este campo puede definirse como MONDAY_SUNDAY, MONDAY_SATURDAY.

  • metadata: cualquier dato adicional relativo al contrato. La estructura de estos metadatos debe ser configurada previamente.

  • costPerHour: coste del empleado por hora trabajada.

  • personCategory*: identificador externo de la categoría del empleado.

  • id: identificador externo del contrato. Es muy recomendable proporcionar este campo. De lo contrario, el sistema intentará hacer coincidir los objetos dados. La identificación debe ser única y debe ser la misma siempre. Limitado a 200 caracteres.

  • contractTypeId: identificador del tipo de contrato que se aplica. Si se añade, las características del contrato serán sobrescritas por aquellas del tipo de contrato. Si no se especifica, se podrán aplicar filtros de tipo de contrato para asignarle uno.

  • completed: determina si el contrato está liquidado o no. 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.

Ejemplo de la petición

Una vez realizado el análisis de los distintos campos, se muestra un ejemplo del cuerpo de la petición:

[
  {
    "business": "BUSINESSID",
    "lag": 0,
    "partial": false,
    "ignoreWithoutOuterId": false,
    "ignoreServiceAssociations": false,
    "ignoreContracts": false,
    "person": {
      "name": "Brian",
      "surname": "Cohen",
      "group": "01",
      "email": "brian@orquest.com",
      "birthday": "1987-12-01",
      "employeeId": "021298521",
      "metadata": {
        "language": "english",
        "nationality": "scottish"
      },
      "seniority": "2021-12-01",
      "aptitudes": [
        {
          "productId": "C14",
          "aptitudes": [
            {
              "locationId": "101",
              "level": 3
            },
            {
              "locationId": "102",
              "level": 2
            }
          ]
        }
      ],
      "virtual": false
    },
    "user": {
      "username": "brian",
      "email": "brian@cohen.com",
      "nodes": [
        10, 14
      ],
      "roles": [
        "admin"
      ]
    },
    "serviceAssociations": [
      {
        "ownerProduct": "C14",
        "product": "C14",
        "from": "2024-04-11",
        "to": null,
        "splitPresence": true,
        "unplannable": false,
        "card": "C14A658",
        "roles": [
          "manager"
        ],
        "disponibility": [
          {
            "from": "2024-04-11",
            "to": null,
            "ranges": [
              {
                "dayType": "ALL",
                "startMinuteDay": 600,
                "duration": 300
              }
            ]
          }
        ],
        "regularCessions": [
          {
            "product": "C15",
            "minutes": 60,
            "days": [
              "MONDAY"
            ]
          }
        ],
        "metadata": {
          "restAllowed": true,
          "time": 15,
          "position": "free"
        },
        "id": "asb1415"
      }
    ],
    "contracts": [
      {
        "from": "2024-04-11",
        "to": null,
        "regularMinutes": 2400,
        "weeklyContract": true,
        "countingDays": "MONDAY_SUNDAY",
        "additionalMinutes": 360,
        "regularControlPeriod": "WEEKLY",
        "regularPeriodMultiplier": 1,
        "regularPeriodStartDate": "2024-04-11",
        "additionalControlPeriod": "WEEKLY",
        "additionalPeriodMultiplier": 1,
        "additionalPeriodStartDate": "2024-04-11",
        "calendarDaysOff": true,
        "numberOfHolidays": 25,
        "numberOfPublicHolidays": 7,
        "weeklyDaysInvolved": "MONDAY_SUNDAY",
        "metadata": {
          "full": true,
          "days": 215,
          "taxProfit": "none"
        },
        "costPerHour": 200.34,
        "personCategory": "DE125",
        "id": "321abc654def",
        "contractTypeId": "07H",
        "completed": false
      }
    ]
  }
]

Aspectos que tener en cuenta

Cada entidad de la lista tiene su propio estado, es decir, cada elemento de la lista tiene su propio conjunto de atributos o propiedades que se pueden actualizar de manera independiente. No se permiten más de 30 elementos en el cuerpo de la petición.

Cada entidad generará una operación atómica que se puede revertir de forma automática si hay errores: el error se mostrará en la respuesta de la petición.

Si se incluyen datos del objeto user, se valida la existencia de ese usuario en Orquest, de modo que se establecen los siguientes escenarios:

  • Si el usuario no existe, se crea y se vincula al empleado.

  • Si el usuario existe y ya está vinculado al empleado de la petición, se actualiza la información.

  • Si el usuario existe y está vinculado a otro empleado, la operación se cancela y devuelve HTTP 409 - Conflict, señalando el conflicto con los detalles del error en el cuerpo de la respuesta.

Si la categoría de empleado (personCategory) especificada en el cuerpo de la petición no existe en el sistema, se crea automáticamente una nueva categoría (Configuración de negocio > Categorías de empleado). En este caso, el nombre y el identificador externo de la nueva categoría coincidirán con el valor proporcionado en este campo. Por lo tanto, es recomendable revisar las categorías existentes antes de realizar la petición para evitar la creación innecesaria de categorías adicionales.

Enlaces de interés

¿Qué es un empleado?

¿Qué es una asociación a servicio?

¿Qué es un contrato? ¿Y un tipo de contrato?

¿Cómo integrar empleados?