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

# Cuentas por pagar

> Compras con saldo, resumen vigente/vencido, historial y registro de pagos a proveedores

| Permiso | Endpoints |
| - | - |
| `payables` | `GET /payables`, `GET /payables/summary`, `GET /payables/{expense_id}/payments` |
| `payables.payments` | `POST /payables/payments` |

<Note>
  Son permisos **explícitos**: deben marcarse uno por uno en **Integraciones externas**; las integraciones existentes no los reciben automáticamente.
</Note>

Consulta las compras con saldo pendiente y aplica pagos a proveedores. Usa la misma lógica que **Cuentas por pagar** en FileXpress.

## Documentos pendientes

```http theme={null}
GET /payables?branch_id={branch_id}&provider_id={provider_id}
```

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `branch_id` | string | Sí | Sucursal. |
| `provider_id` | string | No | Filtra por proveedor. |

Incluye las compras no eliminadas con saldo pendiente, del ambiente del negocio.

```json theme={null}
{
  "status": true,
  "data": {
    "data": [
      {
        "expense_id": "9a10...",
        "generation_code": "DTE-03-M001P001-000000000000123",
        "document_type": "ccf",
        "issue_date": "2026-08-20",
        "due_date": "2026-09-19",
        "days_overdue": 17,
        "provider_id": "9c77...",
        "provider_name": "Distribuidora Central, S.A. de C.V.",
        "total_amount": 1130.0,
        "amount_paid": 500.0,
        "pending_amount": 630.0,
        "payment_status": "partial"
      }
    ],
    "total_pending": 630.0
  }
}
```

| Campo | Descripción |
| - | - |
| `due_date` | Fecha de emisión + días de crédito del documento (30 si no tiene). |
| `days_overdue` | Días transcurridos desde el vencimiento (0 si está vigente). |
| `provider_name` | Razón social o, si no tiene, nombre comercial. |
| `amount_paid` | Suma de pagos aplicados (los revertidos no cuentan). |
| `payment_status` | `pending` (sin pagos) o `partial` (con abonos). |
| `total_pending` | Suma de `pending_amount` del listado. |

Ordenado del documento más antiguo al más reciente. **Errores**: `404` `Branch not found`; `422` validación.

## Resumen vigente / vencido

```http theme={null}
GET /payables/summary?branch_id={branch_id}
```

```json theme={null}
{
  "status": true,
  "data": {
    "total": 15420.5,
    "current": 9800.0,
    "overdue": 5620.5,
    "current_count": 14,
    "overdue_count": 6
  }
}
```

`current` suma los documentos con `days_overdue = 0`; `overdue`, los vencidos. `branch_id` es obligatorio: sin él (o de otro negocio) responde `404` `Branch not found`.

## Historial de pagos

```http theme={null}
GET /payables/{expense_id}/payments
```

```json theme={null}
{
  "status": true,
  "data": [
    {
      "id": "9f20...",
      "amount": "500.00",
      "pay_date": "2026-09-05 14:12:00",
      "reference": "TRF-88231",
      "status": "applied",
      "payment_method_name": "Transferencia bancaria",
      "bank_name": "Banco Agrícola"
    }
  ]
}
```

Incluye todos los pagos del documento en orden de fecha, también los revertidos (`status` distinto de `applied`). **Errores**: `404` `Bill not found` (inexistente o de otro negocio).

## Registrar pago

```http theme={null}
POST /payables/payments
```

Hay dos formas de indicar a qué documentos aplicar el pago:

<Tabs>
  <Tab title="Por documento (allocations)">
    Indicas cada compra y el monto a aplicarle.

    ```json theme={null}
    {
      "payment_method_id": "pm-uuid",
      "bank_id": "bank-uuid",
      "payment_date": "2026-10-06",
      "reference_number": "TRF-90112",
      "allocations": [
        { "expense_id": "9a10...", "amount": 630.00 },
        { "expense_id": "9a14...", "amount": 250.00 }
      ]
    }
    ```
  </Tab>

  <Tab title="Automático por proveedor">
    Indicas el proveedor, la sucursal y el monto total; FileXpress lo reparte **del documento más antiguo al más reciente** hasta agotarlo.

    ```json theme={null}
    {
      "payment_method_id": "pm-uuid",
      "bank_id": "bank-uuid",
      "payment_date": "2026-10-06",
      "provider_id": "9c77...",
      "branch_id": "9d1c5a3e-...",
      "amount": 880.00
    }
    ```
  </Tab>
