Lifecycle y estados

Concepto clave

Un comprobante es un registro contable de deuda (o de su modificación). El sistema no vincula automáticamente los movimientos entrantes con comprobantes específicos (cuando un cliente tiene varias facturas pendientes, no se puede inferir cuál está pagando). Las transiciones a PAID son siempre decisión del integrador.

Estados

Estado	Significado	Cómo se llega
PENDING	Comprobante activo, esperando cobro	Estado inicial al crearse
PAID	Marcado como pagado por el integrador	PATCH /v1/receivables/{id}/status { "status": "PAID" }
EXPIRED	Pasó dueDate sin ser cobrado	Job nocturno, o PATCH manual
SETTLED	El ciclo de liquidación marcó este comprobante como cerrado contablemente	Job de liquidación
DISABLED	Anulado o invalidado	DELETE /v1/receivables/{id}

Diagrama de transiciones

Imputación y liquidación

Hay dos ciclos que afectan a un comprobante: la imputación (decisión del integrador de marcar un comprobante como PAID vía PATCH /v1/receivables/{id}/status) y la liquidación (proceso automático que cierra los comprobantes de una cuenta en SETTLED al mover la plata a la MAIN del customer). La imputación es opcional; la liquidación ocurre siempre. Las diferencias entre lo cobrado y lo facturado se reflejan en el resumen de liquidación, no en los comprobantes individuales. Ver Liquidaciones.

Listado por estado

Es muy común filtrar comprobantes por estado para visualizar pendientes:

GET /v1/receivables?receivableAccountId=4242&status=PENDING

Para conciliación nocturna, listar los que se liquidaron hoy:

GET /v1/receivables?status=SETTLED&fromDate=2026-05-15T00:00:00-03:00&toDate=2026-05-15T23:59:59-03:00

Los filtros fromDate/toDate siguen la convención de filtros estándar (fecha de creación del comprobante). Para acotar por fecha de cambio de estado (ej. cuándo se marcó como SETTLED), conviene cruzar el listado con la ventana del último ciclo de liquidación de la cuenta (GET /v1/receivable-accounts/{id}/settlements?fromDate=...). Para fechas de negocio del comprobante usá fromIssueDate/toIssueDate o fromDueDate/toDueDate (ver Filtros del listado).

Modificación de estado

Endpoint

PATCH /v1/receivables/{id}/status
Idempotency-Key: ...
Content-Type: application/json

{
  "status": "PAID"
}

Status target	Permitido desde	Restricción
PAID	PENDING, EXPIRED	El integrador asume la responsabilidad de la imputación
EXPIRED	PENDING	Sin restricción adicional, pero típicamente lo hace el job nocturno
DISABLED	PENDING, PAID, EXPIRED	Solo si todavía no se liquidó. Marca el comprobante como anulado en el histórico.

SETTLED y DISABLED son estados finales y no aceptan más transiciones. Intentar modificarlos devuelve 422 updating-receivable-final-status.

No hay rollback de PAID/EXPIRED a PENDING

La API no acepta retroceder un comprobante desde PAID o EXPIRED de vuelta a PENDING. Si lo marcaste como PAID por error y todavía no se liquidó, podés anularlo (DISABLED) y emitir uno nuevo. Si ya se liquidó (SETTLED), la única forma de revertir el efecto contable es emitir una nota de crédito (CREDIT_NOTE) que compense el monto. Ver Notas de crédito.

Webhooks

Cambio de estado	Webhook
→ PAID	receivable.paid
→ EXPIRED	receivable.expired
→ SETTLED	receivable.settled
→ DISABLED	receivable.disabled

Anulación (DELETE)

DELETE /v1/receivables/{id}

Cambia el estado a DISABLED. Permitido si el comprobante está en PENDING, PAID o EXPIRED y todavía no se liquidó.

DELETE /v1/receivables/{id} y PATCH /v1/receivables/{id}/status con { "status": "DISABLED" } son equivalentes: producen el mismo cambio de estado y disparan el mismo webhook receivable.disabled. Elegí el que mejor exprese intención en tu integración (DELETE para "borrar por error de carga", PATCH cuando el flujo ya está iterando con cambios de estado).

Si el comprobante ya tiene notas de crédito asociadas (otros comprobantes con parentReceivableId = id), DELETE devuelve 422 receivable-has-related-items. Hay que anular los hijos primero.