# Statuses e webhooks

Beta
Smart Collections está atualmente em Beta. Alguns contratos nesta página ainda estão sendo confirmados com nossa equipe de engenharia, portanto, trate-os como provisórios e espere refinamentos antes da disponibilidade geral, incluindo:

- Payloads de webhook e códigos de eventos
- Atualizações de referência da API para os endpoints de Collection Instructions, Payment Authorization e Charge
- Nomes de campos e melhorias na documentação (terminologia, diagramas)


Entre em contato com seu gerente de conta da Belvo para participar do programa Beta.

Esta página é a referência para os status de objetos e webhooks usados em ambas as fases do Smart Collections. Para o fluxo passo a passo, veja Fase 1 e Fase 2.

## Statuses

## Statuses

Os status são usados para indicar o estado atual de uma operação ou recurso dentro da API. Abaixo estão os status comuns que você encontrará ao trabalhar com a API da Belvo.

### Status de Conexão

- **valid**: A conexão está ativa e funcionando corretamente.
- **invalid**: A conexão não é mais válida e precisa ser atualizada.
- **pending**: A conexão está em processo de validação.
- **error**: Ocorreu um erro ao tentar validar a conexão.


### Status de Transação

- **completed**: A transação foi concluída com sucesso.
- **failed**: A transação falhou e não foi concluída.
- **pending**: A transação está em andamento e ainda não foi concluída.
- **canceled**: A transação foi cancelada pelo usuário ou pelo sistema.


### Status de Pagamento

- **paid**: O pagamento foi realizado com sucesso.
- **unpaid**: O pagamento ainda não foi realizado.
- **refunded**: O pagamento foi reembolsado ao usuário.
- **disputed**: O pagamento está em disputa e requer revisão.


Esses status ajudam a monitorar e gerenciar as operações dentro da API de forma eficaz.

### Instrução de Coleta

| Status  | Significado |
|  --- | --- |
| `PROCESSING` | Criado. A Belvo está monitorando (ou já terminou de monitorar) seus itens. Uma instrução permanece `PROCESSING` até que você a cancele; verifique o status de cada item para ver como o monitoramento terminou. |
| `CANCELLED` | Você cancelou a instrução. Quaisquer itens que ainda estavam sendo monitorados foram cancelados também. |


### Instrução de Coleta de item

Apenas `CHARGE_SETTLED` envia um webhook. Para ler o status de qualquer item, obtenha os detalhes da instrução.


```mermaid
stateDiagram-v2
    [*] --> PENDING
    PENDING --> PROCESSING: a balance check starts
    PROCESSING --> PENDING: not enough funds yet
    PROCESSING --> CHARGE_SETTLED: enough funds, webhook sent
    PROCESSING --> POLICY_EXPIRED: no collection window left
    PROCESSING --> CHARGE_REJECTED: the account can't be read
    PENDING --> COMPLETED: you mark it complete
    PENDING --> CANCELLED: you cancel it
    PROCESSING --> CANCELLED: you cancel it
```

| Status  | Significado |
|  --- | --- |
| `PENDING` | Aguardando a próxima verificação de saldo agendada. |
| `PROCESSING` | Uma verificação de saldo está em andamento. |
| `CHARGE_SETTLED` | O saldo cobriu o `amount` do item e a Belvo enviou `item_ready_to_charge`. O monitoramento para. Apesar do nome, este status **não** significa que uma Cobrança foi feita: você cria a Cobrança na Fase 2. |
| `POLICY_EXPIRED` | Todas as janelas de coleta do item terminaram sem saldo suficiente. **Nenhum webhook é enviado.** |
| `CHARGE_REJECTED` | A Belvo não conseguiu ler o saldo de nenhuma das contas do usuário (por exemplo, o consentimento de dados não é mais válido). **Nenhum webhook é enviado.** |
| `FAILED` | Um erro interno interrompeu o monitoramento. **Nenhum webhook é enviado.** |
| `COMPLETED` | Você marcou o item como completo (você o coletou fora da Belvo), então a Belvo parou de monitorá-lo. |
| `CANCELLED` | Você cancelou o item (ou toda a instrução). |


### Autorização de Pagamento e Cobrança

A Fase 2 utiliza Autorizações de Pagamento e Cobranças de Transferências Inteligentes. Para os seus status, consulte a referência de status de Transferências Inteligentes.

## Webhooks

