Crear

Descripcion general

Este endpoint permite crear uno o varios contratos dentro de tu organización. Acepta tanto un objeto como un arreglo de hasta 100 objetos, y la respuesta refleja la forma del cuerpo enviado. Un contrato es propiedad de la organización y se comparte entre las razones sociales que indiques en legal_entity_numbers mediante un puente (relación M:N). El campo contract_type corresponde a un código SAT c_TipoContrato (p. ej. "01" para indeterminado) y concept_numbers lista los conceptos de nómina extralegales que el contrato adjunta. Una solicitud única exitosa devuelve 201 con el contrato creado; una solicitud por lote devuelve 201 con { summary, created[] }.

Un contrato nuevo empieza con las prestaciones mínimas de ley: aguinaldo de 15 días, prima vacacional de 25 % y vacaciones según la tabla de ley.

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

{
  "legal_entity_numbers": [1, 2],
  "name": "Indeterminado tiempo completo",
  "contract_type": "01",
  "concept_numbers": [7]
}

[
  { "legal_entity_numbers": [1], "name": "Indeterminado tiempo completo", "contract_type": "01" },
  { "legal_entity_numbers": [1, 2], "name": "Por obra determinada", "contract_type": "03" }
]

Reglas de los campos

Prestaciones

Todas son opcionales al crear: lo que omitas toma el valor de ley, y lo que envíes se valida con los mínimos de ley sobre el resultado. Sin ninguna prestación el contrato queda como el de ley (is_legal_default en true); con al menos una es personalizado (template_key en null). Las mismas claves sirven para editar.

Coherencia de conceptos

Cada número enviado en concept_numbers debe corresponder a un concepto activo y extralegal de tu organización, sin importar las razones sociales del contrato. Los conceptos de ley se calculan a cada empleado y nunca se adjuntan a un contrato. Si un número no cumple estas condiciones, la fila se rechaza con CONCEPT_NOT_FOUND.

Forma de las respuestas

201 — solicitud única

Cuando el cuerpo es un objeto, la respuesta es el objeto del contrato creado.

{
  "contract_number": 4,
  "name": "Indeterminado tiempo completo",
  "contract_type": "01",
  "description": null,
  "is_active": true,
  "sort_order": 0,
  "legal_entity_numbers": [1, 2],
  "concept_numbers": [7],
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Cada contrato de la respuesta incluye además template_key, is_legal_default, concept_calculations, concept_values (los montos fijos y las fórmulas de fracción del salario, en el formato anterior) y todas las prestaciones, más year_end_bonus_discounts_absences y year_end_bonus_days, que es null cuando la tabla de aguinaldo cambia con la antigüedad.

201 — solicitud por lote

Cuando el cuerpo es un arreglo, la respuesta envuelve los resultados en summary + created[].

{
  "summary": { "total": 2, "created": 2 },
  "created": [
    { "contract_number": 4, "...": "..." },
    { "contract_number": 5, "...": "..." }
  ]
}

Errores

400 — validación fallida (solicitud única)

Para fallas de validación de campos, errors es un objeto indexado por campo:

{
  "message": "Validation failed.",
  "errors": { "name": ["El nombre debe tener entre 3 y 80 caracteres."] }
}

400 — validación fallida (solicitud por lote)

Reporte por fila. Ningún contrato del lote fue creado.

{
  "message": "Validation failed for 1 contract(s). No contracts were created.",
  "summary": { "total": 2, "with_errors": 1 },
  "errors": [
    {
      "index": 0,
      "contract": { "name": "Indeterminado tiempo completo" },
      "issues": [
        {
          "field": "concept_numbers",
          "code": "CONCEPT_NOT_FOUND",
          "message": "No se encontró un concepto extralegal activo con el número '7' en la organización."
        }
      ]
    }
  ]
}

• index — posición 0-based de la fila que falló dentro del arreglo enviado.
• contract.name — extraído de tu entrada para que identifiques la fila sin contar.
• issues[] — todos los problemas de esa fila listados juntos para corregirlos antes de reintentar.

409 — nombre duplicado

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

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

Vocabulario de códigos de error

Estos códigos aparecen dentro de issues[].code (o como code en el cuerpo de error en single) y son estables — tu cliente puede ramificar lógica con base en ellos: