> ## Documentation Index
> Fetch the complete documentation index at: https://docs.filexpress.app/llms.txt
> Use this file to discover all available pages before exploring further.
# Sucursales y puntos de venta
> Códigos de establecimiento, puntos de venta y su numeración de DTE
| Permiso | Endpoints |
| - | - |
| Sin permiso | `GET /branches` |
| `branches.write` | `POST /branches/{id}/points-of-sale`, `PUT /points-of-sale/{id}` |
`branches.write` es un permiso **explícito**: debe marcarse en **Integraciones externas**; las integraciones existentes no lo reciben automáticamente.
Cada sucursal tiene un **código de establecimiento** (`M001` para la casa matriz, `S001`, `S002`… para las demás) y uno o más **puntos de venta** (`P001`, `P002`…). Cada punto de venta lleva su propia numeración de documentos electrónicos, y el número de control se forma con ambos códigos:
```text theme={null}
DTE-01-M001P002-000000000000015
└──┘└──┘
establecimiento + punto de venta
```
* Toda sucursal tiene siempre **un punto de venta predeterminado** (`P001` al inicio). Las ventas que no indican punto de venta ni pertenecen a un turno de caja se emiten con él.
* El predeterminado no se puede desactivar.
* El código de establecimiento y el punto de venta predeterminado se administran desde FileXpress (**Facturación → Configuración → Puntos de venta**). Ver [Puntos de venta](/docs/caja/puntos-de-venta).
Los códigos de establecimiento y de punto de venta deben coincidir con los registrados ante el Ministerio de Hacienda. Verifícalos antes de emitir desde un punto de venta nuevo.
## Listar sucursales
```http theme={null}
GET /branches
```
No requiere permiso. Devuelve las sucursales del negocio con sus puntos de venta (el predeterminado primero y luego por código):
```json theme={null}
{
"status": true,
"data": [
{
"id": "9d1c5a3e-...",
"name": "Casa Matriz",
"code": "M001P001",
"establishment_code": "M001",
"points_of_sale": [
{ "id": "7c20...", "code": "P001", "name": "Caja principal", "is_default": true, "is_active": true },
{ "id": "7c31...", "code": "P002", "name": "Caja 2", "is_default": false, "is_active": true }
]
},
{
"id": "9d1c5a40-...",
"name": "Sucursal Santa Ana",
"code": "S001P001",
"establishment_code": "S001",
"points_of_sale": [
{ "id": "7c42...", "code": "P001", "name": "Caja principal", "is_default": true, "is_active": true }
]
}
]
}
```
| Campo | Descripción |
| - | - |
| `establishment_code` | Código de establecimiento registrado en Hacienda. |
| `code` | Solo lectura: código de establecimiento + código del punto de venta predeterminado. Se conserva por compatibilidad; para emitir usa `points_of_sale`. |
| `points_of_sale[].is_default` | Punto de venta que se usa cuando una venta no indica otro. |
| `points_of_sale[].is_active` | Los inactivos no pueden emitir ni abrir caja. |
## Crear punto de venta
```http theme={null}
POST /branches/{id}/points-of-sale
```
| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `code` | string | Sí | Formato `P` + 3 dígitos (`P002`). Único en la sucursal. |
| `name` | string | Sí | Nombre visible. Máx. 100. |
```bash theme={null}
curl -X POST https://api.filexpress.app/api/external/branches/9d1c5a3e-.../points-of-sale \
-H "X-API-Key: fx_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"code":"P002","name":"Caja 2"}'
```
**Respuesta `201`**
```json theme={null}
{
"status": true,
"data": {
"id": "7c31...",
"business_id": "5a10...",
"branch_id": "9d1c5a3e-...",
"code": "P002",
"name": "Caja 2",
"is_default": false,
"is_active": true,
"created_at": "2026-10-08T15:00:00.000000Z",
"updated_at": "2026-10-08T15:00:00.000000Z",
"current_session": null,
"last_session": null
}
}
```
Al crearlo, FileXpress genera su numeración propia para cada tipo de documento del año en curso, empezando en 1.
**Errores**
| Código | Causa |
| - | - |
| `404` | `Branch not found for this integration.` (inexistente o de otro negocio). |
| `422` | `code`: `El código del punto de venta debe tener el formato P001.` / `Ya existe un punto de venta con ese código en la sucursal.` / validación. |
## Editar punto de venta
```http theme={null}
PUT /points-of-sale/{id}
```
| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `name` | string | No | Nuevo nombre. Máx. 100. |
| `is_active` | boolean | No | `false` para desactivarlo. |
El código no se puede cambiar. Renombrar un punto de venta no afecta a los documentos ya emitidos.
```bash theme={null}
curl -X PUT https://api.filexpress.app/api/external/points-of-sale/7c31... \
-H "X-API-Key: fx_xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"is_active":false}'
```
**Respuesta `200`**: el punto de venta con los mismos campos que al crearlo.
| Campo | Descripción |
| - | - |
| `current_session` | Turno de caja abierto en el punto de venta (`id`, `opening_date`, `opening_amount`, `opened_by_user`) o `null`. |
| `last_session` | Turno más reciente, abierto o cerrado (`id`, `status`, `opening_date`, `closing_date`, `opened_by_user`, `closed_by_user`) o `null`. |
**Errores**
| Código | Causa |
| - | - |
| `404` | `Point of sale not found.` (inexistente o de otro negocio). |
| `422` | `is_active`: `No se puede desactivar el punto de venta predeterminado.` / `El punto de venta tiene un turno de caja abierto.` / validación. |
## Usar el punto de venta
* [Crear venta](/docs/api/facturacion/ventas#crear-venta): campo opcional `point_of_sale_id`.
* [Abrir caja](/docs/api/caja#abrir-caja): `point_of_sale_id`, obligatorio si la sucursal tiene más de un punto de venta activo.
## Errores
| Código | Cuándo |
| - | - |
| `401` | API key ausente o inválida. |
| `403` | La integración no tiene el permiso `branches.write`. |
| `404` | Sucursal o punto de venta inexistente o de otro negocio. |
| `422` | Validación o regla de negocio (código duplicado o con formato inválido, desactivar el predeterminado o uno con turno abierto). |
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.