O Smart Collections utiliza **dois canais de webhook**. Você deve configurar um endpoint para cada um.

| Canal  | Fase  | Eventos  | Versionamento |
|  --- | --- | --- | --- |
| Aggregation (`COLLECTIONS`) | Fase 1 | `item_ready_to_charge` | Nenhum (webhooks de agregação não são versionados) |
| Payments | Fase 2 | `PAYMENT_AUTHORIZATION`, `CHARGE` | `Payments-BR.V2` |


### Fase 1: `item_ready_to_charge` (Agregação)

Enviado uma vez, quando o saldo de uma das contas do usuário cobre o `amount` de um item. O item passa para `CHARGE_SETTLED` e a Belvo para de monitorá-lo.


```json item_ready_to_charge webhook
{
  "webhook_id": "e29b41d4a7164a4fae1112b8c9d3f5a2",
  "webhook_type": "COLLECTIONS",
  "webhook_code": "item_ready_to_charge",
  "process_type": null,
  "link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", // [!code warning]
  "external_id": null,
  "data": {
    "item_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "external_id": "inv-2026-001",
    "amount": "150.50"
  }
}
```

| Campo  | Descrição |
|  --- | --- |
| `webhook_id` | Um ID único para esta entrega de webhook. Use-o para detectar e descartar entregas duplicadas. |
| `webhook_type` | Sempre `COLLECTIONS` para este evento. |
| `webhook_code` | Sempre `item_ready_to_charge` para este evento. |
| `process_type` | Sempre `null` para este evento. |
| `link_id` | O `id` do Link OFDA que esta Instrução de Cobrança monitora. |
| `external_id` | Sempre `null` para este evento. Use `data.external_id` em vez disso. |
| `data.item_id` | O `id` do item da Instrução de Cobrança cuja condição de saldo foi atendida. |
| `data.external_id` | O `external_id` que você definiu para esse item, ou `null` se você não definiu um. |
| `data.amount` | O `amount` do item: o que você deve coletar na Fase 2, como uma string. |


Identifica o item, não a conta ou a política
O payload informa qual **item** foi correspondido, mas não qual das contas do usuário tinha o saldo, nem qual janela de `collection_policy` estava aberta. Para cobrar uma conta específica, veja Fase 2.

Veja Webhooks de Agregação para o envelope geral de webhook de Agregação.

Nenhum webhook quando o monitoramento termina sem fundos
Itens que terminam em `POLICY_EXPIRED`, `CHARGE_REJECTED` ou `FAILED` não acionam um webhook. Acompanhe o último `end_date` dos seus itens e reconcilie qualquer um que nunca produziu um `item_ready_to_charge`.

### Fase 2: `PAYMENT_AUTHORIZATION` e `CHARGE` (Pagamentos)

Estes são webhooks padrão `Payments-BR.V2`. Eles apenas informam que um recurso mudou, então você deve usar `GET` no recurso para ler seu status:


```json Payments V2 webhook
{
  "schema_version": "2.0.0",
  "resource": "CHARGE",
  "resource_id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "resource_version": "V2",
  "timestamp": "2026-10-16T15:00:07Z"
}
```

Para o formato do payload e como obter detalhes completos, consulte Webhooks de Pagamentos (Brasil).

### Confiabilidade de Webhooks

- **Configurações separadas por canal:** Os webhooks de `COLLECTIONS` são configurados separadamente dos webhooks de Pagamentos no painel do Belvo, cada um com sua própria URL e token Bearer opcional.
- **Autenticação:** O Belvo não assina webhooks (sem HMAC). Restrinja seu endpoint com uma lista de IPs permitidos dos IPs do Belvo e, opcionalmente, defina um token Bearer.
- **Repetições:** `item_ready_to_charge` é repetido até três vezes apenas quando o Belvo não consegue se conectar ao seu endpoint, então certifique-se de que seu endpoint seja acessível e responda rapidamente. Para repetições de webhooks de Pagamentos, veja Webhooks de Pagamentos (Brasil).
- **Ordenação:** webhooks podem chegar fora de ordem ou muito próximos uns dos outros. Como os webhooks de Pagamentos não carregam o status, fazer um `GET` por webhook mantém sua visão do status correta.
- **Recuperando eventos perdidos:** não há repetição de eventos. Execute uma tarefa recorrente que verifica autorizações e Cobranças que ainda não estão em um status final, e itens de Instrução de Cobrança que você ainda está aguardando.