Crear

Descripcion general

Este endpoint permite crear una o varias sucursales 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. Las sucursales pueden anidarse mediante parent_branch_code para formar un árbol. Una solicitud exitosa devuelve 201 con las sucursales creadas, incluyendo los campos generados por el servidor (id, branch_number, parent_id, depth, created_at, updated_at).

En modo lote, si cualquier fila falla la validación, ninguna sucursal se crea — la respuesta lista los problemas por fila para corregirlos en una sola pasada.

Referencias entre filas no permitidas. parent_branch_code debe resolverse contra una sucursal que ya exista en la base de datos. No se pueden crear referencias entre filas del mismo lote — para construir un árbol multi-nivel, envía lotes secuenciales (raíces primero, luego hijos). Las sucursales creadas sin code no pueden ser referenciadas como padre vía la API; si necesitas que una sucursal sea direccionable, asígnale un code.

Endpoint

{
  "name": "Matriz CDMX",
  "code": "CDMX"
}

{
  "name": "Sucursal Norte",
  "code": "NTE",
  "description": "Cobertura zona norte",
  "parent_branch_code": "CDMX",
  "sort_order": 10
}

[
  { "name": "Sucursal Norte", "code": "NTE", "parent_branch_code": "CDMX" },
  { "name": "Sucursal Sur",   "code": "SUR", "parent_branch_code": "CDMX" },
  { "name": "Almacén GDL",    "code": "GDL" }
]

Reglas de los campos

Forma de las respuestas

201 — solicitud única

Cuando el cuerpo es un objeto, la respuesta es el objeto de la sucursal creada.

{
  "id": "5d3a...",
  "branch_number": 7,
  "parent_id": "1a2b...",
  "depth": 1,
  "name": "Sucursal Norte",
  "code": "NTE",
  "description": null,
  "is_active": true,
  "sort_order": 0,
  "created_at": "2026-05-24T12:34:56.000Z",
  "updated_at": "2026-05-24T12:34:56.000Z"
}

201 — solicitud por lote

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

{
  "summary": { "total": 3, "created": 3 },
  "created": [
    { "id": "...", "branch_number": 7, "code": "NTE", "...": "..." },
    { "id": "...", "branch_number": 8, "code": "SUR", "...": "..." },
    { "id": "...", "branch_number": 9, "code": "GDL", "...": "..." }
  ]
}

Errores

400 — validación fallida (solicitud única)

{
  "message": "Validation failed.",
  "errors": [
    {
      "field": "parent_branch_code",
      "code": "PARENT_BRANCH_NOT_FOUND",
      "message": "No branch with code 'XYZ' in this organization."
    }
  ]
}

Para fallas de validación de campos (campo obligatorio faltante, tipo incorrecto), 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. Ninguna sucursal del lote fue creada.

{
  "message": "Validation failed for 2 branch(es). No branches were created.",
  "summary": { "total": 3, "with_errors": 2 },
  "errors": [
    {
      "index": 0,
      "branch": { "name": "Sucursal Norte", "code": "NTE" },
      "issues": [
        {
          "field": "code",
          "code": "DUPLICATE_CODE",
          "message": "A branch with code 'NTE' already exists in this organization."
        }
      ]
    },
    {
      "index": 2,
      "branch": { "name": "Almacén GDL", "code": "GDL" },
      "issues": [
        {
          "field": "parent_branch_code",
          "code": "PARENT_BRANCH_NOT_FOUND",
          "message": "No branch with code 'CDMX' in this organization."
        }
      ]
    }
  ]
}

• index — posición 0-based de la fila que falló dentro del arreglo enviado.
• branch.name / branch.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

Otra solicitud reclamó un code entre el momento en que validamos el tuyo y el momento en que escribimos. En modo lote, la transacción completa hace rollback — ninguna sucursal es creada. Reintenta la misma solicitud.

{
  "message": "Another request claimed a 'code' value during validation. Please retry.",
  "errors": [
    {
      "field": "code",
      "code": "CONCURRENT_MODIFICATION",
      "message": "Retry the request."
    }
  ]
}

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: