# Ciclo de vida de la factura

Una factura recorre el camino desde su creación hasta cerrarse o vencer. Esta sección describe los estados en los que puede encontrarse, cómo pasa de uno a otro y qué puede hacer el comercio en cada paso.

## Estados de la factura

| Estado    | Valor en la API | Descripción                                                                             | Participa en la búsqueda de pagos            |
| --------- | --------------- | --------------------------------------------------------------------------------------- | -------------------------------------------- |
| Sin pagar | `unpaid`        | La factura está emitida, el plazo de pago no ha vencido, no se ha recibido ningún pago  | Sí                                           |
| Pagada    | `paid`          | Se ha encontrado un pago y se ha asociado a la factura                                  | No                                           |
| Vencida   | `expired`       | El plazo de pago ha vencido, no se ha recibido ningún pago                              | Sí, durante una hora más tras el vencimiento |
| Cancelada | `canceled`      | La factura fue cancelada por el comercio manualmente o a través de la API               | No                                           |

## Transiciones de estado

* **Creación de la factura.** La factura recibe de inmediato el estado Sin pagar.
* **Sin pagar → Pagada.** Llegó un pago por el importe exacto de la factura, o el comercio asoció un pago manualmente.
* **Sin pagar → Vencida.** El plazo de pago venció sin que se recibiera un pago.
* **Sin pagar → Cancelada.** El comercio canceló la factura.
* **Vencida → Pagada.** El pago llegó dentro de la hora posterior al vencimiento y se encontró automáticamente, o el comercio lo asoció manualmente.
* **Cancelada.** Estado final; no hay vuelta atrás.

Una factura en el estado Pagada tampoco cambia de estado —no se puede volver a pagar ni cancelar.

## Plazo de pago

El plazo se establece al crear la factura y va de 30 minutos a 12 horas. Valores permitidos: 30 minutos, 1 hora, 3 horas, 6 horas, 12 horas.

Hasta el plazo, el cliente ve el formulario de pago y puede pagar la factura. Tras el vencimiento, la factura pasa a Vencida y el formulario de pago deja de ofrecer el pago.

Ambos extremos tienen su precio. Un plazo corto es arriesgado en redes lentas —el cliente puede no llegar a tiempo. Uno largo amplía la brecha entre el tipo de cambio al crear la factura y el tipo de cambio al pagarla.

## Ventana de búsqueda de pagos

La búsqueda de pagos continúa durante una hora más después del plazo de pago —para tener en cuenta las redes lentas, donde una transacción puede confirmarse cuando la factura ya ha vencido formalmente. Durante todo ese tiempo el cliente ve la factura como vencida, pero cuando llega un pago por el importe correcto, la factura pasa automáticamente a Pagada con todas las notificaciones.

De ahí la regla para integradores: no rechaces una notificación de pago porque el plazo haya pasado —esa comprobación corta una parte de los pagos reales.

## Cancelación de una factura

Puedes cancelar una factura si contiene un error. La cancelación exige dos condiciones:

* La factura no está pagada —es decir, está en el estado Sin pagar
* Nadie ha abierto la página de pago de la factura; el contador de vistas está en cero

La segunda condición protege contra la cancelación de una factura que el cliente ya ha visto y quizá ha empezado a pagar.

La cancelación es irreversible. Una factura cancelada queda excluida de la búsqueda de pagos, y no se le puede asociar un pago ni siquiera manualmente. Si el pago es probable, espera a que venza el plazo en lugar de cancelar —una factura vencida aún puede cerrarse con un pago.

## Qué queda fijado al crear y qué se recalcula al pagar

Al crear la factura, el servicio convierte el importe fiat a cripto al tipo de cambio actual y fija los importes resultantes para la factura. Esos son los importes que ve el cliente, y esos son los que el servicio busca on-chain. El tipo de cambio ya no les afecta: pase el tiempo que pase, el cliente paga exactamente el importe fijado.

En el momento del pago se recalculan los importes contables:

| Campo               | Qué ocurre                                                                                          |
| ------------------- | --------------------------------------------------------------------------------------------------- |
| `amountFiat`        | El importe original de la factura en moneda fiat. Nunca cambia                                      |
| `amountFiatUSD`     | Se sobrescribe con el importe realmente recibido, convertido a USD al tipo de cambio del momento del pago |
| `commissionFiatUSD` | Se recalcula a partir del nuevo valor de `amountFiatUSD` según la tarifa del proyecto               |

Por el movimiento del tipo de cambio, estos valores pueden diferir de los originales incluso cuando el pago es exacto. Para conciliar con el pedido en tu tienda usa `amountFiat` —el único importe que permanece sin cambios.

## Notificaciones a lo largo de la vida de la factura

Las notificaciones se configuran por proyecto. Una factura tiene dos:

* **Pago entrante** (Incoming payment). Se envía al correo y a Telegram cuando se detecta cualquier transacción entrante en tu billetera, haya coincidido o no con una factura.
* **Factura pagada** (Invoice paid). Se envía al correo, a Telegram y al Webhook URL en el momento en que la factura pasa a Pagada —tanto con la asociación automática como con la manual.

Esto da una regla de diagnóstico sencilla: si llegó una notificación de pago entrante pero no la siguió una de factura pagada, el pago no coincidió por una discrepancia de importes y requiere gestión manual.

## Retorno del cliente al sitio de la tienda

En la configuración del proyecto puedes establecer dos URL a las que el cliente vuelve desde la página de pago:

* **URL de éxito** (Successful URL) —redirección automática después de pagarse la factura
* **URL de fallo** (Unsuccessful URL) —redirección automática al abrir una factura vencida o cancelada

Cada URL se activa por separado. Si una URL no está configurada, el cliente permanece en la página de pago y ve el estado de la factura.

El parámetro `uid` —el identificador de la factura para el cliente— se añade a la URL: `https://example.com/order/success?uid=AFhygKX21ecd`. La tienda lo usa para encontrar el pedido y mostrar al cliente su propia página.

Llegar a estas URL no confirma el pago —el cliente puede abrir el enlace manualmente. Entrega los pedidos según el [webhook](./webhook-url/index.md) o tras [comprobar el estado de la factura](./api/index.md) a través de la API.