Añadir contratos de un empleado

Este endpoint permite añadir contratos con restricciones para un empleado.

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

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 
{
    "business": "string",
    "ignoreWithoutOuterId": false,
    "ignoreConstraints": false,
    "contracts": [
        {
            "from": "yyyy-MM-dd",
            "to": "yyyy-MM-dd",
            "regularMinutes": 0,
            "weeklyContract": true,
            "dailyContract": true,
            "countingDays": "Enum",
            "additionalMinutes": 0,
            "regularControlPeriod": "Enum",
            "regularPeriodMultiplier": 1,
            "regularPeriodStartDate": "yyyy-MM-dd",
            "additionalControlPeriod": "Enum",
            "additionalPeriodMultiplier": 1,
            "additionalPeriodStartDate": "yyyy-MM-dd",
            "calendarDaysOff": true,
            "numberOfHolidays": 0,
            "numberOfPublicHolidays": 0,
            "holidayEquivalentWorkingMinutes": 0,
            "weeklyDaysInvolved": "Enum",
            "metadata": {},
            "costPerHour": 0,
            "personCategory": "string",
            "id": "string",
            "contractTypeId": "string",
            "completed": true,
            "additionalDailyContract": true,
            "additionalWeeklyContract": true,
            "regularCountingDayType": "string",
            "additionalCountingDayType": "string",
            "constraints": [
                {
                    "id": "constraint.id",
                    "parameters": {
                        "string": 0
                    },
                    "blocks": {
                        "1": {
                            "string": "string"
                        }
                    },
                    "blocking": false
                }
            ]
        }
    ]
}
Detalles

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

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

  • ignoreConstraints: determina si se actualizan las restricciones del empleado. En caso de establecer true, se ignorarán las restricciones de la solicitud y solo se importarán los datos del contrato base. Las restricciones existentes no se verán afectadas.

  • contracts: lista de contratos que se definen para el empleado de la URL. Cada contrato puede tener sus propias restricciones.

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

    • weeklyContract*: determina si las horas ordinarias del contrato se definen de manera semanal (true).

    • dailyContract: determina si las horas ordinarias del contrato se definen de manera diaria (true). 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, 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, YEARLY o PERIODS.

    • 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, YEARLY o PERIODS.

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

    • holidayEquivalentWorkingMinutes: tiempo trabajado al que equivale un festivo en minutos. Si se omite o se envía null, se mantiene el valor que hubiera en el sistema.

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

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

    • additionalDailyContract: determina si las horas complementarias del contrato se definen de manera diaria (true).

    • additionalWeeklyContract: determina si las horas complementarias del contrato se definen de manera semanal (true). Si tanto additionalWeeklyContract como additionalDailyContract se envían como false, se asume que el contrato es anual.

    • regularCountingDayType: tipo de día que se establece para las horas ordinarias de un contrato diario. Puede ser un tipo de día del sistema (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) o uno definido a nivel de negocio.

    • additionalCountingDayType: tipo de día que se establece para las horas complementarias en un contrato diario. Puede ser un tipo de día del sistema (ALL, WEEKENDS, MONDAY, TUESDAY, WEDNESDAY, etc.) o uno definido a nivel de negocio.

    • constraints: lista de restricciones que se aplicarán a este contrato. Cada restricción del catálogo tiene sus propios parámetros.

      • id*: identificador interno de la restricción.

      • parameters: objeto que define la configuración de la restricción mediante pares clave-valor. Cada restricción utiliza sus propios parámetros. Todos los valores se almacenan como cadena de texto.

      • blocks: objeto opcional que agrupa los bloques de configuración de la restricción, indexados por un identificador numérico. Solo está presente en los tipos de restricción que admiten esta estructura. El conjunto de claves, sus tipos de datos y los valores posibles de cada bloque están definidos de forma independiente para cada tipo de restricción.

      • blocking: indica si la restricción es bloqueante o no. Si se envía true, las infracciones bloquearán determinadas operaciones.

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",
    "ignoreWithoutOuterId": false,
    "ignoreConstraints": false,
    "contracts": [
        {
            "from": "2026-01-15",
            "to": null,
            "regularMinutes": 360,
            "weeklyContract": false,
            "dailyContract": true,
            "countingDays": "WEEKENDS_AND_HOLIDAYS",
            "additionalMinutes": 120,
            "regularControlPeriod": "MONTHLY",
            "regularPeriodMultiplier": 1,
            "regularPeriodStartDate": "2026-01-15",
            "additionalControlPeriod": "MONTHLY",
            "additionalPeriodMultiplier": 1,
            "additionalPeriodStartDate": "2026-01-15",
            "calendarDaysOff": true,
            "numberOfHolidays": 10,
            "numberOfPublicHolidays": 10,
            "weeklyDaysInvolved": "LABOR_DAYS",
            "costPerHour": 200.34,
            "personCategory": "AV",
            "completed": false,
            "additionalDailyContract": true,
            "additionalWeeklyContract": false,
            "regularCountingDayType": "WEEKENDS",
            "additionalCountingDayType": "WEEKENDS",
            "constraints": [
                {
                    "id": "constraint.sliding_rested_constraint",
                    "parameters": {
                        "assigmentIncidence": "false",
                        "skipHolidayWeekends": "false"
                    },
                    "blocks": {
                        "1": {
                            "weekendRestFull": "SATURDAY_OR_SUNDAY",
                            "uniformDistribution": "UNIFORM",
                            "periodicity": "MONTHLY",
                            "restDayAsWork": "false",
                            "maxOccurrences": "0,1",
                            "interval": "0,1",
                            "mandatory": "true"
                        },
                        "2": {
                            "weekendRestFull": "SATURDAY_XOR_SUNDAY",
                            "uniformDistribution": "UNIFORM",
                            "periodicity": "WEEKLY",
                            "restDayAsWork": "false",
                            "maxOccurrences": "0,1",
                            "interval": "0,1",
                            "mandatory": "false"
                        }
                    },
                    "blocking": false
                },
                {
                    "id": "constraint.max_consecutive_worked_days",
                    "parameters": {
                        "min": 1,
                        "max": 6
                    },
                    "blocking": false
                }
            ]
        }
    ]
}

