Crear o actualizar 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}/employeesA 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 |
Cuerpo de la petición
| Análisis del JSON |
|---|
Detalles
|
Objeto person* Incluye los datos personales del empleado identificado a través de su employeeId. |
Detalles
|
Objeto user Incluye los datos que vinculan al empleado con un usuario de la aplicación de Orquest. |
Detalles
|
Objeto serviceAssociations Incluye la información relativa a las asociaciones a servicio establecidas para el empleado. |
Detalles
|
Objeto contracts Incluye la información relativa a los contratos que se aplican al empleado, en términos de horas trabajadas, limitaciones laborales, etc. |
Detalles
|
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": "Eva",
"surname": "García",
"birthday": "1987-05-07",
"employeeId": "170326",
"virtual": false
},
"user": {
"username": "egarcia",
"email": "egarcia@mail.com",
"nodes": [
10101
],
"roles": [
"Manager"
]
},
"serviceAssociations": [
{
"ownerProduct": "0001-G",
"product": "0001-G",
"from": "2026-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-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"
}
]
}
]Consideraciones
Cada entidad de la lista tiene su propio estado, es decir, cada elemento se actualiza de manera independiente: un error en un elemento no interrumpe el procesamiento del resto.
No se permiten más de 30 elementos en el cuerpo de la petición.
Validación de usuario
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. El campo
usernameno se actualiza, soloemail,nodesyroles. -
Si el usuario existe y está vinculado a otro empleado, la operación se cancela.
En user.roles, el nombre del rol debe coincidir exactamente con el que está configurado en el sistema: Configuración de negocio > Roles.
Tanto nodes como roles definidos previamente permanecen cuando se realiza la petición sin estos campos de usuario.
|
Los roles de |
|
Un usuario de integraciones podrá asignar cualquier rol definido a nivel de negocio. |
|
Si la categoría de empleado ( |
Códigos de error
|
Al ser una petición de lista, el estado de cada elemento se evalúa de forma independiente: si un elemento incurre en cualquiera de los códigos de esta tabla (incluidos los transversales), ese elemento se marca en la lista de resultados con |
Además de los errores comunes, este endpoint puede devolver los siguientes códigos:
| Código | Mensaje | Descripción |
|---|---|---|
|
- |
El cuerpo de la petición no es un JSON válido o no puede ser leído. |
Time frame patter not found |
El identificador del patrón de turno ( |
|
Calendar disponibility type is not enabled for business |
Se envía el tipo de disponibilidad |
|
ContractType not found in business |
El identificador de tipo de contrato ( |
|
|
- |
Falta un campo marcado como obligatorio dentro de un objeto presente en la petición ( |
- |
Un campo numérico recibe un valor negativo. |
|
- |
En un contrato o una asociación a servicio, la fecha de inicio ( |
|
- |
El valor de un campo enumerado no corresponde a ninguno de los valores definidos. |
|
User email is not valid |
El formato de la dirección de correo electrónico ( |
|
- |
Alguno de los roles de una asociación a servicio ( |
|
|
- |
El usuario incluido en el objeto |
some role is not valid |
Alguno de los roles de |
|
El objeto |
|
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 empleado?
¿Qué es una asociación a servicio?
¿Qué es un contrato? ¿Y un tipo de contrato?