# Estado de facturas y depósitos

Consulta una factura o depósito mediante la API, con o sin webhooks.

Source: https://docs.invoise.me/es/payments/status/

Consulta el estado de la factura o el depósito mediante solicitudes GET. Los webhooks te notifican los cambios automáticamente.

## Consulta una factura o depósito

Usa el `id` que se devolvió al crear la factura o el depósito:

```bash
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/issuances/{issuance_id}' \
  -H 'Authorization: Bearer ivk_...'
```

Campos relevantes de una respuesta de ejemplo (se omiten otros campos):

```json
{
  "id": "f06b8a31-19c7-4687-ade3-1c09466d2751",
  "kind": "invoice",
  "status": "funded",
  "amount": "10000000",
  "received": "10000000",
  "token_decimals": 6,
  "expires_at": "2026-10-19T10:00:00Z",
  "cancelled_at": null,
  "disabled_at": null,
  "payout_tx_hash": null
}
```

Ambos importes son cadenas de enteros en unidades base. Este ejemplo significa que llegaron 10 tokens, pero todavía no se muestra ninguna transacción de pago confirmada.

## Interpreta una factura

| `status` | Qué hacer |
| --- | --- |
| `registering` | Espera a que `address` no esté vacío. No la derives tú mismo. |
| `open` | Sigue esperando. `received` puede mostrar un pago parcial. |
| `funded` | Hay fondos confirmados suficientes disponibles para la liquidación. |
| `settled` | La factura se cerró en la cadena. |
| `reconciling` | Espera la reconciliación; no lo trates como un pago exitoso. |

Comprueba también `cancelled_at`. Es una marca de tiempo o `null`, no un valor de estado. Se define cuando cancelas la factura, cuando una factura sin pagar supera su `expires_at`, o cuando el personal de Invoise bloquea el comercio; el webhook `invoice.cancelled` distingue estos casos mediante [`data.reason`](https://docs.invoise.me/es/integration/webhooks/#2-elige-los-eventos-que-necesitas). La cancelación oculta la página de pago pero no detiene los fondos entrantes ni la liquidación. Decide explícitamente cómo gestiona tu negocio una factura pagada y cancelada.

`funded` significa que se recibió el pago, no que el pago al destinatario se completó. `settled` registra el cierre de la factura. Para la contabilidad completa del pago, usa `payout.confirmed`; `payout_tx_hash` identifica la última transferencia saliente confirmada al destinatario, cuando está disponible.

Si recibes `transfer.reverted`, Invoise está informando de la reversión de una transferencia entrante concreta en la red. Identifícala mediante `chain_event.reference_event_id`, consulta el estado actual de la factura y ajusta tu registro de esa transferencia una sola vez. Consulta [Webhooks](https://docs.invoise.me/es/integration/webhooks/) para ver el formato del evento.

## Sigue los depósitos

Una dirección de depósito es reutilizable. Puede volver a `open` después de un pago, así que no esperes a que quede en `settled` de forma permanente.

`received` es el **dinero entrante confirmado acumulado**, no el saldo restante. Un pago no se resta de él. Puede disminuir cuando se revierte una transferencia. Acredita cada pago entrante una sola vez; los webhooks son útiles para esto porque cada evento tiene un ID estable.

`disabled_at` controla la disponibilidad de la página de pago. Deshabilitar un depósito no detiene el monitoreo de su dirección.

## Lista facturas y depósitos

```bash
curl 'https://platform.invoise.me/api/v1/shops/{shop_id}/payments?limit=50' \
  -H 'Authorization: Bearer ivk_...'
```

Con `limit` (1–100), la respuesta es `{"items":[...],"next_cursor":"..."}`. Envía `cursor` para la página siguiente hasta que `next_cursor` esté vacío. Sin parámetros de paginación, el endpoint devuelve un array limitado; no es el historial completo.

La lista admite los filtros `kind`, `status` y `q`. Su filtro `status=paid` selecciona `funded` y `settled`; `paid` no es un estado de operación devuelto por el endpoint de detalle.

El campo `transfers` del endpoint de detalle contiene solo las diez entradas confirmadas más recientes de entrada/pago. No lo uses como un libro contable completo.

## Estado público de la página de pago

`GET /api/v1/checkout/{public_id}` no necesita credenciales. Proporciona el estado de la página de pago, incluidos `status`, `received`, `amount` y `expires_at`. Usa el endpoint de operación autenticado para los registros de tienda de tu backend.

Para actualizaciones push y comprobación de firma, consulta [Webhooks](https://docs.invoise.me/es/integration/webhooks/).