# Fase 1: Verificação de Saldo (API Direta)

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.

Na Fase 1 das Smart Collections, você delega o monitoramento de saldo para a Belvo. Você define **Instruções de Cobrança**, estabelecendo os valores que deseja cobrar e as condições de saldo que devem ser atendidas, e a Belvo monitora a conta vinculada em segundo plano. Quando uma conta tem dinheiro suficiente, a Belvo notifica você para que possa coletá-lo na Fase 2.

Produto de Agregação
A verificação de saldo faz parte do produto de **agregação** da Belvo: ela depende do consentimento OFDA e dos dados bancários do Link do usuário.
Portanto, você deve completar primeiro os pré-requisitos das Smart Collections, pois você precisa de um Link OFDA (`link_id`) para criar Instruções de Cobrança e um endpoint de webhook para receber eventos de saldo.

A Fase 1 cobre três etapas: você cria uma Instrução de Cobrança, a Belvo monitora o saldo da conta em relação a ela, e a Belvo envia um webhook para você assim que houver fundos suficientes para coletar.


```mermaid
sequenceDiagram
    participant Client as Your application
    participant Aggregation as Belvo Aggregation API

    Note over Client, Aggregation: 1. Create the Collection Instruction

    Client->>Aggregation: POST /api/collection-instructions/
    Aggregation-->>Client: 201 Created (instruction and item IDs)

    Note over Client, Aggregation: 2. Belvo monitors the balance

    loop Within your collection windows, until the balance is sufficient
        Aggregation->>Aggregation: Check whether the account balance covers the amount
    end

    Note over Client, Aggregation: 3. Belvo signals that funds are available

    Aggregation->>Client: Webhook: item_ready_to_charge
    Note over Client, Aggregation: Carries the item_id, your external_id, and the amount.<br/>Continue in Phase 2 to create the Charge.
```

## 1. Criar uma Instrução de Cobrança

Uma **Instrução de Cobrança** indica quanto você deseja cobrar do seu usuário (`link_id`) e por qual período de tempo. A Belvo usa essas informações para monitorar o saldo da conta do link e, assim que a condição de saldo for atendida, você receberá um evento de webhook indicando que pode transferir fundos para um determinado valor.

Cada item de Instrução de Cobrança no array `items` refere-se a uma cobrança singular que você deseja realizar. **A maioria das integrações cria uma Instrução de Cobrança por dívida**: um único item descrevendo essa dívida, com uma ou mais políticas de cobrança. (Uma instrução pode conter vários itens se você quiser agrupar várias dívidas em uma única chamada, mas um item por dívida é o padrão comum.)

Para criar uma, faça uma solicitação POST Criar uma instrução de cobrança:


```json Corpo da Solicitação para Criar uma Instrução de Cobrança
{
  "link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "items": [
    {
      "amount": "150.50",
      "external_id": "inv-2026-001",
      "collection_policies": [
        {
          "start_date": "2026-11-01",
          "end_date": "2026-11-10",
          "amount": "150.50"
        },
        {
          "start_date": "2026-11-21",
          "end_date": "2026-11-30",
          "amount": "150.50"
        }
      ]
    }
  ]
}
```

O que uma política de cobrança faz
Uma política de cobrança define uma **janela de tempo** durante a qual a Belvo verifica a conta. Adicione mais de uma política a um item para controlar *quando* o monitoramento acontece. No exemplo acima, a Belvo verifica durante os primeiros dez dias de novembro, faz uma pausa e depois verifica novamente nos últimos dez dias. **Nenhuma verificação acontece durante o intervalo** entre as janelas.

Tanto `start_date` quanto `end_date` são **inclusivos**, então uma janela vai até o final de seu `end_date`.

A Belvo notifica você assim que o saldo disponível de **qualquer uma** das contas do usuário for maior que o `amount` do item, e então para de monitorar esse item. Saldos entre contas não são somados.

Janelas são avaliadas em UTC
As janelas de cobrança vão de 00:00 UTC no `start_date` até 23:59:59 UTC no `end_date`, não no horário local do pagador. No horário de Brasília, uma janela abre às 21:00 do dia anterior ao `start_date` e fecha às 20:59 no `end_date`.

Dentro de uma janela, a Belvo verifica o saldo cerca de sete vezes por dia, em horários variados. Um saldo que é apenas brevemente alto o suficiente pode ser perdido.

O saldo disponível inclui cheque especial
A Belvo usa o saldo disponível da conta conforme relatado pelo banco, que pode incluir um limite de cheque especial. Um usuário pode, portanto, acionar `item_ready_to_charge` com menos dinheiro próprio do que o `amount` do item.

