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

# Introducción

> Guía técnica para integrar facturas con OnePay — flujo de integración, estados, webhooks y funcionalidades avanzadas.

## ¿Qué es una Factura?

Una factura es un registro de cobro que genera automáticamente un [Payment](/client/payments/index) asociado. Al crear una factura, OnePay crea un cobro vinculado, lo envía al cliente y gestiona todo el ciclo de vida hasta el pago y la conciliación.

<Note>
  Si solo necesitas cobrar un monto sin vincular a un sistema de gestión externo, usa directamente [Payments](/client/payments/index).
</Note>

<Note>
  **¿Quieres que OnePay emita la factura ante la DIAN?** Es este mismo endpoint: manda `items` y `customer_id` en vez de `provider` y `amount`, y OnePay genera el documento fiscal con tu resolución. Ver [Facturación electrónica](/client/electronic-invoices/index).
</Note>

## ¿Cuándo usar Facturas?

| Escenario                                                                | Solución                           |
| ------------------------------------------------------------------------ | ---------------------------------- |
| Cobro desde un sistema de gestión externo (SAEplus, Wispro, Siigo, etc.) | Usa Facturas                       |
| Cobro con detalle de items y datos de facturación                        | Usa Facturas                       |
| Dividir el pago entre múltiples destinatarios                            | Usa Facturas con splits            |
| Cobro en múltiples abonos                                                | Usa Facturas con `partial_payment` |

***

## Flujo de integración

El flujo completo para integrar facturas tiene estos pasos clave:

```mermaid theme={null}
sequenceDiagram
    participant SG as Sistema de Gestion
    participant OP as OnePay
    participant CF as Cliente Final
    Note over SG,CF: Flujo principal de facturacion
    SG->>OP: 1. POST /invoices (Crear factura)
    Note right of OP: OnePay crea internamente un cobro asociado a la factura creada.
    OP->>CF: 2. Envia link/cobro al cliente final (WhatsApp, email, etc.)
    CF->>OP: 3. Paga la factura (via OnePay)
    OP->>OP: 4. Actualiza estado de factura = Pagada
    OP-->>SG: 5. Webhook notificacion de pago exitoso
    alt El sistema necesita modificar el valor o datos de la factura
        SG->>OP: 6. PUT /invoices/{invoice} (Actualizar factura)
        Note right of OP: OnePay crea un nuevo cobro con el valor actualizado.
        OP->>CF: 7. Envia nuevo cobro al cliente final
    end
    alt El pago se hizo por otro proveedor externo
        SG->>OP: 8. DELETE /invoices/{invoice} (Eliminar factura)
        Note right of OP: OnePay elimina el cobro asociado y detiene el seguimiento de pago.
    end
```

<Warning>
  Para homologar la integración de facturas, tu sistema debe implementar las siguientes capacidades:

  1. **Crear facturas** — `POST /invoices` para sincronizar facturas desde tu sistema de gestión hacia OnePay.
  2. **Recibir confirmación de pago** — Webhook `invoice.paid` para saber cuándo una factura fue pagada a través de OnePay.
  3. **Actualizar facturas** — `PUT /invoices/{invoice}` para reflejar cambios de valor o datos de la factura.
  4. **Eliminar facturas** — `DELETE /invoices/{invoice}` para cancelar facturas o marcarlas como pagadas por otro medio distinto a OnePay.
</Warning>

### Crear factura

Al llamar a `POST /invoices`, OnePay:

* Crea un registro de factura con estado `CREATED`
* Genera un **Payment** asociado con `source = INVOICE`
* Si ya existe una factura con el mismo `company + provider + reference` en estado `CREATED`, retorna la existente (idempotencia implícita)
* Retorna la factura con los datos del payment y su `payment_link`

<Info>
  Al crear una factura, la respuesta incluye el campo `id` — este es el **identificador único de la factura en OnePay**.
  Guárdalo en tu sistema ya que lo necesitarás para [actualizar](/client/invoices/update) o [eliminar](/client/invoices/delete) la factura posteriormente.

  **Recomendación:** Almacena este valor como `external_id` (o equivalente) en tu sistema de gestión para asociar fácilmente tus registros con OnePay.
</Info>

### Webhooks

OnePay notifica automáticamente los cambios de estado de cada factura. Configura los [eventos de facturas](/client/webhooks/index#facturas) en tu webhook para recibirlos.

Para ver la estructura completa del payload que recibirás, consulta los [ejemplos de webhooks de facturas](/client/webhooks/ejemplos#facturas).

### Actualizar factura

Al llamar a `PUT /invoices/{invoice}`:

* **Si el payment aún no se pagó:** OnePay cancela el payment anterior y crea uno nuevo con los datos actualizados. Se envía un nuevo cobro al cliente.
* **Si el payment ya se pagó:** Solo se actualizan los campos informativos (nombre, monto, referencia), sin generar un nuevo cobro.
* El campo `provider` no se puede modificar.

### Eliminar factura

Al llamar a `DELETE /invoices/{invoice}`:

* No se puede eliminar una factura con estado `PAID` o `CONCILIATED` (retorna HTTP 409)
* OnePay cancela el payment asociado
* La factura se marca según el `reason`: `PAID_FROM_PROVIDER` (pagada externamente) o `DELETE_FROM_PROVIDER` (eliminada)
* Se detiene todo seguimiento y recordatorios de cobranza

***

## Estados de una factura

| Estado                 | Descripción                                                |
| ---------------------- | ---------------------------------------------------------- |
| `CREATED`              | Factura creada, cobro enviado al cliente                   |
| `PAID`                 | Pagada en OnePay, pendiente conciliación con el proveedor  |
| `CONCILIATED`          | Pagada y conciliada exitosamente con el sistema de gestión |
| `PAID_FROM_PROVIDER`   | Marcada como pagada desde el sistema externo               |
| `DELETE_FROM_PROVIDER` | Eliminada desde el sistema externo                         |
| `FAILED`               | Fallo en la creación o procesamiento                       |

***

## Endpoints

| Método   | Endpoint                 | Descripción                   |
| -------- | ------------------------ | ----------------------------- |
| `POST`   | [/invoices](create)      | Crear factura                 |
| `GET`    | [/invoices](list)        | Listar facturas               |
| `GET`    | [/invoices/{id}](get)    | Detalle de una factura        |
| `PUT`    | [/invoices/{id}](update) | Actualizar factura            |
| `DELETE` | [/invoices/{id}](delete) | Eliminar factura              |
| `DELETE` | [/invoices](bulk-delete) | Eliminar facturas masivamente |