> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cobrix.co/llms.txt
> Use this file to discover all available pages before exploring further.

# API pública de documentos de cobro

> Crea, consulta, actualiza y cierra documentos con reglas financieras explícitas

<div className="cobrix-category">
  <strong>Una fachada de cobro compacta para sistemas que ya controlan su cartera.</strong>
  <p>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.</p>
</div>

<div className="cobrix-scope-line">
  <span className="cobrix-scope">public\_invoices:read</span>
  <span className="cobrix-scope">public\_invoices:write</span>
</div>

## 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 |

<Tabs>
  <Tab title="CREATED">
    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.
  </Tab>

  <Tab title="Con pagos aplicados">
    La actualización se rechaza con `409`, código `10009` y `errors.payment`. No se modifica el documento, checkout ni ledger.
  </Tab>

  <Tab title="Pagada o conciliada">
    `PAID`, `CONCILIATED` y `PAID_FROM_PROVIDER` aceptan únicamente cambios informativos. `amount` debe coincidir con el total liquidado.
  </Tab>

  <Tab title="Cerrada o fallida">
    `DELETE_FROM_PROVIDER` y `FAILED` no aceptan `PUT`. La respuesta es `409` con el detalle en `errors.status`.
  </Tab>
</Tabs>

## Reglas que protegen el ledger

<AccordionGroup>
  <Accordion title="El proveedor es inmutable" icon="lock">
    `provider` identifica el origen financiero y no puede cambiar después de crear el documento. Un intento devuelve `409` con un mensaje explícito.
  </Accordion>

  <Accordion title="El monto pagado es inmutable" icon="dollar-sign">
    Un documento pagado conserva su monto liquidado. Puedes corregir nombre, descripción, teléfono, email o vencimiento, pero no reabrir ni reescribir el pago.
  </Accordion>

  <Accordion title="No se admiten pagos parciales" icon="ban">
    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.
  </Accordion>

  <Accordion title="DELETE_FROM_PROVIDER" icon="trash">
    Informa que el proveedor eliminó el documento. Cobrix anula los cobros pendientes; si existe dinero aplicado, protege el ledger y rechaza la operación.
  </Accordion>

  <Accordion title="PAID_FROM_PROVIDER" icon="circle-check">
    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.
  </Accordion>
</AccordionGroup>

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

<Columns cols={2}>
  <Card title="Referencia interactiva" icon="brackets-curly" href="/api-reference/documentos-públicos/listar-documentos-de-cobro" cta="Explorar endpoints" arrow>
    Consulta el DTO `snake_case`, filtros, respuestas y errores exactos.
  </Card>

  <Card title="Webhooks de documentos públicos" icon="webhook" href="/guides/webhooks/categories/public-documents" cta="Implementar receptor" arrow>
    Procesa `invoice.created`, `invoice.paid` e `invoice.canceled`.
  </Card>
</Columns>