| Parâmetro | Obrigatório | Descrição |
|  --- | --- | --- |
| `link_id` | true | O `id` do Link OFDA para o usuário cujo saldo da conta você deseja monitorar. Deve ser um Link ativo que pertença à sua organização, caso contrário, a Belvo responde com `400 - Bad Request`. |
| `items` | true | Array de itens, com pelo menos uma entrada. Cada item é um valor que você deseja cobrar, com uma ou mais políticas de cobrança. A maioria das Instruções de Cobrança tem exatamente **um** item, uma dívida por instrução. |
| `items[].amount` | true | O valor que você deseja cobrar por este item, como uma string. A Belvo notifica você assim que o saldo disponível de uma das contas do usuário for maior que este valor. |
| `items[].external_id` | opcional (fortemente recomendado) | Sua própria referência para este item. A Belvo não vincula Instruções de Cobrança à Autorização de Pagamento ou Cobrança que você cria na Fase 2, então é assim que você vincula um webhook aos seus registros. Defina isso a menos que você tenha um motivo para não fazê-lo. Como a maioria das instruções contém um item por dívida, isso é tipicamente sua referência para a dívida como um todo. |
| `items[].collection_policies` | true | Array de políticas, com pelo menos uma entrada. Cada política define uma janela de tempo (`start_date` a `end_date`) durante a qual a Belvo verifica a conta. Use várias políticas para controlar quando o monitoramento acontece. |
| `items[].collection_policies[].start_date` | true | A primeira data em que a Belvo verifica a conta, no formato `YYYY-MM-DD`. Inclusivo. |
| `items[].collection_policies[].end_date` | true | A última data em que a Belvo verifica a conta, no formato `YYYY-MM-DD`. Avaliado em UTC, veja a nota abaixo. |
| `items[].collection_policies[].amount` | true | O valor para esta janela, como uma string. Defina-o para o valor que você deseja cobrar pelo item. Veja a nota abaixo. |


Defina o valor de cada política para o valor do item
Cada política requer um `amount`, mas hoje a Belvo compara o saldo com o `amount` do **item** em cada janela, e o `amount` de uma política não tem efeito. Defina o `amount` de cada política para o mesmo valor do `amount` do item.


```json Resposta de Criação de Instrução de Cobrança (201 Created)
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", // [!code highlight]
  "link_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "PROCESSING",
  "created_at": "2026-10-25T14:22:10.123456Z",
  "updated_at": "2026-10-25T14:22:10.123456Z",
  "items": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", // [!code highlight]
      "amount": "150.50",
      "external_id": "inv-2026-001",
      "status": "PENDING",
      "created_at": "2026-10-25T14:22:10.234567Z",
      "updated_at": "2026-10-25T14:22:10.234567Z",
      "collection_policies": [
        {
          "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
          "start_date": "2026-11-01",
          "end_date": "2026-11-10",
          "amount": "150.50",
          "created_at": "2026-10-25T14:22:10.345678Z"
        },
        {
          "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
          "start_date": "2026-11-21",
          "end_date": "2026-11-30",
          "amount": "150.50",
          "created_at": "2026-10-25T14:22:10.345678Z"
        }
      ]
    }
  ]
}
```

A instrução começa em `PROCESSING` e cada item em `PENDING`. Veja Status e webhooks para o ciclo de vida completo.

Salve os IDs da instrução e dos itens
Armazene o `id` da instrução e o `id` de cada item desta resposta. Você precisa do `id` da instrução para verificar ou cancelar a instrução, e você precisa de ambos os IDs para cancelar um único item. Nenhum endpoint resolve um `id` de item de volta para sua instrução pai. Se você perder um `id` de instrução, pode encontrá-lo novamente listando suas instruções.

## 2. Ouça o webhook `item_ready_to_charge`

Quando a condição de saldo é atendida, a Belvo envia um único webhook e para de monitorar esse item. O item se move para `CHARGE_SETTLED`, o que apenas significa que o webhook foi enviado: ainda não existe uma Cobrança.


```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",
  "external_id": null,
  "data": {
    "item_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "external_id": "inv-2026-001",
    "amount": "150.50"
  }
}
```

O payload identifica o item correspondente (`data.item_id`) e seu `external_id`, junto com o `amount` a ser coletado. Este é um webhook de **agregação**, portanto, não possui versionamento V1/V2. Para uma análise detalhada campo a campo, veja Status e webhooks.

Use external_id para conectar as fases
A Belvo não vincula uma Instrução de Cobrança à Autorização de Pagamento ou Cobrança que você cria em seguida, então use `data.external_id` (ou `data.item_id`) para correlacionar este webhook com a Cobrança que você aciona na Fase 2.

