# Status de fatura e depósito

Verifique uma fatura ou depósito pela API, com ou sem webhooks.

Source: https://docs.invoise.me/pt-br/payments/status/

Leia o estado da fatura ou depósito por requisições GET. Os webhooks avisam você das mudanças automaticamente.

## Leia uma fatura ou depósito

Use o `id` retornado quando você criou a fatura ou o depósito:

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

Campos relevantes de uma resposta de exemplo (outros campos omitidos):

```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 os valores são strings de números inteiros em unidades base. Este exemplo significa que 10 tokens chegaram, mas nenhuma transação de repasse confirmada é mostrada ainda.

## Interprete uma fatura

| `status` | O que fazer |
| --- | --- |
| `registering` | Aguarde um `address` não vazio. Não derive um você mesmo. |
| `open` | Continue aguardando. `received` pode mostrar um pagamento parcial. |
| `funded` | Fundos confirmados suficientes estão disponíveis para a liquidação. |
| `settled` | A fatura foi fechada na blockchain. |
| `reconciling` | Aguarde a reconciliação; não trate como um pagamento bem-sucedido. |

Verifique também `cancelled_at`. É um timestamp ou `null`, não um valor de status. É definido quando você cancela a fatura, quando uma fatura não paga passa do `expires_at`, ou quando a equipe do Invoise bloqueia o lojista; o webhook `invoice.cancelled` diferencia esses casos por [`data.reason`](https://docs.invoise.me/pt-br/integration/webhooks/#2-escolha-os-eventos-que-você-precisa). O cancelamento oculta a página de pagamento, mas não interrompe os fundos recebidos nem a liquidação. Decida explicitamente como seu negócio trata uma fatura paga e cancelada.

`funded` significa pagamento recebido, não repasse concluído. `settled` registra o fechamento da fatura. Para a contabilização completa do repasse, use `payout.confirmed`; `payout_tx_hash` identifica a última transferência de saída confirmada ao destinatário, quando disponível.

Se você receber `transfer.reverted`, o Invoise está informando a reversão de uma transferência recebida específica na rede. Identifique-a por `chain_event.reference_event_id`, leia o estado atual da fatura e ajuste seu registro dessa transferência uma única vez. Veja [Webhooks](https://docs.invoise.me/pt-br/integration/webhooks/) para o formato do evento.

## Acompanhe depósitos

Um endereço de depósito é reutilizável. Ele pode voltar a `open` após um repasse, então não espere que ele se torne `settled` permanentemente.

`received` é **o total acumulado de dinheiro recebido confirmado**, não o saldo restante. Um repasse não é subtraído dele. Ele pode diminuir quando uma transferência é revertida. Credite cada pagamento recebido apenas uma vez; os webhooks são úteis para isso porque cada evento tem um ID estável.

`disabled_at` controla a disponibilidade da página de pagamento. Desativar um depósito não interrompe o monitoramento do seu endereço.

## Liste faturas e depósitos

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

Com `limit` (1–100), a resposta é `{"items":[...],"next_cursor":"..."}`. Envie `cursor` para a próxima página até que `next_cursor` esteja vazio. Sem parâmetros de paginação, o endpoint retorna um array limitado; não é o histórico completo.

A listagem aceita os filtros `kind`, `status` e `q`. Seu filtro `status=paid` seleciona `funded` e `settled`; `paid` não é um status de issuance retornado pelo endpoint de detalhe.

O campo `transfers` do endpoint de detalhe contém apenas as dez entradas mais recentes de transferências recebidas/repasses confirmadas. Não o use como um livro-razão completo.

## Status público da página de pagamento

`GET /api/v1/checkout/{public_id}` não exige credenciais. Ele fornece o estado da página de pagamento, incluindo `status`, `received`, `amount` e `expires_at`. Use o endpoint autenticado de issuance para os registros de loja do seu back-end.

Para atualizações push e verificação de assinatura, veja [Webhooks](https://docs.invoise.me/pt-br/integration/webhooks/).