Crear

Descripcion general

Este endpoint permite crear uno o varios departamentos 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. El único campo obligatorio por fila es name; el resto son opcionales. Los departamentos pueden anidarse mediante parent_department_number para formar una jerarquía, y opcionalmente vincularse a un centro de costos vía cost_center_code o inline mediante cost_center. Una solicitud exitosa devuelve 201 con los departamentos creados, incluyendo los campos generados por el servidor (id, department_number, depth, created_at, updated_at).

Endpoint

{ "name": "Recursos Humanos" }

{
  "name": "Reclutamiento",
  "code": "RH-REC",
  "description": "Subárea de reclutamiento",
  "parent_department_number": 1,
  "sort_order": 10
}

{
  "name": "Ventas",
  "code": "VEN",
  "parent_department_number": 1,
  "cost_center": {
    "code": "CC-VEN",
    "name": "Centro de costos Ventas",
    "is_active": true
  }
}

[
  { "name": "Marketing", "code": "MKT" },
  { "name": "Finanzas", "code": "FIN", "parent_department_number": 1 }
]

Reglas de los campos

Forma de cost_center (creación inline)

Espejo de campos con el centro de costos

Cuando el departamento se vincula a un centro de costos (al crear, sea vía cost_center_code o cost_center), el CC es dueño de estos campos en el departamento: name, code, description, sort_order. Los valores que el usuario envíe para esos campos se ignoran y el departamento se escribe con los valores del CC.

Forma de las respuestas

201 — solicitud única

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

{
  "id": "ck...",
  "department_number": 5,
  "parent_id": "ck...",
  "depth": 1,
  "name": "Ventas",
  "code": "VEN",
  "description": null,
  "cost_center_id": null,
  "is_active": true,
  "sort_order": 0,
  "created_at": "2026-05-24T10:00:00.000Z",
  "updated_at": "2026-05-24T10:00:00.000Z"
}

201 — solicitud por lote

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

{
  "summary": { "total": 2, "created": 2 },
  "created": [
    { "id": "ck...", "department_number": 6, "...": "..." },
    { "id": "ck...", "department_number": 7, "...": "..." }
  ]
}

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": ["Ingresa el nombre."] }
}

400 — validación fallida (solicitud por lote)

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

{
  "message": "Validation failed for 2 department(s). No departments were created.",
  "summary": { "total": 3, "with_errors": 2 },
  "errors": [
    {
      "index": 0,
      "department": { "name": "Ventas", "code": "VEN" },
      "issues": [
        {
          "field": "parent_department_number",
          "code": "PARENT_DEPARTMENT_NOT_FOUND",
          "message": "No department with number '99' in this organization."
        }
      ]
    },
    {
      "index": 2,
      "department": { "name": "Compras", "code": "VEN" },
      "issues": [
        {
          "field": "code",
          "code": "DUPLICATE_CODE_IN_BATCH",
          "message": "Code 'VEN' appears multiple times in this batch."
        }
      ]
    }
  ]
}

• index — posición 0-based de la fila que falló dentro del arreglo enviado.
• department.name / department.code — extraídos 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 — condición de carrera

Se devuelve con el código CONCURRENT_MODIFICATION cuando otra solicitud reclama un code (o modifica un CC referenciado) entre el momento en que validamos el tuyo y el momento en que escribimos. En modo lote, la transacción completa hace rollback — ningún departamento es creado. Reintenta la misma solicitud.

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: