Editar

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

Path param: contract_number — entero positivo, el número de contrato dentro de la organización.

{ "name": "Indeterminado jornada completa" }

{
  "legal_entity_numbers": [1, 2, 3],
  "concept_numbers": [7]
}

Campos del cuerpo

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

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

200 OK: el objeto completo del contrato actualizado, con sus prestaciones:

{
  "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

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:

{
  "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

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:

{
  "message": "Cannot deactivate a contract with active or pending employees.",
  "affected_count": 3
}

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

Se devuelve cuando el nuevo name ya existe en la organización:

{
  "message": "A contract with this 'name' already exists in this organization."
}

Vocabulario de códigos de error