# Editar (/docs/developers/api-reference/contracts/edit) ## Descripcion general [#descripcion-general] Este endpoint permite actualizar parcialmente un contrato. Todos los campos del cuerpo son **opcionales**: si omites una clave, ese campo queda intacto; si envías `description` como `null`, se limpia. El identificador en la URL es el `contract_number` del contrato dentro de tu organización. Enviar `legal_entity_numbers` **reemplaza** el conjunto de razones sociales vinculadas, y enviar `concept_numbers` **reemplaza** el conjunto de conceptos extralegales. Una solicitud exitosa devuelve `200` con la forma completa del contrato actualizado. > **Nota sobre `concept_numbers`:** la API todavía no documenta cómo listar los conceptos de nómina, así que `concept_numbers` debe usar números que ya conozcas, o puedes omitirlo (arreglo vacío). ## Endpoint [#endpoint] `PATCH https://app.integranom.com/api/v1/contracts/{contract_number}` **Path param:** `contract_number` — entero positivo, el número de contrato dentro de la organización. ## Actualizacion minima [#actualizacion-minima] *** Envía solo los campos que quieras cambiar. El resto del contrato queda intacto. ```json { "name": "Indeterminado jornada completa" } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/contracts/4" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Indeterminado jornada completa" }' ``` **Respuesta** ```json { "contract_number": 4, "name": "Indeterminado jornada completa", "contract_type": "01", "description": null, "is_active": true, "sort_order": 0, "legal_entity_numbers": [1, 2], "concept_numbers": [7, 9], "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-01-15T11:15:32.000Z" } ``` ## Reemplazar razones sociales y conceptos [#reemplazar-razones-sociales-y-conceptos] *** Al enviar `legal_entity_numbers` se **reconcilian** los vínculos con las razones sociales: el arreglo pasa a ser el conjunto completo de RS del contrato (se agregan las nuevas y se retiran las ausentes). Al enviar `concept_numbers` se **reemplaza** el conjunto de conceptos extralegales. Si modificas las razones sociales, los conceptos vigentes se **revalidan**: cada concepto debe seguir activo y ser extralegal; de lo contrario la solicitud falla con `CONCEPT_NOT_FOUND`. ```json { "legal_entity_numbers": [1, 2, 3], "concept_numbers": [7] } ``` **cURL** ```bash curl -X PATCH "https://app.integranom.com/api/v1/contracts/4" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "legal_entity_numbers": [1, 2, 3], "concept_numbers": [7] }' ``` **Respuesta** ```json { "contract_number": 4, "name": "Indeterminado jornada completa", "contract_type": "01", "description": null, "is_active": true, "sort_order": 0, "legal_entity_numbers": [1, 2, 3], "concept_numbers": [7], "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-01-15T11:18:09.000Z" } ``` ## Campos del cuerpo [#campos-del-cuerpo] | Campo | Tipo | Notas | | ---------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `legal_entity_numbers` | arreglo de enteros positivos | Al menos 1 elemento. **Reemplaza** el conjunto de razones sociales vinculadas. | | `name` | string | 3–80 caracteres, sin contar espacios al inicio o al final, que no se guardan. Único por organización. | | `contract_type` | string | Código SAT c\_TipoContrato (p. ej. `"01"`). | | `description` | string \| null | `null` limpia la descripción. | | `concept_numbers` | arreglo de enteros positivos | **Reemplaza** el conjunto de conceptos extralegales. | | `concept_calculations` | arreglo de objetos | **Reemplaza** los cálculos por concepto. Si lo omites, los conceptos que siguen en el contrato conservan su cálculo y los conceptos nuevos empiezan con el suyo. Cada objeto sigue las reglas de [crear](/docs/developers/api-reference/contracts/create) y su concepto debe quedar en el contrato. | | `concept_values` | arreglo de objetos | Formato anterior de `concept_calculations`, que se sigue aceptando con las reglas de [crear](/docs/developers/api-reference/contracts/create). Si lo envías, **reemplaza** los cálculos por concepto igual que `concept_calculations`. No se envía junto con él. | | `is_active` | boolean | Flag activo controlado por el usuario. Al ponerlo en `false` con empleados activos o pendientes, la solicitud falla con `409` e informa `affected_count`. | | Prestaciones | | Las claves de [crear](/docs/developers/api-reference/contracts/create). Lo que omitas queda intacto. | ### Prestaciones [#prestaciones] Las reglas que combinan campos (vacaciones del primer año, vales de despensa, fondo de ahorro) se validan contra el **resultado** de combinar tu solicitud con lo guardado, y responden `400` con `INVALID_BENEFITS`. Un valor fuera de rango en un solo campo responde con `errors` por campo. Por ejemplo, activar `food_voucher_enabled` exige que el contrato ya tenga, o que envíes, el porcentaje o el monto y el método de entrega. Enviar `food_voucher_monthly_amount` limpia `food_voucher_rate`, y al revés. Solo se juzgan los grupos que envías (aguinaldo, vales, fondo de ahorro). Modificar el valor de una prestación vuelve personalizado el contrato (`template_key` en `null`), igual que en el panel. ### Coherencia al reconciliar [#coherencia-al-reconciliar] Los conceptos del contrato se **revalidan en cada edición**, incluso si no modificas `legal_entity_numbers` ni `concept_numbers`. Cada concepto adjunto debe seguir activo y ser extralegal; si alguno dejó de cumplirlo (por ejemplo, se desactivó), la solicitud se rechaza con `CONCEPT_NOT_FOUND`. Si un `legal_entity_number` no existe, el error es `LEGAL_ENTITY_NOT_FOUND`; si un `concept_number` no es un concepto extralegal activo, el error es `CONCEPT_NOT_FOUND`. ## Forma de la respuesta [#forma-de-la-respuesta] `200 OK`: el objeto completo del contrato actualizado, con sus prestaciones: ```json { "contract_number": 4, "name": "Indeterminado jornada completa", "contract_type": "01", "description": null, "is_active": true, "sort_order": 0, "legal_entity_numbers": [1, 2, 3], "concept_numbers": [7], "created_at": "2026-01-01T00:00:00.000Z", "updated_at": "2026-01-15T11:18:09.000Z" } ``` ## Errores [#errores] ### `400` — parámetro o validación [#400--parámetro-o-validación] Para `contract_number` inválido en la URL, la respuesta es `400`. Para fallas de validación del cuerpo, `errors` es un arreglo de problemas: ```json { "message": "Validation failed.", "errors": [ { "field": "concept_numbers", "code": "CONCEPT_NOT_FOUND", "message": "No se encontró un concepto extralegal activo con el número '7' en la organización." } ] } ``` Los códigos `LEGAL_ENTITY_NOT_FOUND`, `CONCEPT_NOT_FOUND`, `CONCEPT_CALCULATION_NOT_ALLOWED`, `CONCEPT_VALUE_NOT_ALLOWED`, `WORK_SCHEDULE_NOT_FOUND`, `INVALID_BENEFITS` y `YEAR_END_BONUS_TABLE_GRADED` aparecen en `errors[].code`. Un valor fuera de rango responde `400` con `errors` como objeto indexado por campo. ### `409` — desactivar con empleados vigentes [#409--desactivar-con-empleados-vigentes] Se devuelve cuando envías `is_active: false` y el contrato aún tiene empleados **activos o pendientes**. El cuerpo informa cuántos empleos quedarían afectados vía `affected_count`: ```json { "message": "Cannot deactivate a contract with active or pending employees.", "affected_count": 3 } ``` ### `409`: contrato modificado [#409-contrato-modificado] `code: "CONTRACT_CHANGED"`: otra solicitud modificó el contrato mientras se procesaba la tuya. No se guardó nada; envíala de nuevo. ### `409` — nombre duplicado [#409--nombre-duplicado] Se devuelve cuando el nuevo `name` ya existe en la organización: ```json { "message": "A contract with this 'name' already exists in this organization." } ``` ## Vocabulario de códigos de error [#vocabulario-de-códigos-de-error] | Status | Causa | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `contract_number` inválido en la URL; falla de validación del cuerpo (`LEGAL_ENTITY_NOT_FOUND` / `CONCEPT_NOT_FOUND` / `CONCEPT_CALCULATION_NOT_ALLOWED` / `CONCEPT_VALUE_NOT_ALLOWED` / `WORK_SCHEDULE_NOT_FOUND` / `INVALID_BENEFITS` / `YEAR_END_BONUS_TABLE_GRADED`). | | `403` | Alguna razón social del contrato o de `legal_entity_numbers` queda fuera del alcance de la API key. | | `404` | El contrato con ese `contract_number` no existe (o fue eliminado) en esta organización. | | `409` | `is_active: false` con empleados activos o pendientes (`affected_count`), `name` duplicado o `CONTRACT_CHANGED`. |