Añadir contratos con restricciones

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

 
"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,
        "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,
                    "string": 0
                },
                "blocking": false
            }
        ]
    }
]
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.

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

    • blocking. Indica si la restricción es bloqueante o no. Si se envía true, las infracciones bloquearán determinadas operaciones. Este campo se ignora actualmente y todas las restricciones se crean con false como valor predeterminado.

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.presence_total_minutes",
                    "parameters": {
                        "max": 360
                    },
                    "blocking": false
                },
                {
                    "id": "constraint.weekly_rotative_rest",
                    "parameters": {
                        "mandatory": true,
                        "rest": 4.0,
                        "rotation": 4.0
                    },
                    "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 (Duración máxima de un turno y Rotación de descansos).

Aspectos que tener en cuenta

Si el empleado indicado en la URL no existe, la petición devolverá un error 404 Not Found indicando Person does not exist.

Si el identificador de la restricción (id) no se corresponde con ninguna restricción del catálogo del negocio, la petición devolverá un error 400 Bad Request indicando Constraint not found in business catalog.

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ía el campo contractTypeId y constraints, la petición devolverá un error 400 Bad Request indicando […​] cannot specify both contractTypeId and constraints simultaneously.

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?