Cuentas por pagar

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

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

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

Documentos pendientes

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.

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

GET /payables/summary?branch_id={branch_id}

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

GET /payables/{expense_id}/payments

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

POST /payables/payments

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

Por documento (allocations)
Automático por proveedor

Indicas cada compra y el monto a aplicarle.

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

Indicas el proveedor, la sucursal y el monto total; FileXpress lo reparte del documento más antiguo al más reciente hasta agotarlo.

{
  "payment_method_id": "pm-uuid",
  "bank_id": "bank-uuid",
  "payment_date": "2026-10-06",
  "provider_id": "9c77...",
  "branch_id": "9d1c5a3e-...",
  "amount": 880.00
}

Campo	Tipo	Requerido	Descripción
`payment_method_id`	string	Sí	Forma de pago (ver catálogos).
`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 para no duplicar el pago si reintentas.
Los pagos registrados quedan listos para contabilizarse en Procesar documentos (tipo Pagos a proveedores).

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

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

Primeros Pasos

Facturación

Recursos Humanos

Contabilidad

Inventario

Proyectos

Cuentas por cobrar y pagar

Precios y promociones

Caja

Referencia interactiva

Documentos pendientes

Resumen vigente / vencido

Historial de pagos

Registrar pago

​Documentos pendientes

​Resumen vigente / vencido

​Historial de pagos

​Registrar pago

Documentos pendientes

Resumen vigente / vencido

Historial de pagos

Registrar pago