Crear o actualizar empleado (complejo)
Este endpoint permite añadir un empleado o modificar sus datos utilizando su identificador (employeeId). Se pueden añadir o modificar todos los datos del empleado, incluyendo usuario vinculado, contratos, asociaciones a servicio, etc.
PUT /api/v2/businesses/{businessId}/employees/{employeeId}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 |
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
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
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 ( |
|
|
Business forbidden o Product <id> does not exist |
El negocio o el producto indicados en alguna de las |
|
- |
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?