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

# Elegir la API correcta

> Decide por capacidad, contrato y efecto financiero

No elijas por el nombre del recurso. Elige por el flujo que controla tu sistema y por la unidad monetaria que ya maneja.

<Tabs sync={false}>
  <Tab title="Sincronizar cartera" icon="database">
    Usa la **API de integraciones** si necesitas upsert de clientes y documentos, filtros por cursor, links para varios documentos o pagos dirigidos a cobros concretos.
  </Tab>

  <Tab title="Operar documentos" icon="file-text">
    Usa la **API pública de documentos de cobro** si quieres crear un documento y recibir inmediatamente su cobro vigente con un contrato compacto en `snake_case`.
  </Tab>

  <Tab title="Reportar pagos" icon="credit-card">
    Usa `verified-payments` cuando tu sistema confirma un pago externo y Cobrix debe aplicarlo al ledger. La API pública de documentos también acepta `PAID_FROM_PROVIDER`, pero únicamente para el saldo completo.
  </Tab>

  <Tab title="Recibir eventos" icon="webhook">
    Configura webhooks después de elegir la API. No mezcles la fórmula de firma general con la firma específica de documentos públicos.
  </Tab>
</Tabs>

## Comparación directa

| Decisión        | API de integraciones                               | API pública de documentos de cobro                |
| --------------- | -------------------------------------------------- | ------------------------------------------------- |
| Base            | `/integrations/v1/{companyId}`                     | `/v1/invoices`                                    |
| Forma de campos | `camelCase`                                        | `snake_case`                                      |
| Montos          | Unidades menores: `2025` = USD 20,25               | Unidades mayores: `20.25` = USD 20,25             |
| Seguridad       | Bearer + timestamp + firma HMAC                    | Bearer                                            |
| Idempotencia    | `Idempotency-Key` en todos los `POST`              | `x-idempotency` al crear                          |
| Cliente         | Recurso explícito con ID externo                   | Cuenta sombra resuelta por proveedor y referencia |
| Pagos           | Aplicación por documentos; admite tasa certificada | Pago completo; no admite parcialidad              |

## Recorridos recomendados

<AccordionGroup>
  <Accordion title="ERP o ISP que sincroniza toda su cartera" icon="server">
    <Steps>
      <Step title="Upsert del cliente">Crea o actualiza la identidad externa.</Step>
      <Step title="Upsert del documento">Envía líneas y montos en unidades menores.</Step>
      <Step title="Link de cobro">Selecciona uno o varios documentos abiertos.</Step>
      <Step title="Webhook">Procesa pago y aplicación financiera de forma idempotente.</Step>
    </Steps>
  </Accordion>

  <Accordion title="Sistema que usa el contrato público de documentos" icon="file-invoice">
    <Steps>
      <Step title="Crear documento">Envía `provider`, `reference` y `amount` en unidades mayores.</Step>
      <Step title="Entregar link">Usa `payment.payment_link` devuelto por Cobrix.</Step>
      <Step title="Actualizar pendiente">Un `PUT` reemplaza el checkout y ajusta el ledger.</Step>
      <Step title="Cerrar ciclo">Recibe `invoice.paid` o anula con `DELETE`.</Step>
    </Steps>
  </Accordion>

  <Accordion title="Sistema que confirma pagos fuera de Cobrix" icon="building-columns">
    Reporta el pago por `verified-payments` si trabajas con documentos sincronizados. Para un documento público usa `PAID_FROM_PROVIDER` con `provider_payment_id`. Nunca envíes un monto superior al saldo abierto.
  </Accordion>
</AccordionGroup>

<Warning>
  No copies payloads entre ambas APIs. Los nombres, unidades, autenticación, idempotencia y errores son contratos distintos.
</Warning>