Sucursales y puntos de venta

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:

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.

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

GET /branches

No requiere permiso. Devuelve las sucursales del negocio con sus puntos de venta (el predeterminado primero y luego por código):

{
  "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

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.

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

{
  "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

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.

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: campo opcional point_of_sale_id.
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).

Primeros Pasos

Facturación

Recursos Humanos

Contabilidad

Inventario

Proyectos

Cuentas por cobrar y pagar

Precios y promociones

Caja

Referencia interactiva

Sucursales y puntos de venta

Listar sucursales

Crear punto de venta

Editar punto de venta

Usar el punto de venta

Errores

​Listar sucursales

​Crear punto de venta

​Editar punto de venta

​Usar el punto de venta

​Errores

Listar sucursales

Crear punto de venta

Editar punto de venta

Usar el punto de venta

Errores