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

# Create and edit banks, petty cash funds and checkbooks

> Create and edit banks, petty cash funds and checkbooks from an external system

**Required permission:** `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]
>
> This is an **explicit** permission: it must be checked in **External integrations**; existing integrations do not receive it automatically. To query the records, use the `treasury` permission ([Banks, petty cash funds and checkbooks](https://docs.filexpress.app/en/docs/api/tesoreria.md)).

The records created here are later used as `bank_id`, `petty_cash_id` and `checkbook_id` in [collections](https://docs.filexpress.app/en/docs/api/cuentas-por-cobrar.md#register-payment) and [payments](https://docs.filexpress.app/en/docs/api/cuentas-por-pagar.md#register-payment).

> [!TIP]
>
> The accounting account (`account_id`) is obtained with [Chart of accounts](https://docs.filexpress.app/en/docs/api/contabilidad/catalogo.md) (`accounting.accounts` permission). It must be a **posting account** (with no sub-accounts) of the company; it is the account used when posting the collections and payments of that bank or petty cash fund.

## Create bank

```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..."
}
```

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Name of the bank or account (max. 255). |
| `account_number` | Yes | Bank account number (max. 255). Cannot be repeated. |
| `balance` | No | Opening balance. Defaults to `0`. |
| `account_id` | No | Posting accounting account of the company. |

**Response `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..."
  }
}
```

## Edit bank

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

| Field | Required | Description |
| - | - | - |
| `name` | No | Name. |
| `account_number` | No | Account number (cannot be repeated). |
| `account_id` | No | Posting accounting account; `null` removes it. |

**Behavior**

* Only the fields you send change.
* The balance is **not** edited through the API: it changes with the collections, payments and movements registered in FileXpress.

**Response `200`**: the updated bank (same format as creation).

## Create petty cash fund

```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"
}
```

| Field | Required | Description |
| - | - | - |
| `name` | Yes | Name (max. 255). |
| `balance` | No | Opening balance. Defaults to `0`. |
| `account_id` | No | Posting accounting account of the company. |
| `observations` | No | Notes (max. 1000). |

**Response `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"
  }
}
```

## Edit petty cash fund

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

| Field | Required | Description |
| - | - | - |
| `name` | No | Name. |
| `account_id` | No | Posting accounting account; `null` removes it. |
| `observations` | No | Notes. |

**Behavior**: only the fields sent change. The balance is not edited through the API; it changes with fund top-ups, expenses, supplier payments and customer cash collections.

**Response `200`**: the updated petty cash fund.

## Create checkbook

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

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

| Field | Required | Description |
| - | - | - |
| `bank_id` | Yes | Company bank the checkbook belongs to. |
| `start_number` | Yes | First check number (minimum 1). |
| `end_number` | Yes | Last number; greater than `start_number`. |
| `name` | No | Name (max. 100). |
| `code` | No | Code or series (max. 50). |

**Behavior**: the checkbook is created in `ACTIVE` status and its current number (`current_number`) is `start_number`.

**Response `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"
  }
}
```

## Edit checkbook

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

| Field | Required | Description |
| - | - | - |
| `name` | No | Name. |
| `code` | No | Code or series. |
| `status` | No | `ACTIVE`, `EXHAUSTED` or `CANCELLED`. |

**Behavior**: the number range and the bank cannot be changed. To pay by check, the checkbook must be `ACTIVE`.

**Response `200`**: the updated checkbook.

## Errors

| Code | Cause |
| - | - |
| `401` | Missing or invalid API key. |
| `403` | The integration does not have the `treasury.write` permission. |
| `404` | `Bank not found` / `Petty cash not found` / `Checkbook not found` (nonexistent, deleted or from another company; also `bank_id` when creating a checkbook). |
| `422` | `Validation errors`, for example a repeated `account_number` or `end_number` less than or equal to `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.