> ## 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.

# Clientes

> Crear y consultar clientes

**Permiso requerido:** `customers`

<Note>
  Estos endpoints usan el formato de respuesta heredado `{ success, data, message }`. Ver [Formato de respuestas](/docs/api/introduccion#formato-de-respuestas).
</Note>

## Listar clientes de una sucursal

```http theme={null}
GET /customers/branch/{branch_id}
```

Devuelve todos los clientes activos de la sucursal (sin paginar).

## Consultar cliente

```http theme={null}
GET /customers/{id}
```

## Crear cliente

```http theme={null}
POST /customers
```

```json theme={null}
{
  "customer_name": "Juan Pérez",
  "legal_name": "Juan Antonio Pérez García",
  "register_number": "12345-6",
  "tax_number": "0614-000101-000-0",
  "document_type": "13",
  "document_number": "00000000-0",
  "address": "Col. San Benito, Av. La Revolución #123",
  "country_id": "uuid",
  "state_id": "uuid",
  "city_id": "uuid",
  "activity_id": "uuid",
  "phone": "7777-1234",
  "email": "juan@example.com",
  "business_type": "natural",
  "branch_id": "uuid"
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `customer_name` | Sí | Nombre comercial o nombre de la persona. |
| `address` | Sí | Dirección. |
| `country_id`, `state_id`, `city_id` | Sí | País, departamento y municipio. Ver [Catálogos](/docs/api/facturacion/catalogos). |
| `phone` | Sí | Teléfono. |
| `email` | Sí | Correo donde se envían los DTE. |
| `business_type` | Sí | `non-business` (consumidor final), `natural` (persona natural) o `legal` (persona jurídica). |
| `branch_id` | Sí | Sucursal a la que pertenece el cliente. |
| `legal_name` | No | Razón social. |
| `register_number` | No | NRC (requerido para emitir CCF). |
| `tax_number` | No | NIT. |
| `document_type` | No | Tipo de documento de identidad según catálogo de Hacienda (ej. `13` DUI, `36` NIT). |
| `document_number` | No | Número de documento. |
| `activity_id` | No | Actividad económica (giro). Ver `GET /activities`. |

La respuesta incluye el cliente creado con su `id`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.