Cobros y pagos

Los cobros de tus facturas emitidas y los pagos de las recibidas son el registro fiscal de la empresa: con ellos se llevan los libros registro y, si la empresa está en el criterio de caja, se decide en qué periodo se declara el IVA y se comunican al SII. Si tu programa (ERP) es el que sabe cuándo cobras, infórmalos aquí.

Todas las llamadas usan la URL base https://app.faxtal.com/api/v1.1 y la cabecera X-API-Key (ver Autenticación).

Operación	Scope de la API key
Listar los cobros o pagos de una factura	payments:read
Registrar, corregir y compensar cobros o pagos	payments:write

Las rutas son las mismas para emitidas (issued-invoices, cobros) y recibidas (received-invoices, pagos). {invoice_id} es el identificador público de la factura.

Registrar un cobro o un pago

POST /api/v1.1/issued-invoices/{invoice_id}/payments POST /api/v1.1/received-invoices/{invoice_id}/payments

Campo	Obligatorio	Descripción
amount	Sí	Importe cobrado o pagado, positivo. En un abono (factura negativa) también se envía positivo.
occurred_on	Sí	Fecha efectiva del cobro o pago (YYYY-MM-DD). No puede ser futura.
payment_method_code	No	Medio de pago del catálogo payment-methods (ver Formato canónico).
bank_account_id	No	Cuenta bancaria de la empresa en la que se cobró o desde la que se pagó.
means_reference	No	Identificación del medio: IBAN, número de cheque… Máximo 100 caracteres.
external_reference	No	Referencia de tu programa. Si la reenvías, no se duplica el cobro. Máximo 90 caracteres.
receipt_id	No	Vencimiento concreto al que se aplica. Sin él, se reparte entre los vencimientos abiertos, del más antiguo al más reciente.
note	No	Nota interna.

curl -s -X POST "https://app.faxtal.com/api/v1.1/issued-invoices/00000000-0000-0000-0000-000000000001/payments" \
  -H "X-API-Key: fctXXXXXXXX_YYYYYYYYYYYYYYYY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 605.00, "occurred_on": "2026-05-10", "payment_method_code": "04", "external_reference": "COBRO-8812"}'

Responde 201 con la lista de movimientos creados (uno por vencimiento al que se aplicó):

[
  {
    "id": "5120",
    "invoice_id": "00000000-0000-0000-0000-000000000001",
    "receipt_id": "Rk3P0aQ2",
    "kind": "payment",
    "amount": 605.0,
    "occurred_on": "2026-05-10",
    "payment_method_code": "04",
    "bank_account_id": null,
    "means_reference": null,
    "external_reference": "COBRO-8812",
    "reverses_payment_id": null,
    "reversed_by_payment_id": null,
    "created_at": "2026-05-10T09:12:44"
  }
]

• Idempotencia. Con la misma external_reference responde 200 con lo que ya estaba registrado, sin crear nada. Si esa referencia ya se usó en otra factura, responde 409 payment_reference_in_use.
• amount en la respuesta lleva el signo de la factura: negativo en los abonos, en las devoluciones y en las correcciones.
• kind: payment (cobro o pago), return (devolución o reembolso), reversal (corrección), offset (compensación con un abono) o forced_accrual (devengo forzoso por concurso, lo registra la aplicación).

Corregir un cobro o un pago

Un cobro no se borra: se corrige con un movimiento inverso, que queda enlazado al original.

POST /api/v1.1/issued-invoices/{invoice_id}/payments/{payment_id}/reverse POST /api/v1.1/received-invoices/{invoice_id}/payments/{payment_id}/reverse

Campo	Obligatorio	Descripción
occurred_on	No	Fecha de la corrección. Por defecto, la del movimiento que corrige (el cobro mal anotado desaparece de su periodo). No puede ser anterior.
external_reference	No	Referencia de tu programa: reenviarla devuelve la misma corrección (200).
note	No	Nota interna.

Responde 201 con el movimiento inverso. Cada movimiento se corrige una sola vez.

Compensar una factura con un abono

Salda una factura con otra de signo contrario (una factura y su abono) de la misma empresa, del mismo sentido (las dos emitidas o las dos recibidas) y del mismo cliente o proveedor: solo se compensan deudas recíprocas entre las mismas partes. Deja un movimiento offset con medio 14 (Compensación) en cada factura, por el mismo importe y en la misma fecha.

