Crear o actualizar empleado (simplificado)

Este endpoint es una simplificación de Crear o actualizar empleado (complejo). Permite crear o modificar un empleado incluyendo solo información acerca de la persona, sus asociaciones a servicio y sus contratos.

PUT /api/v1/businesses/{businessId}/import/simple/employee

A continuación, se expone una explicación detallada de cada uno de los campos que pueden conformar el cuerpo de la petición.

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

Los valores admitidos para los campos de tipo Enum se muestran en el desplegable de detalles.

Cuerpo de la petición

Análisis del JSON

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": "yyyy-MM-dd",
      "employeeId": "string",
      "seniority": "yyyy-MM-dd"
    }
Detalles

  • name*: nombre del empleado.

  • surname*: apellido(s) del empleado.

  • group: 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.

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

Objeto serviceAssociations

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

 
"serviceAssociations": [
      {
        "ownerProduct": "string",
        "product": "string",
        "from": "yyyy-MM-dd",
        "to": "yyyy-MM-dd",
        "splitPresence": true,
        "unplannable": true,
        "disponibility": [
          {
            "from": "yyyy-MM-dd",
            "to": "yyyy-MM-dd",
            "ranges": [
              {
                "dayType": "string",
                "startMinuteDay": 0,
                "duration": 0,
                "available": true
              }
            ],
            "type": "Enum",
            "timeFramePatternId": "string",
            "weekStart": 0,
            "blockedType": "Enum"
          }
        ],
        "id": "string"
      }
    ]
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.

  • disponibility: disponibilidad del empleado durante un intervalo concreto. Si no se define, la disponibilidad de un empleado es total. Para cambiarla, se deberá enviar la siguiente información.

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

  • id: identificador externo de la asociación a servicio. Debe ser único.

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": "yyyy-MM-dd",
        "to": "yyyy-MM-dd",
        "regularMinutes": 0,
        "countingDays": "Enum",
        "additionalMinutes": 0,
        "regularControlPeriod": "Enum",
        "additionalControlPeriod": "Enum",
        "calendarDaysOff": true,
        "numberOfHolidays": 0,
        "numberOfPublicHolidays": 0,
        "weeklyDaysInvolved": "Enum",
        "metadata": {},
        "costPerHour": 0,
        "personCategory": "string",
        "id": "string",
        "contractTypeId": "string"
      }
    ]
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*: horas ordinarias (en minutos) establecidas en el contrato. El valor se interpreta en función de la base horaria definida: anual, semanal o diaria.

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

  • additionalMinutes*: horas complementarias (en minutos) establecidas en el contrato. El valor se interpreta en función de la base horaria definida: anual, semanal o diaria.

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

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

  • 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 (tipo de semana). Este campo puede definirse como MONDAY_SUNDAY, MONDAY_SATURDAY, LABOR_DAYS, LABOR_MONDAY_SATURDAY o WEEKENDS_AND_HOLIDAYS.

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

  • costPerHour: coste del empleado por hora trabajada.

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

  • id: identificador externo del contrato. Debe ser único. 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 (más información aquí). Si no se especifica, se podrán aplicar filtros de tipo de contrato para asignarle uno.

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:

{
    "person": {
        "name": "Jane",
        "surname": "Santos",
        "employeeId": "010203",
        "seniority": "2018-03-01"
    },
    "serviceAssociations": [
        {
            "ownerProduct": "0001-G",
            "product": "0001-G",
            "from": "2024-01-01",
            "to": null,
            "disponibility": [
                {
                    "from": "2026-01-01",
                    "ranges": [
                        {
                            "dayType": "ALL",
                            "startMinuteDay": 0,
                            "duration": 1440,
                            "available": false
                        }
                    ],
                    "type": "SHIFT_PATTERN",
                    "timeFramePatternId": "d01e1e08-b2e4-48d1",
                    "weekStart": 1,
                    "blockedType": "NON_EXTENSIBLE_TIME"
                }
            ]
        }
    ],
    "contracts": [
        {
            "from": "2026-01-01",
            "to": null,
            "regularMinutes": 0,
            "additionalMinutes": 0,
            "regularControlPeriod": "WEEKLY",
            "additionalControlPeriod": "WEEKLY",
            "calendarDaysOff": false,
            "numberOfHolidays": 0,
            "numberOfPublicHolidays": 0,
            "weeklyDaysInvolved": "MONDAY_SUNDAY",
            "personCategory": "AV",
            "contractTypeId": "JC40"
        }
    ]
}

Aspectos que tener en cuenta

Esta petición 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 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?