Añadir contratos de un empleado con restricciones

Este endpoint permite añadir contratos con restricciones para un empleado, admitiendo la naturaleza (nature) de cada restricción.

PUT /api/v2/businesses/{businessId}/people/{employeeId}/contracts-with-constraints

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,
    "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",
            "completed": true,
            "additionalDailyContract": true,
            "additionalWeeklyContract": true,
            "regularCountingDayType": "string",
            "additionalCountingDayType": "string",
            "constraints": [
                {
                    "id": "constraint.id",
                    "parameters": {
                        "string": 0
                    },
                    "blocks": {
                        "1": {
                            "string": "string"
                        }
                    },
                    "blocking": false,
                    "nature": "Enum"
                }
            ]
        }
    ]
}
Detalles

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

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

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

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

  • 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. El valor por defecto es false.

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

      • nature: naturaleza de la restricción. Puede ser PERSONAL o CONTRACT_TYPE. Si no se informa, su valor por defecto es CONTRACT_TYPE.

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": "CST",
    "ignoreWithoutOuterId": false,
    "contracts": [
        {
            "from": "2026-06-16",
            "regularMinutes": 380,
            "weeklyContract": false,
            "dailyContract": true,
            "countingDays": "WEEKENDS_AND_HOLIDAYS",
            "additionalMinutes": 150,
            "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",
            "constraints": [
                {
                    "id": "constraint.shift_duration_alternatives",
                    "parameters": {},
                    "blocks": {
                        "1": {
                            "shiftDuration": 630
                        },
                        "2": {
                            "shiftDuration": 1230
                        }
                    },
                    "blocking": false,
                    "nature": "PERSONAL"
                },
                {
                    "id": "constraint.presence_min_total_minutes",
                    "parameters": {
                        "min": "240"
                    },
                    "blocking": false
                }
            ]
        }
    ]
}

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

Aspectos que tener en cuenta

Este endpoint admite el campo nature en cada restricción, permitiendo indicar explícitamente si se ha informado manualmente (PERSONAL) o si proviene de un tipo de contrato o de una importación (CONTRACT_TYPE).

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.

Contract '<id>': constraints are required

El campo constraints no se ha incluido en un contrato, o se ha enviado vacío.

Constraint '<id>': invalid nature '<nature>'. Allowed values are PERSONAL and CONTRACT_TYPE

El valor del campo nature de una restricción no es PERSONAL ni CONTRACT_TYPE.

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.

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?

¿Qué es una restricción?

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