</Tabs>

| Campo | Tipo | Requerido | Descripción |
| - | - | - | - |
| `payment_method_id` | string | Sí | Forma de pago (ver [catálogos](/docs/api/facturacion/catalogos)). |
| `payment_date` | date | Sí | Fecha del pago `YYYY-MM-DD` (se guarda con la hora actual). |
| `bank_id` | string | No | Banco desde el que se paga (del negocio). |
| `petty_cash_id` | string | No | Caja chica desde la que se paga (del negocio). |
| `checkbook_id` | string | No | Chequera (del negocio). |
| `check_number` | string | No | Número de cheque (máx. 50). |
| `reference_number` | string | No | Referencia (máx. 255). |
| `notes` | string | No | Máx. 500. |
| `allocations` | array | Sí, si no se envía `provider_id` | 1 a 200 elementos. |
| `allocations[].expense_id` | string | Sí, con `allocations` | Compra del negocio. |
| `allocations[].amount` | number | Sí, con `allocations` | Mayor que 0 y no mayor que su saldo pendiente. |
| `provider_id` | string | Sí, si no se envía `allocations` | Proveedor. |
| `branch_id` | string | Sí, con `provider_id` | Sucursal de los documentos. |
| `amount` | number | Sí, con `provider_id` | Monto total; no puede exceder el saldo pendiente total del proveedor en la sucursal. |

**Reglas**

* **Todo o nada**: los pagos se aplican en una sola transacción. Si un documento falla, no se aplica ninguno.
* El monto de cada documento no puede superar su saldo pendiente; al cubrirlo por completo pasa a `payed`, si no a `partial`.
* El banco, la caja chica y la chequera, si se envían, deben pertenecer al negocio. Las reglas propias de caja chica (fondos) y chequeras se validan igual que en la web; si fallan, responde `422` con el mensaje correspondiente.
* Se recomienda enviar [`Idempotency-Key`](/docs/api/introduccion#idempotencia) para no duplicar el pago si reintentas.
* Los pagos registrados quedan listos para contabilizarse en [Procesar documentos](/docs/contabilidad/procesar-documentos) (tipo **Pagos a proveedores**).

```bash theme={null}
curl -X POST https://api.filexpress.app/api/external/payables/payments \
  -H "X-API-Key: fx_xxxxxxxx" \
  -H "Idempotency-Key: pago-prov-20261006-0017" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id":"pm-uuid","payment_date":"2026-10-06","provider_id":"9c77...","branch_id":"9d1c5a3e-...","amount":880.00}'
```

**Respuesta `201`**

```json theme={null}
{
  "status": true,
  "data": {
    "payments": [
      {
        "payment_id": "9f31...",
        "expense_id": "9a10...",
        "generation_code": "DTE-03-M001P001-000000000000123",
        "amount": 630.0,
        "pending_amount": 0.0,
        "payment_status": "payed"
      },
      {
        "payment_id": "9f32...",
        "expense_id": "9a14...",
        "generation_code": "DTE-03-M001P001-000000000000131",
        "amount": 250.0,
        "pending_amount": 150.0,
        "payment_status": "partial"
      }
    ],
    "total_applied": 880.0
  }
}
```

**Errores**

| Código | Causa |
| - | - |
| `404` | `Bill <id> not found` (en `allocations`, de otro negocio o inexistente) / `Branch not found`. |
| `422` | Validación (`Validation errors` con `errors`). |
| `422` | `Payment method not found` / `Bank not found` / `Petty cash not found` / `Checkbook not found` (de otro negocio o inexistentes). |
| `422` | `The amount exceeds the provider pending balance.` (modo automático). |
| `422` | `El monto para la compra <código> excede lo pendiente. Pendiente: <monto>` / `La compra <código> ya está pagada.` |
| `409` | Conflicto de `Idempotency-Key`. |


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