POST /api/v1.1/issued-invoices/{invoice_id}/payments/compensate POST /api/v1.1/received-invoices/{invoice_id}/payments/compensate

Campo	Obligatorio	Descripción
counter_invoice_id	Sí	Identificador público de la factura de signo contrario.
amount	Sí	Importe a compensar, positivo y con dos decimales como máximo. No puede superar lo pendiente de ninguno de los dos vencimientos.
occurred_on	No	Fecha de la compensación (YYYY-MM-DD). Hoy si no se indica. No puede ser futura ni anterior a la fecha de expedición de ninguna de las dos facturas.
receipt_id	No	Vencimiento de esta factura. Sin él, el abierto más antiguo.
counter_receipt_id	No	Vencimiento de la otra factura. Sin él, el abierto más antiguo.
external_reference	No	Referencia de tu programa. Si la reenvías, no se duplica la compensación. Máximo 90 caracteres.
note	No	Nota interna.

Responde 201 con los dos movimientos: payment (en esta factura) y counter_payment (en la otra, con su signo):

{
  "payment": { "id": "5130", "invoice_id": "00000000-0000-0000-0000-000000000001", "kind": "offset", "amount": 242.0, "payment_method_code": "14", "occurred_on": "2026-05-12" },
  "counter_payment": { "id": "5131", "invoice_id": "00000000-0000-0000-0000-000000000002", "kind": "offset", "amount": -242.0, "payment_method_code": "14", "occurred_on": "2026-05-12" }
}

• Idempotencia. Con la misma external_reference entre las mismas dos facturas responde 200 con lo que ya estaba registrado, sin crear nada. Los dos movimientos guardan la referencia como <referencia> (esta factura) y <referencia>#counter (la otra). Si la referencia ya se usó en un cobro o pago, o en otra compensación, responde 409 payment_reference_in_use; y una referencia de compensación no sirve para registrar un cobro (409).
• Cada movimiento se corrige por separado con /reverse.

Consultar

GET /api/v1.1/issued-invoices/{invoice_id}/payments GET /api/v1.1/received-invoices/{invoice_id}/payments

{
  "items": [ { "id": "5120", "kind": "payment", "amount": 605.0, "occurred_on": "2026-05-10" } ],
  "paid_amount": 605.0
}

paid_amount es la suma con signo de los movimientos.

Criterio de caja

Si la factura está en el régimen especial del criterio de caja (clave de régimen 07, ver Formato canónico):

• El IVA se declara en el periodo de cada cobro o pago, en proporción a lo cobrado sobre el total de la factura. Por eso importa la fecha real (occurred_on), no la del registro.
• Lo que siga sin cobrar el 31 de diciembre del año siguiente al de la operación se declara ese día aunque no se haya cobrado.
• Si la empresa está en el SII, cada cobro o pago se comunica a la AEAT después de la factura. Una corrección se comunica como un importe negativo.

Errores

Código	HTTP	Cuándo
payment_amount_invalid	422	El importe no es positivo.
payment_date_in_future	422	occurred_on es posterior a hoy.
payment_method_unknown	422	El medio no está en el catálogo.
payment_exceeds_pending	422	El importe supera lo pendiente de la factura.
invoice_fully_paid	422	La factura ya está cobrada o pagada del todo.
receipt_not_found	404	El vencimiento indicado no existe o no está abierto.
payment_not_found	404	El movimiento no es de esta factura.
payment_event_not_reversible	422	Ese movimiento no se puede corregir (por ejemplo, una corrección).
payment_already_reversed	422	El movimiento ya está corregido.
payment_reversal_before_original	422	La corrección tiene fecha anterior al movimiento que corrige.
payment_compensation_not_opposite	422	Las dos facturas no son de signo contrario (o es la misma).
payment_compensation_amount_invalid	422	El importe a compensar es cero o supera lo pendiente de alguno de los dos vencimientos.
payment_compensation_not_open	422	Alguno de los dos vencimientos no está pendiente, parcial ni vencido.
payment_compensation_other_party	422	Las dos facturas no son del mismo cliente o proveedor (o falta su NIF).
payment_compensation_date_before_invoice	422	occurred_on es anterior a la fecha de expedición de alguna de las dos facturas.
payment_reference_in_use	409	La external_reference ya se usó en otro cobro o pago.

El formato de los errores está en Errores.