Quando você receber `item_ready_to_charge`, prossiga para Fase 2 e cobre `data.amount` contra a Autorização de Pagamento do usuário.

Nenhum webhook é enviado se o saldo nunca for suficiente
Se nenhuma das janelas de um item encontrar saldo suficiente até sua `end_date`, o item se move para `POLICY_EXPIRED` **silenciosamente, sem envio de webhook**. O mesmo acontece se a Belvo não conseguir ler as contas do usuário (`CHARGE_REJECTED`). Não espere indefinidamente por `item_ready_to_charge`: acompanhe a última `end_date` dos seus itens e reconcilie qualquer item que nunca tenha produzido uma Cobrança do seu lado.

## Verifique o status dos seus itens

A Belvo só envia um webhook quando um item atinge `CHARGE_SETTLED`. Para descobrir como qualquer outro item terminou, ou para se recuperar caso tenha perdido um webhook, obtenha os detalhes da instrução e leia o `status` de cada item:


```shell Get a Collection Instruction
curl --request GET 'https://api.belvo.com/api/collection-instructions/{instruction_id}/' \
  -u SECRET_ID:SECRET_PASSWORD
```

A Belvo responde com `200 - OK` e o mesmo objeto que você recebeu quando criou a instrução, com o `status` atual de cada item. Veja Obter detalhes de uma instrução de cobrança. O próprio `status` da instrução permanece `PROCESSING` até que você a cancele, mesmo depois que cada item atinge um status final, então sempre leia os status dos itens.

Para encontrar uma instrução quando você não tem seu `id`, faça uma solicitação GET Listar instruções de cobrança:


```shell List Collection Instructions
curl --request GET 'https://api.belvo.com/api/collection-instructions/?created_after=2026-11-01&created_before=2026-12-01' \
  -u SECRET_ID:SECRET_PASSWORD
```

A resposta é um array de resumos (`id`, `link_id`, `status` e timestamps) que **não inclui os itens**. Obtenha os detalhes de uma instrução para vê-los.

| Parâmetro de consulta  | Descrição |
|  --- | --- |
| `status` | Retorna apenas instruções com este status (`PROCESSING` ou `CANCELLED`). |
| `created_after` | Retorna apenas instruções criadas nesta data ou depois (`YYYY-MM-DD`), a partir de 00:00 UTC. |
| `created_before` | Retorna apenas instruções criadas antes desta data (`YYYY-MM-DD`). A própria data é excluída. |


O filtro `consent_id` também está disponível, veja a referência da API.

Mantenha as solicitações de lista pequenas e não espere uma ordem
A lista não é paginada e sua ordem não é garantida. Sempre envie `created_after` e `created_before`, para que a resposta cubra apenas o período que você deseja reconciliar. Um valor de filtro que não é válido, por exemplo, um `status` desconhecido ou uma data que não está no formato `YYYY-MM-DD`, retorna um genérico `500 - Internal Server Error`.

Com que frequência verificar
Use essas solicitações para reconciliar, não como seu sinal principal: o webhook `item_ready_to_charge` é como você descobre que um item está pronto. A Belvo verifica saldos cerca de sete vezes por dia, então perguntar com mais frequência não traz informações mais cedo. Um bom momento para verificar um item é após sua última `end_date`, para encontrar itens que terminaram como `POLICY_EXPIRED`, `CHARGE_REJECTED` ou `FAILED`.

Um `instruction_id` que não existe ou não pertence à sua organização retorna um genérico `500 - Internal Server Error`. Um `instruction_id` que não é um UUID retorna `404 - Not Found`.

## Tentar novamente após uma coleta interrompida

O monitoramento de um item para permanentemente assim que a Belvo envia `item_ready_to_charge`, ou quando suas janelas terminam sem fundos suficientes. Uma Instrução de Cobrança **não** retoma o monitoramento por conta própria, mesmo após uma Cobrança que você criar posteriormente ser rejeitada. Para tentar coletar novamente, crie uma **nova** Instrução de Cobrança. Reutilizar o mesmo `external_id` no novo item é permitido.

## Marcar um item como concluído

Se você coletar o valor de um item de outra forma antes que a Belvo encontre saldo suficiente, por exemplo, porque seu usuário paga diretamente a você, marque o item como concluído. A Belvo para de monitorá-lo, e o status do item se torna `COMPLETED`, para que seus registros e os da Belvo concordem sobre por que o monitoramento terminou.

