# Crear (/docs/developers/api-reference/branches/create) ## Descripcion general [#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 [#endpoint] `POST https://app.integranom.com/api/v1/branches` ## Solicitud unica — minima [#solicitud-unica--minima] *** Envía un objeto único con `name`. Sin `parent_branch_code` la sucursal se crea como raíz (`depth: 0`). ```json { "name": "Matriz CDMX", "code": "CDMX" } ``` **cURL** ```bash curl -X POST "https://app.integranom.com/api/v1/branches" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Matriz CDMX", "code": "CDMX" }' ``` **Respuesta** ```json { "id": "1a2b...", "branch_number": 1, "parent_id": null, "depth": 0, "name": "Matriz CDMX", "code": "CDMX", "description": null, "is_active": true, "sort_order": 0, "created_at": "2026-05-24T12:34:56.000Z", "updated_at": "2026-05-24T12:34:56.000Z" } ``` ## Solicitud unica — anidada bajo un padre [#solicitud-unica--anidada-bajo-un-padre] *** Para anidar una sucursal bajo otra existente, envía `parent_branch_code` con el código del padre (en mayúsculas). La API calcula `depth` y resuelve el `parent_id` por ti. ```json { "name": "Sucursal Norte", "code": "NTE", "description": "Cobertura zona norte", "parent_branch_code": "CDMX", "sort_order": 10 } ``` **cURL** ```bash curl -X POST "https://app.integranom.com/api/v1/branches" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Sucursal Norte", "code": "NTE", "description": "Cobertura zona norte", "parent_branch_code": "CDMX", "sort_order": 10 }' ``` **Respuesta** ```json { "id": "5d3a...", "branch_number": 7, "parent_id": "1a2b...", "depth": 1, "name": "Sucursal Norte", "code": "NTE", "description": "Cobertura zona norte", "is_active": true, "sort_order": 10, "created_at": "2026-05-24T12:34:56.000Z", "updated_at": "2026-05-24T12:34:56.000Z" } ``` ## Solicitud por lote (1–100 sucursales) [#solicitud-por-lote-1100-sucursales] *** Envía un **arreglo** de hasta 100 sucursales en el mismo endpoint. Si **cualquier** fila falla la validación, **ninguna** sucursal se crea y la respuesta lista los problemas por fila. ```json [ { "name": "Sucursal Norte", "code": "NTE", "parent_branch_code": "CDMX" }, { "name": "Sucursal Sur", "code": "SUR", "parent_branch_code": "CDMX" }, { "name": "Almacén GDL", "code": "GDL" } ] ``` **cURL** ```bash curl -X POST "https://app.integranom.com/api/v1/branches" \ -H "Authorization: Bearer TU_API_KEY" \ -H "Content-Type: application/json" \ -d '[ { "name": "Sucursal Norte", "code": "NTE", "parent_branch_code": "CDMX" }, { "name": "Sucursal Sur", "code": "SUR", "parent_branch_code": "CDMX" }, { "name": "Almacén GDL", "code": "GDL" } ]' ``` **Respuesta** ```json { "summary": { "total": 3, "created": 3 }, "created": [ { "id": "...", "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" }, { "id": "...", "branch_number": 8, "parent_id": "1a2b...", "depth": 1, "name": "Sucursal Sur", "code": "SUR", "description": null, "is_active": true, "sort_order": 0, "created_at": "2026-05-24T12:34:56.000Z", "updated_at": "2026-05-24T12:34:56.000Z" }, { "id": "...", "branch_number": 9, "parent_id": null, "depth": 0, "name": "Almacén GDL", "code": "GDL", "description": null, "is_active": true, "sort_order": 0, "created_at": "2026-05-24T12:34:56.000Z", "updated_at": "2026-05-24T12:34:56.000Z" } ] } ``` ## Reglas de los campos [#reglas-de-los-campos] | Campo | Tipo | Requerido | Notas | | -------------------- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `name` | string | Sí | No vacío tras recortar espacios. | | `code` | string | No | ≤ 60 caracteres, se almacena en mayúsculas, único por organización. Una sucursal sin `code` no puede ser usada como `parent_branch_code` por otra. | | `description` | string | No | Texto libre. | | `parent_branch_code` | string | No | Código (en mayúsculas) de una sucursal existente en la misma organización. Si se omite, la sucursal se crea como raíz. No se permiten referencias dentro del lote. | | `is_active` | boolean | No | Por defecto `true`. | | `sort_order` | integer ≥ 0 | No | Por defecto `0`. | ## Forma de las respuestas [#forma-de-las-respuestas] ### `201` — solicitud única [#201--solicitud-única] Cuando el cuerpo es **un objeto**, la respuesta es el objeto de la sucursal creada. ```json { "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 [#201--solicitud-por-lote] Cuando el cuerpo es **un arreglo**, la respuesta envuelve los resultados en `summary` + `created[]`. ```json { "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 [#errores] ### `400` — validación fallida (solicitud única) [#400--validación-fallida-solicitud-única] ```json { "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: ```json { "message": "Validation failed.", "errors": { "name": ["Ingresa el nombre."] } } ``` ### `400` — validación fallida (solicitud por lote) [#400--validación-fallida-solicitud-por-lote] Reporte por fila. **Ninguna** sucursal del lote fue creada. ```json { "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 [#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. ```json { "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 [#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: | Codigo | Significado | | ------------------------- | -------------------------------------------------------------------------- | | `INVALID_INPUT` | Falla genérica de validación de campos (formato, longitud, tipo). | | `PARENT_BRANCH_NOT_FOUND` | `parent_branch_code` no coincide con una sucursal viva en la organización. | | `DUPLICATE_CODE` | El `code` ya existe en otra sucursal de la organización. | | `DUPLICATE_CODE_IN_BATCH` | El mismo `code` aparece en más de una fila del lote. | | `CONCURRENT_MODIFICATION` | Señal de reintento por condición de carrera (respuesta `409`). |