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

Qué representa `reference`

POST /v1/invoices tiene un único contrato:

Campo	Significado
`reference`	Cédula o RIF del cliente
`provider_id`	Identidad estable del documento en el sistema de origen
`x-idempotency`	Identidad documental de respaldo cuando no se envía `provider_id`

Cobrix busca o crea al cliente únicamente dentro de la empresa de la API key y guarda su identidad fiscal para que el portal pueda localizarlo. No hace falta llamar a un endpoint adicional de clientes.

{
  "reference": "V-12345678",
  "provider": "erp_acme",
  "provider_id": "DOC-90871",
  "amount": 25,
  "name": "Servicio de internet"
}

Cobrix conserva el valor exacto de reference en la respuesta y en los webhooks. Solo normaliza una copia para resolver la identidad fiscal. Si esa identidad es ambigua dentro de la empresa, la creación devuelve 409 y no crea ni mueve el documento. Una referencia que no represente una cédula o RIF devuelve 422. Varios documentos pueden compartir la misma identidad del cliente:

[
  {
    "reference": "V-12345678",
    "provider": "erp_acme",
    "provider_id": "DOC-001",
    "amount": 25,
    "name": "Servicio de julio"
  },
  {
    "reference": "V12345678",
    "provider": "erp_acme",
    "provider_id": "DOC-002",
    "amount": 30,
    "name": "Servicio de agosto"
  }
]

Ambas quedan vinculadas al mismo cliente, pero conservan cobros, estados y cancelaciones independientes.

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

Nombre y correo

En creación y actualización, name admite entre 2 y 100 caracteres. email es opcional: puedes omitirlo, enviar "" o solo espacios. Cobrix recorta los espacios externos y valida el correo únicamente si queda contenido (formato de correo válido y máximo 200 caracteres). No genera ni completa direcciones. En una actualización, omitirlo o enviarlo vacío conserva el correo existente; no lo borra. Un nombre de un carácter o un correo con contenido inválido devuelve 422 con el detalle del campo, sin cambiar las reglas financieras.

Entrada	Creación	Actualización
`name: "Al"`	Válido	Válido
`name: "A"` o más de 100 caracteres	`422`, error en `name`	`422`, error en `name`
Sin `email`, `email: ""` o `email: " "`	Aceptado; no inventa un correo	Conserva el correo existente
`email: " [email protected] "`	Guarda `[email protected]`	Actualiza a `[email protected]`
`email: "correo-invalido"`	`422`, error en `email`	`422`, no modifica el documento

Ejemplo de creación con nombre de dos caracteres y sin correo:

{
  "reference": "V-12345678",
  "provider": "erp_pruebas",
  "provider_id": "QA-DOC-001",
  "amount": 1,
  "name": "Al"
}

Envía el ejemplo únicamente con una identidad sintética reservada en sandbox y una clave x-idempotency nueva. PUT no es una actualización parcial: conserva los campos obligatorios reference, amount y name. Aceptar los datos de contacto no modifica las restricciones de documentos con pagos.

El proveedor es inmutable

provider identifica el origen financiero y no puede cambiar después de crear el documento. Enviarlo con contenido en un PUT devuelve 422 con el detalle en errors.provider.

La identidad documental es estable

provider_id identifica el documento y no puede cambiar después de crearlo. Si no se envía, Cobrix deriva la identidad de x-idempotency. reference puede variar de formato únicamente si sigue representando la misma cédula o RIF.

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

​Qué representa reference

​Reglas que protegen el ledger

​Nombre y correo

Referencia interactiva

Webhooks de documentos públicos

Operaciones

Qué representa `reference`

Reglas que protegen el ledger

Nombre y correo