API pública de documentos de cobro

Los montos usan unidades mayores de la moneda configurada en la empresa. Por ejemplo, amount: 20 representa USD 20 cuando la empresa opera en USD.

public_invoices:readpublic_invoices:write

Operaciones

Permiso del drawer	Scope	Método y ruta	Resultado
Consultar documentos	`public_invoices:read`	`GET /v1/invoices`	Lista, filtra y ordena
Consultar documentos	`public_invoices:read`	`GET /v1/invoices/{invoiceId}`	Detalle, estado y cobro vigente
Crear, actualizar y eliminar	`public_invoices:write`	`POST /v1/invoices`	Crea documento y checkout
Crear, actualizar y eliminar	`public_invoices:write`	`PUT /v1/invoices/{invoiceId}`	Actualiza según estado financiero
Crear, actualizar y eliminar	`public_invoices:write`	`DELETE /v1/invoices/{invoiceId}`	Anula o informa pago externo
Crear, actualizar y eliminar	`public_invoices:write`	`DELETE /v1/invoices`	Programa eliminación masiva de pendientes

CREATED
Con pagos aplicados
Pagada o conciliada
Cerrada o fallida

Sin pagos aplicados, el PUT puede cambiar datos informativos y monto. Si cambia el monto, Cobrix registra el ajuste financiero, invalida el checkout anterior y devuelve uno nuevo.

La actualización se rechaza con 409, código 10009 y errors.payment. No se modifica el documento, checkout ni ledger.

PAID, CONCILIATED y PAID_FROM_PROVIDER aceptan únicamente cambios informativos. amount debe coincidir con el total liquidado.

DELETE_FROM_PROVIDER y FAILED no aceptan PUT. La respuesta es 409 con el detalle en errors.status.

Reglas que protegen el ledger

El proveedor es inmutable

provider identifica el origen financiero y no puede cambiar después de crear el documento. Un intento devuelve 409 con un mensaje explícito.

El monto pagado es inmutable

Un documento pagado conserva su monto liquidado. Puedes corregir nombre, descripción, teléfono, email o vencimiento, pero no reabrir ni reescribir el pago.

No se admiten pagos parciales

Esta API espera el pago completo del documento. Las recargas de saldo o Wallet pertenecen a otro flujo y no deben modelarse como abonos parciales.

DELETE_FROM_PROVIDER

Informa que el proveedor eliminó el documento. Cobrix anula los cobros pendientes; si existe dinero aplicado, protege el ledger y rechaza la operación.

PAID_FROM_PROVIDER

Informa un pago realizado fuera de Cobrix. Envía reason: PAID_FROM_PROVIDER y provider_payment_id; Cobrix aplica por la vía financiera oficial hasta el saldo abierto.

POST /v1/invoices requiere x-idempotency. Repetir la misma clave y el mismo cuerpo reproduce el resultado; reutilizarla con otro cuerpo devuelve conflicto.

Referencia interactiva

Consulta el DTO snake_case, filtros, respuestas y errores exactos.

Webhooks de documentos públicos

Procesa invoice.created, invoice.paid e invoice.canceled.

​Operaciones

​Reglas que protegen el ledger

Referencia interactiva

Webhooks de documentos públicos

Operaciones

Reglas que protegen el ledger