Si todos los datos son correctos, se creará un contrato para el empleado con las características y restricciones indicadas en la petición.

Consideraciones

Si se envía contractTypeId, se reemplazan todas las restricciones —incluyendo las que se hayan definido manualmente— por las que tenga el tipo de contrato.

Si no se envía contractTypeId, se reemplazan por las de la petición únicamente las restricciones cuyo origen es Importación; las que fueron definidas manualmente se conservan en el sistema.

No se puede enviar tipo de contrato y restricciones en la misma petición: si se envían a la vez los campos contractTypeId y constraints, la petición devuelve un error.

Códigos de error

Además de los errores comunes, este endpoint puede devolver los siguientes códigos:

Código Mensaje Descripción

400 Bad Request

Constraint '<id>' not found in business catalog

El identificador de restricción (id) enviado en un contrato no corresponde a ninguna restricción del catálogo del negocio. Se recomienda consultar el catálogo de restricciones.

[…​] cannot specify both contractTypeId and constraints simultaneously.

Se envían a la vez contractTypeId y constraints en el mismo contrato.

Business mismatch: employee belongs to '<business>' but request specifies '<business>'

El negocio indicado en la petición no coincide con el negocio real del empleado.

PersonCategory '<id>' not found in business '<business>'

El identificador de categoría de empleado (personCategory) enviado en un contrato no existe en el negocio. Se recomienda consultar las categorías de empleado disponibles.

DayType '<id>' not found in business

El tipo de día enviado en regularCountingDayType o additionalCountingDayType no existe a nivel de negocio.

ContractType '<id>' not found in business '<business>'

El identificador de tipo de contrato (contractTypeId) enviado no existe en el negocio.

Contract '<id>': block orderValue keys […​] must be positive integers

Las claves de orden (orderValue) definidas en los bloques de una restricción no son números enteros positivos.

Se recomienda revisar el cuerpo de la respuesta en caso de error, ya que incluye información relevante para su diagnóstico y depuración, como el campo inválido o el valor no reconocido.

Enlaces de interés

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

¿Cómo se aplica un tipo de contrato?

¿Qué es una restricción?

¿Cómo se consulta el catálogo de restricciones?