# Editar (/docs/developers/api-reference/employees/edit) ## Descripcion general [#descripcion-general] Este endpoint permite actualizar parcialmente un empleado. Todos los campos del cuerpo son **opcionales** y operan en tres capas dentro de la misma transacción: **datos personales** del empleado, **datos laborales** (puesto, departamento, sucursal, registro patronal, etc.), y **valores de campos personalizados**. Omitir una clave significa que ese campo no se toca; `null` la limpia (cuando aplica). El identificador en la URL es el `employee_number`. Una solicitud exitosa devuelve `200` con el objeto **plano** del empleado (datos personales + los de su empleo actual, mismo shape que `POST` en modo single). Los empleados eliminados se tratan como no encontrados (`404`). **Sobre los datos laborales.** Solo pueden modificarse cuando el empleado está **activo** (no dado de baja). Si el empleado está dado de baja, tocar cualquier campo laboral devuelve `400` con `NO_OPEN_EMPLOYMENT` — primero debes [reactivarlo](/docs/developers/api-reference/employees/reactivate). **Invariante IMSS.** Cuando el valor **efectivo** de `contributes_to_imss` queda en `true`, el `employer_registration` efectivo debe estar puesto. Si no, la respuesta es `400`. **Datos fijos por historial.** Cuando el empleado ya tiene una nómina cerrada en la que se le pagó, o su alta ante el IMSS ya se presentó (desde la plataforma o fuera de ella), `worker_type`, `contributes_to_imss` y `employer_registration` ya no pueden cambiar: la respuesta es `409` con `LOCKED_BY_PAYROLL_HISTORY` en el campo. Esos datos cambian con una baja y un reingreso. `payroll_calendar_number` no puede cambiar mientras el empleado está en una nómina abierta (`409` con `LOCKED_BY_OPEN_PAYROLL`). Reenviar el valor guardado no cuenta como cambio. **Tipo de trabajador.** Cuando el `worker_type` efectivo no es `subordinate`, el `contributes_to_imss` efectivo debe ser `false` y los valores efectivos de `imss_number` y `employer_registration` deben quedar vacíos (sino, `400`): para reclasificar a un subordinado, envía esos campos en `null` en la misma solicitud. Reclasificar a `asimilado` u `honorarios` borra la fecha de antigüedad del empleado. Reclasificar a un trabajador no altera ninguna corrida cerrada: cada corrida congela el tipo con el que se calculó. Un `subordinate` con créditos INFONAVIT o FONACOT activos o suspendidos no puede pasar a `asimilado` ni a `honorarios` (`409` con `WORKER_TYPE_HAS_CREDITS`). **Compensación y estatus.** El endpoint acepta también la compensación (`daily_base_salary`, `regimen_fiscal`, `payroll_calendar_number`, `contract_number`), el horario de trabajo (`work_schedule_number` o `work_schedule_bundle_number`) y las unidades organizacionales (`organizational_units`) del empleado. Cambiar el sueldo registra una nueva fila con fecha efectiva en el historial de sueldos. `activate: true` da de alta al empleado solo si el estado fusionado queda listo para nómina (sino, `400` `ACTIVATION_INCOMPLETE`); si su fecha de ingreso cae en periodos cerrados, exige `confirm_retro: true` (sino, `409` `RETRO_CONFIRMATION_REQUIRED`) y paga esos periodos con ajustes retroactivos; `activate: false` lo deja en `pending`; si **omites** `activate`, un empleado `active` se **degrada** automáticamente a `pending` cuando una edición elimina un dato requerido para nómina. El arreglo `organizational_units` **reemplaza** el conjunto actual (un arreglo vacío lo limpia). ## Endpoint [#endpoint] `PATCH https://app.integranom.com/api/v1/employees/{employee_number}` **Path param:** `employee_number` — entero positivo, el número de empleado dentro de la organización. ## Actualizar datos personales [#actualizar-datos-personales] *** Envía solo los campos que quieras cambiar. El resto del empleado (incluyendo sus datos laborales) queda intacto. ```json { "first_name": "María José", "notes": "Promovida en marzo." } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employees/5" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "first_name": "María José", "notes": "Promovida en marzo." }' ``` **Respuesta** ```json { "employee_number": 5, "internal_number": null, "first_name": "María José", "paternal_last_name": "González", "status": "active", "legal_entity_number": 1, "notes": "Promovida en marzo.", "...": "resto de campos planos del empleado y su empleo", "updated_at": "2026-05-25T11:15:32.000Z" } ``` ## Reasignar departamento y limpiar puesto [#reasignar-departamento-y-limpiar-puesto] *** Los campos laborales solo aplican si el empleado está activo. `null` desvincula (en este caso, deja al empleado sin puesto asignado). Si el empleado está dado de baja, la solicitud falla con `400` `NO_OPEN_EMPLOYMENT`. ```json { "department_code": "MKT", "job_position_code": null } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employees/5" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "department_code": "MKT", "job_position_code": null }' ``` **Respuesta** ```json { "employee_number": 5, "internal_number": null, "first_name": "María José", "paternal_last_name": "González", "status": "active", "legal_entity_number": 1, "department_code": "MKT", "job_position_code": null, "...": "resto de campos planos del empleado y su empleo", "updated_at": "2026-05-25T11:20:00.000Z" } ``` ## Alternar contribucion IMSS [#alternar-contribucion-imss] *** Cuando `contributes_to_imss` efectivo es `true`, el `employer_registration` efectivo debe estar puesto. Si lo dejas en `true` sin un registro patronal vinculado (ni enviado ni almacenado), la solicitud falla con `400`. ```json { "contributes_to_imss": false } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employees/5" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "contributes_to_imss": false }' ``` **Respuesta** ```json { "employee_number": 5, "internal_number": null, "first_name": "María José", "paternal_last_name": "González", "status": "active", "legal_entity_number": 1, "contributes_to_imss": false, "...": "resto de campos planos del empleado y su empleo", "updated_at": "2026-05-25T11:25:00.000Z" } ``` ## Campos personalizados [#campos-personalizados] *** Los `key` de campos personalizados se envían como **claves planas en la raíz del cuerpo**, junto con cualquier campo nativo del empleado en el mismo request. Cada `key` enviada se **guarda** uno a uno: si ya tenía valor, se sobrescribe; si no lo tenía, se crea. `null` limpia ese valor específico. Las `key` **omitidas** del payload no se tocan — es un patch parcial sobre el conjunto de valores del empleado. ```json { "department_code": "MKT", "shirt_size": "L", "allergens": null } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/employees/5" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "department_code": "MKT", "shirt_size": "L", "allergens": null }' ``` **Respuesta** ```json { "employee_number": 5, "internal_number": null, "first_name": "María José", "paternal_last_name": "González", "status": "active", "legal_entity_number": 1, "department_code": "MKT", "...": "resto de campos planos del empleado y su empleo", "updated_at": "2026-05-25T11:30:00.000Z" } ``` ## Campos del cuerpo — datos personales [#campos-del-cuerpo--datos-personales] | Campo | Tipo | Notas | | ----------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `first_name` | string | Mínimo 1 carácter. No aceptado como `null`. | | `middle_name` | string \| null | | | `paternal_last_name` | string | Mínimo 1 carácter. No aceptado como `null`. | | `maternal_last_name` | string \| null | | | `gender` | `male` \| `female` \| `unspecified` | | | `birth_date` | string `YYYY-MM-DD` \| null | | | `birth_country` | string \| null | | | `birth_state` | string \| null | Nombre del estado de nacimiento. Se acepta por compatibilidad: si coincide con un estado del catálogo se guarda su clave; si no, se conserva el texto. Prefiere `birth_state_code`. | | `birth_city` | string \| null | Nombre del municipio de nacimiento. Se acepta por compatibilidad: si coincide con un municipio del estado de nacimiento se guarda su clave; si no, se conserva el texto. Prefiere `birth_municipality_code`. | | `birth_state_code` | string \| null | Estado de nacimiento, clave SAT c\_Estado de 3 letras (por ejemplo `JAL`). | | `birth_municipality_code` | string \| null | Municipio de nacimiento, clave INEGI de 3 dígitos dentro del estado de nacimiento (por ejemplo `120`). Al cambiar el estado sin enviar municipio, el municipio se limpia. | | `birth_place` | string \| null | | | `nationality` | string \| null | Nacionalidad en gentilicio, del catálogo de nacionalidades (por ejemplo `Mexicana`). No distingue mayúsculas, acentos ni género, y acepta el nombre del país, la forma en inglés o la clave de tres letras: `MEXICANO`, `México` y `MEX` se guardan como `Mexicana`. Un valor fuera del catálogo responde `INVALID_NATIONALITY`. `null` la borra. | | `phone_number` | string \| null | Teléfono del empleado con clave de país y sin espacios, por ejemplo `+529611234567`. `null` lo borra. | | `secondary_phone_number` | string \| null | Teléfono secundario. Mismo formato que `phone_number`. `null` lo borra. | | `postal_code` | string `#####` \| null | Código postal de 5 dígitos del domicilio fiscal (el de la Constancia de Situación Fiscal), que es el que valida el CFDI. Cuenta para la preparación de nómina. Se ignora si la casilla queda en `true` (ve `fiscal_address_same_as_home`). | | `work_center_state_code` | string | Entidad del centro de trabajo, clave SAT c\_Estado de 3 letras (por ejemplo `CMX`). No acepta `null`: solo puede cambiarse por otra entidad válida. Cuenta para la preparación de nómina. | | `home_street` | string \| null | Calle del domicilio real (donde vive el empleado). Independiente del domicilio fiscal. | | `home_exterior_number` | string \| null | Número exterior del domicilio real. | | `home_interior_number` | string \| null | Número interior del domicilio real. | | `home_neighborhood` | string \| null | Colonia del domicilio real. | | `home_city` | string \| null | Nombre del municipio o alcaldía. Se acepta por compatibilidad: si coincide con un municipio del estado se guarda su clave; si no, se conserva el texto. Prefiere `home_municipality_code`. | | `home_municipality_code` | string \| null | Municipio o alcaldía del domicilio real, clave INEGI de 3 dígitos dentro de `home_state_code` (por ejemplo `039`). Al cambiar el estado sin enviar municipio, el municipio se limpia. | | `home_state_code` | string \| null | Estado del domicilio real, clave SAT c\_Estado de 3 letras (por ejemplo `NLE`). | | `home_postal_code` | string `#####` \| null | Código postal de 5 dígitos del domicilio real. Solo cuenta para la preparación de nómina si `fiscal_address_same_as_home` es `true`. `null` lo borra. | | `fiscal_address_same_as_home` | boolean | `true` copia el domicilio real al fiscal en cada edición e ignora `postal_code`, `domicile_state_code` y los `fiscal_*` enviados; mientras siga en `true`, cambiar un `home_*` cambia también el domicilio fiscal. Si se omite, conserva el valor guardado, salvo que envíes algún campo del domicilio fiscal: entonces pasa a `false`. | | `domicile_state_code` | string \| null | Estado del domicilio fiscal, clave SAT c\_Estado de 3 letras. Cambiarlo borra `fiscal_municipality_code` si no se envía uno nuevo. | | `fiscal_street` | string \| null | Calle del domicilio fiscal. | | `fiscal_exterior_number` | string \| null | Número exterior del domicilio fiscal. | | `fiscal_interior_number` | string \| null | Número interior del domicilio fiscal. | | `fiscal_neighborhood` | string \| null | Colonia del domicilio fiscal. | | `fiscal_municipality_code` | string \| null | Municipio o alcaldía del domicilio fiscal, clave INEGI de 3 dígitos dentro de `domicile_state_code`. | | `fiscal_city` | string \| null | Nombre del municipio del domicilio fiscal. Se acepta por compatibilidad igual que `home_city`. Prefiere `fiscal_municipality_code`. | | `internal_number` | string \| null | Número interno que asigna la organización. Único en la organización sin distinguir mayúsculas: `409` con `DUPLICATE_INTERNAL_NUMBER` si otro empleado ya lo tiene. `null` lo borra. | | `bank` | string \| null | Nombre del banco, máximo 60 caracteres. Texto libre; utiliza el nombre del catálogo SAT c\_Banco para que coincida con el selector de la plataforma. | | `clabe` | string `18 dígitos` \| null | CLABE interbancaria. Se valida el dígito verificador. | | `account_number` | string \| null | Número de cuenta, solo dígitos: máximo 12 si `bank` es BANREGIO, máximo 11 para cualquier otro banco. Sin una `clabe` válida, el `bank` efectivo es obligatorio: `400` con `BANK_REQUIRED_FOR_ACCOUNT`. Solo se revisa si la solicitud envía `bank`, `clabe` o `account_number`. | | `card_number` | string `16 dígitos` \| null | Número de tarjeta. | | `notes` | string \| null | | | `rfc` | string | 12 o 13 caracteres. Editable — se devuelve `409` si el nuevo valor colisiona con otro empleado de la organización. | | `curp` | string | Exactamente 18 caracteres. Editable — `409` en colisión. | ## Campos del cuerpo — datos laborales [#campos-del-cuerpo--datos-laborales] Aplican solo cuando el empleado está activo (no dado de baja). Si el empleado está dado de baja, **cualquier** campo de esta sección produce `400` `NO_OPEN_EMPLOYMENT`. | Campo | Tipo | Notas | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `job_position_code` | string \| null | | | `branch_code` | string \| null | | | `department_code` | string \| null | | | `cost_center_code` | string \| null | | | `employer_registration` | string \| null | Dentro de la razón social del empleado. Debe quedar en `null` cuando el `worker_type` efectivo no es `subordinate`. Fijo cuando el empleado tiene historial de nómina (`409` `LOCKED_BY_PAYROLL_HISTORY`). | | `imss_number` | string \| null | NSS de 11 dígitos cuando se asigna. Se valida el dígito verificador. Debe quedar en `null` cuando el `worker_type` efectivo no es `subordinate`. | | `is_included_in_payroll_calculations` | boolean | | | `contributes_to_imss` | boolean | Cuando el valor efectivo es `true`, el `employer_registration` efectivo debe estar puesto; sino `400`. Debe quedar en `false` cuando el `worker_type` efectivo no es `subordinate`. Fijo cuando el empleado tiene historial de nómina (`409` `LOCKED_BY_PAYROLL_HISTORY`). | | `worker_type` | `subordinate` \| `asimilado` \| `honorarios` | Tipo de trabajador para efectos estatutarios. No se infiere del tipo de contrato SAT. Fijo cuando el empleado tiene historial de nómina (`409` `LOCKED_BY_PAYROLL_HISTORY`); `409` `WORKER_TYPE_HAS_CREDITS` al dejar de ser `subordinate` con créditos INFONAVIT o FONACOT activos. | | `minimum_wage_zone` | `general` \| `northern_border` | Zona económica del empleado: Zona del Salario Mínimo General o Zona Libre de la Frontera Norte. Al cambiarla, el `daily_base_salary` efectivo se vuelve a validar contra el mínimo de la nueva zona. Cada corrida congela la zona con la que se calculó. | | `salary_type` | `fixed` \| `mixed` \| `variable` \| null | Tipo de salario del empleado: fijo, mixto o variable. Con `null` se borra. Es informativo: no cambia el cálculo de la nómina. | | `imss_worker_type` | `permanent` \| `eventual_city` \| `eventual_construction` \| `eventual_rural` \| null | Tipo de trabajador IMSS: permanente, eventual de la ciudad, eventual de la construcción o eventual del campo. Con `null` se borra. Obligatorio para un empleado activo que aporta al IMSS. Si el empleado no aporta al IMSS, se guarda vacío. | | `imss_work_schedule` | `full` \| `one_day_week` \| `two_day_week` \| `three_day_week` \| `four_day_week` \| `five_day_week` \| `reduced_day` \| null | Semana o jornada reducida: semana completa, semana reducida de 1 a 5 días o jornada reducida. Con `null` se borra. Obligatorio para un empleado activo que aporta al IMSS. Si el empleado no aporta al IMSS, se guarda vacío. | | `is_unionized` | boolean | Indica si el trabajador está sindicalizado. | | `receives_annual_isr_adjustment` | boolean | Si el subordinado entra al ajuste anual de ISR. `true` con un `worker_type` efectivo distinto de `subordinate` responde `400`. Reclasificar a `asimilado` u `honorarios` lo regresa a `false`, y reclasificar a `subordinate` lo vuelve `true` si no lo envías. | | `opts_into_annual_isr_adjustment` | boolean | **Obsoleto:** utiliza `receives_annual_isr_adjustment`. Un `true` se acepta como su equivalente; un `false` se ignora, porque antes no excluía a ningún subordinado. Si envías ambos, gana `receives_annual_isr_adjustment`. Las respuestas lo devuelven siempre en `false`: su significado era la solicitud de un asimilado o un trabajador por honorarios, que ya no existe. Antes un subordinado siempre entraba al ajuste; ahora `receives_annual_isr_adjustment` decide. Un error sobre este campo se reporta con el nombre que enviaste. | | `daily_base_salary` | number \| null | Sueldo diario base (> 0). Un cambio registra una nueva fila con fecha efectiva en el historial de sueldos. | | `regimen_fiscal` | string \| null | Clave SAT del régimen del trabajador (c\_TipoRegimen). El valor efectivo debe corresponder al `worker_type` efectivo: `02` o `13` para `subordinate`, del `05` al `11` para `asimilado` y `honorarios` (sino `400`). | | `work_shift_type` | string \| null | Clave SAT del tipo de jornada (c\_TipoJornada). Va en el recibo timbrado y cuenta para la preparación de nómina. | | `benefit_scheme_number` | null | Ya no existe: las prestaciones del empleado vienen de su contrato (`contract_number`). Se acepta `null` y se ignora; cualquier otro valor responde `400`. | | `payroll_calendar_number` | integer positivo \| null | Calendario de nómina; debe pertenecer a la razón social del empleado. No cambia mientras el empleado está en una nómina abierta (`409` `LOCKED_BY_OPEN_PAYROLL`). | | `contract_number` | integer positivo \| null | Contrato; debe estar vinculado a la razón social del empleado. | | `work_schedule_number` | integer positivo \| null | Horario semanal fijo. Debe ser un horario **activo** de la organización; `null` limpia la asignación. Excluyente con `work_schedule_bundle_number`. | | `work_schedule_bundle_number` | integer positivo \| null | Rotación de horarios. Debe ser una rotación **activa** de la organización; `null` limpia la asignación. Excluyente con `work_schedule_number`. | | `work_schedule_bundle_start_step` | integer positivo \| null | Paso del ciclo en el que arranca el empleado. **Opcional**: omitido, se utiliza el primer paso de la rotación. Un paso con valor exige `work_schedule_bundle_number` en el mismo cuerpo. | | `organizational_units` | integer\[] | **Reemplaza** el conjunto de unidades organizacionales (un arreglo vacío lo limpia). Máximo una unidad por tipo. | | `activate` | boolean | `true` da de alta (`active`) solo si el estado fusionado está listo para nómina (sino `400` `ACTIVATION_INCOMPLETE`); `false` deja en `pending`. Omitirlo aún degrada `active`→`pending` si la edición rompe la preparación. | | `confirm_retro` | boolean | Autoriza que dar de alta a un empleado `pending` cuya fecha de ingreso cae en periodos **cerrados** pague esos periodos con ajustes retroactivos. Sin él, esa alta responde `409` `RETRO_CONFIRMATION_REQUIRED` (con `retro_periods`) y no se guarda nada. | ## Campos del cuerpo — valores de campos personalizados [#campos-del-cuerpo--valores-de-campos-personalizados] Los valores de campos personalizados se envían como **claves planas en la raíz del cuerpo**, junto a los campos nativos del empleado. Cada `key` enviada se guarda (sobrescribe el valor anterior si existía); `null` limpia ese campo; las `key` omitidas del payload no se tocan. Los tipos aceptados son los mismos que en [crear](/docs/developers/api-reference/employees/create) (`text`/`select` → string, `number` → número, `boolean` → `true`/`false`, `date` → string `YYYY-MM-DD`). ## No aceptados [#no-aceptados] * `legal_entity_number` — la razón social del empleado activo es inmutable. Para cambiarla, primero da de baja al empleado y reactívalo contra una nueva razón social. * `hire_date`, `seniority_date` — se fijan al crear/reactivar. * `termination_date` — se fija vía [`/terminate`](/docs/developers/api-reference/employees/terminate). * `employee_number` — identificador en la URL. ## Forma de la respuesta [#forma-de-la-respuesta] `200 OK` — el objeto **plano** del empleado (datos personales + los de su empleo actual), misma forma que la respuesta de [crear](/docs/developers/api-reference/employees/create) en modo single. ## Errores [#errores] | Status | Causa | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `employee_number` inválido en la URL; falla de validación del cuerpo; `NO_OPEN_EMPLOYMENT` cuando se tocan campos laborales y el empleado está dado de baja; `*_NOT_FOUND` para códigos que no resuelven (incluye `PAYROLL_CALENDAR_NOT_FOUND`, `CONTRACT_NOT_FOUND`, `ORGANIZATIONAL_UNIT_NOT_FOUND`); `ORGANIZATIONAL_UNIT_DUPLICATE_TYPE`; `ACTIVATION_INCOMPLETE` al dar de alta un empleado que no está listo para nómina; `BELOW_MINIMUM_WAGE` cuando el `daily_base_salary` efectivo es menor al salario mínimo diario vigente de la `minimum_wage_zone` efectiva (tomado del catálogo `salario_minimo`, respetando el override de la razón social); `INVALID_HOME_MUNICIPALITY` / `INVALID_FISCAL_MUNICIPALITY` / `INVALID_BIRTH_MUNICIPALITY` cuando el municipio efectivo no pertenece al estado efectivo; `ACCOUNT_NUMBER_TOO_LONG` cuando el `account_number` efectivo excede los dígitos permitidos para el `bank` efectivo (12 para BANREGIO, 11 para cualquier otro); `BANK_REQUIRED_FOR_ACCOUNT` cuando el `account_number` efectivo no tiene `bank` ni una `clabe` válida; `CUSTOM_FIELD_NOT_FOUND` / `CUSTOM_FIELD_INVALID_TYPE`; invariante IMSS violada; `regimen_fiscal` que no corresponde al `worker_type` efectivo; `imss_number` o `employer_registration` efectivos en un empleado que no es `subordinate`. | | `404` | El empleado con ese `employee_number` no existe (o fue eliminado) en esta organización. | | `409` | `RETRO_CONFIRMATION_REQUIRED` al dar de alta a un empleado cuya fecha de ingreso cae en periodos cerrados sin `confirm_retro: true`; `LOCKED_BY_PAYROLL_HISTORY` al cambiar `worker_type`, `contributes_to_imss` o `employer_registration` de un empleado con historial de nómina; `LOCKED_BY_OPEN_PAYROLL` al cambiar `payroll_calendar_number` mientras está en una nómina abierta; `WORKER_TYPE_HAS_CREDITS` al dejar de ser `subordinate` con créditos INFONAVIT o FONACOT activos; `DUPLICATE_INTERNAL_NUMBER`; carrera por RFC/CURP duplicado durante la escritura (`CONCURRENT_MODIFICATION`). |