Faça uma solicitação PATCH Marcar um item de instrução de cobrança como concluído, e identifique o item pelo seu `id` ou pelo `external_id` que você forneceu:

Por item id

```shell Marcar um item como concluído
curl --request PATCH 'https://api.belvo.com/api/items/complete/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'Content-Type: application/json' \
  --data '{
    "item_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  }'
```

Por external_id

```shell Marcar um item como concluído
curl --request PATCH 'https://api.belvo.com/api/items/complete/' \
  -u SECRET_ID:SECRET_PASSWORD \
  -H 'Content-Type: application/json' \
  --data '{
    "external_id": "inv-2026-001"
  }'
```

| Parâmetro  | Obrigatório | Descrição |
|  --- | --- | --- |
| `item_id` | um dos dois | O `id` do item, da resposta de Instrução de Cobrança. |
| `external_id` | um dos dois | O `external_id` que você definiu no item. Deve corresponder exatamente a um item na sua organização. |


Envie exatamente um de `item_id` ou `external_id`. A Belvo responde com `200 - OK` e o item:


```json Resposta: 200 - OK
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "amount": "150.50",
  "external_id": "inv-2026-001",
  "status": "COMPLETED", // [!code highlight]
  "created_at": "2026-10-25T14:22:10.234567Z",
  "updated_at": "2026-11-05T09:12:44.104311Z",
  "collection_policies": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "start_date": "2026-11-01",
      "end_date": "2026-11-10",
      "amount": "150.50",
      "created_at": "2026-10-25T14:22:10.345678Z"
    },
    {
      "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "start_date": "2026-11-21",
      "end_date": "2026-11-30",
      "amount": "150.50",
      "created_at": "2026-10-25T14:22:10.345678Z"
    }
  ]
}
```

Apenas itens PENDING podem ser concluídos
Você só pode marcar um item como concluído enquanto seu status for `PENDING`. Se uma verificação de saldo estiver em andamento (`PROCESSING`), tente novamente alguns momentos depois. Itens em qualquer outro status não podem ser concluídos.

No momento, toda solicitação rejeitada (um item que não está `PENDING`, um `item_id` desconhecido ou um `external_id` compartilhado por vários de seus itens) retorna um genérico `500 - Internal Server Error`. Use o `id` do item quando possível, para evitar correspondências ambíguas.

A diferença de cancelar é o motivo que você registra: `COMPLETED` significa que o valor foi coletado fora da Belvo, e `CANCELLED` significa que você não deseja mais coletá-lo.

## Cancelar uma Instrução de Cobrança

Para parar o monitoramento da Belvo porque você não deseja mais coletar, por exemplo, se a dívida foi renegociada ou baixada, cancele toda a instrução ou um único item com um `PATCH`. (O cancelamento é um `PATCH` em vez de um `DELETE` para que a Belvo mantenha um histórico de auditoria.)

| Ação | Endpoint | Comportamento |
|  --- | --- | --- |
| Cancelar toda a instrução | `PATCH /api/collection-instructions/{instruction_id}/` | Cancela todos os itens que ainda estão `PENDING` ou `PROCESSING`, e define a instrução como `CANCELLED`. Retorna a instrução. |
| Cancelar um único item | `PATCH /api/collection-instructions/{instruction_id}/items/{item_id}/` | Apenas enquanto o item estiver `PENDING` ou `PROCESSING`. Retorna o item, agora `CANCELLED`. |


Nenhuma das requisições requer um corpo. Veja Cancelar uma instrução de cobrança e Cancelar um item de instrução de cobrança. A Belvo responde com `200 - OK`.

Tenha em mente os seguintes pontos:

- **O cancelamento não pode ser desfeito.** Para monitorar novamente, crie uma nova Instrução de Cobrança.
- **Status finais permanecem como estão.** Itens que já atingiram um status final, como `CHARGE_SETTLED` ou `COMPLETED`, mantêm seu status quando você cancela sua instrução.
- **Cancelar um item não altera sua instrução.** A instrução permanece `PROCESSING`, mesmo que você tenha cancelado seu último item ativo.
- **Cancelar a mesma instrução duas vezes é seguro.** A Belvo responde com `200 - OK` novamente.


Requisições rejeitadas retornam um genérico 500
A Belvo retorna um genérico `500 - Internal Server Error` quando a instrução ou item não existe, não pertence à sua organização, ou não está em um status que permita o cancelamento (para um item, `PENDING` ou `PROCESSING`). Um item que não pertence à instrução no caminho é rejeitado da mesma forma. Um ID que não é um UUID retorna `404 - Not Found`. Verifique o status de um item com Obter uma Instrução de Cobrança antes de cancelá-lo.