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

# Alta y edición de bancos, cajas chicas y chequeras

> Crear y editar bancos, cajas chicas y chequeras desde un sistema externo

**Permiso requerido:** `treasury.write`

| Endpoints |
| - |
| `POST /treasury/banks`, `PUT /treasury/banks/{id}` |
| `POST /treasury/petty-cashes`, `PUT /treasury/petty-cashes/{id}` |
| `POST /treasury/checkbooks`, `PUT /treasury/checkbooks/{id}` |

<Note>
  Es un permiso **explícito**: debe marcarse en **Integraciones externas**; las integraciones existentes no lo reciben automáticamente. Para consultar los registros usa el permiso `treasury` ([Bancos, cajas chicas y chequeras](/docs/api/tesoreria)).
</Note>

Los registros creados aquí se usan después como `bank_id`, `petty_cash_id` y `checkbook_id` en [cobros](/docs/api/cuentas-por-cobrar#registrar-cobro) y [pagos](/docs/api/cuentas-por-pagar#registrar-pago).

<Tip>
  La cuenta contable (`account_id`) se obtiene con [Catálogo de cuentas](/docs/api/contabilidad/catalogo) (permiso `accounting.accounts`). Debe ser una **cuenta de movimiento** (sin subcuentas) de la empresa; es la cuenta que se usa al contabilizar los cobros y pagos de ese banco o caja chica.
</Tip>

## Crear banco

```http theme={null}
POST /treasury/banks
```

```json theme={null}
{
  "name": "Banco Agrícola - Corriente",
  "account_number": "0012-345678-9",
  "balance": 15000.00,
  "account_id": "a1b2..."
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `name` | Sí | Nombre del banco o de la cuenta (máx. 255). |
| `account_number` | Sí | Número de cuenta bancaria (máx. 255). No puede repetirse. |
| `balance` | No | Saldo inicial. Por defecto `0`. |
| `account_id` | No | Cuenta contable de movimiento de la empresa. |

**Respuesta `201`**

```json theme={null}
{
  "status": true,
  "data": {
    "id": "3f1c...",
    "name": "Banco Agrícola - Corriente",
    "account_number": "0012-345678-9",
    "balance": 15000.00,
    "account_id": "a1b2..."
  }
}
```

## Editar banco

```http theme={null}
PUT /treasury/banks/{id}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `name` | No | Nombre. |
| `account_number` | No | Número de cuenta (no puede repetirse). |
| `account_id` | No | Cuenta contable de movimiento; `null` la quita. |

**Comportamiento**

* Solo cambian los campos que envías.
* El saldo **no** se edita por API: cambia con los cobros, pagos y movimientos registrados en FileXpress.

**Respuesta `200`**: el banco actualizado (mismo formato que la creación).

## Crear caja chica

```http theme={null}
POST /treasury/petty-cashes
```

```json theme={null}
{
  "name": "Caja chica Sucursal Centro",
  "balance": 250.00,
  "account_id": "a1c9...",
  "observations": "Responsable: administración de sucursal"
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `name` | Sí | Nombre (máx. 255). |
| `balance` | No | Saldo inicial. Por defecto `0`. |
| `account_id` | No | Cuenta contable de movimiento de la empresa. |
| `observations` | No | Observaciones (máx. 1000). |

**Respuesta `201`**

```json theme={null}
{
  "status": true,
  "data": {
    "id": "8b2e...",
    "name": "Caja chica Sucursal Centro",
    "balance": 250.00,
    "account_id": "a1c9...",
    "observations": "Responsable: administración de sucursal"
  }
}
```

## Editar caja chica

```http theme={null}
PUT /treasury/petty-cashes/{id}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `name` | No | Nombre. |
| `account_id` | No | Cuenta contable de movimiento; `null` la quita. |
| `observations` | No | Observaciones. |

**Comportamiento**: solo cambian los campos enviados. El saldo no se edita por API; cambia con fondeos, gastos, pagos a proveedores y cobros de clientes en efectivo.

**Respuesta `200`**: la caja chica actualizada.

## Crear chequera

```http theme={null}
POST /treasury/checkbooks
```

```json theme={null}
{
  "bank_id": "3f1c...",
  "name": "Chequera 2027",
  "code": "B",
  "start_number": 101,
  "end_number": 200
}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `bank_id` | Sí | Banco de la empresa al que pertenece la chequera. |
| `start_number` | Sí | Primer número de cheque (mínimo 1). |
| `end_number` | Sí | Último número; mayor que `start_number`. |
| `name` | No | Nombre (máx. 100). |
| `code` | No | Código o serie (máx. 50). |

**Comportamiento**: la chequera se crea en estado `ACTIVE` y su número actual (`current_number`) es `start_number`.

**Respuesta `201`**

```json theme={null}
{
  "status": true,
  "data": {
    "id": "c71b...",
    "bank_id": "3f1c...",
    "name": "Chequera 2027",
    "code": "B",
    "start_number": 101,
    "end_number": 200,
    "current_number": 101,
    "status": "ACTIVE"
  }
}
```

## Editar chequera

```http theme={null}
PUT /treasury/checkbooks/{id}
```

| Campo | Requerido | Descripción |
| - | - | - |
| `name` | No | Nombre. |
| `code` | No | Código o serie. |
| `status` | No | `ACTIVE`, `EXHAUSTED` o `CANCELLED`. |

**Comportamiento**: el rango de números y el banco no se pueden cambiar. Para pagar con cheque, la chequera debe estar `ACTIVE`.

**Respuesta `200`**: la chequera actualizada.

## Errores

| Código | Causa |
| - | - |
| `401` | API key ausente o inválida. |
| `403` | La integración no tiene el permiso `treasury.write`. |
| `404` | `Bank not found` / `Petty cash not found` / `Checkbook not found` (inexistente, eliminado o de otra empresa; también `bank_id` al crear una chequera). |
| `422` | `Validation errors`, por ejemplo `account_number` repetido o `end_number` menor o igual que `start_number`. |
| `422` | `account_id`: `La cuenta contable no existe o no pertenece a esta empresa.` / `La cuenta <código> tiene subcuentas; use una cuenta de movimiento.` |

```json theme={null}
{
  "status": false,
  "message": "Validation errors",
  "errors": { "account_id": "La cuenta 1101 tiene subcuentas; use una cuenta de movimiento." }
}
```


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