> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Início rápido de dados bancários: conecte um banco de teste e leia transações

> Da aplicação sandbox às contas, saldos e transações do Test Bank da Didit: crie chave e link, conecte, leia, sincronize e exclua.

Os dados bancários estão disponíveis para aplicações de sandbox.
Uma aplicação em produção recebe `404` nas chamadas até que o acesso em produção seja anunciado, e nada é cobrado no sandbox.
Este guia rápido leva você de uma aplicação de sandbox até as contas, saldos e transações do Didit Test Bank, com requisições prontas para copiar e colar.

> [!NOTE]
>
> Cada resposta abaixo foi encurtada para os campos que importam.
> Mantenha a chave de API no seu servidor: ela nunca chega a um navegador ou a um aplicativo.

## Passo 1: crie uma chave de API com a permissão Bank data

Bank data não faz parte do acesso total.
Uma chave com acesso total, incluindo o segredo principal da aplicação, é recusada em todas as chamadas de Bank data com `403 bank_data_access_denied`.

1. No [Business Console](https://business.didit.me), abra sua aplicação de sandbox e acesse **API keys**.
2. Crie uma chave com acesso personalizado e adicione **Bank data**: **Read** para as leituras e **Write** para as chamadas que criam, alteram ou excluem algo.
3. Copie a chave e exporte-a:

```bash theme={null}
export DIDIT_API_KEY="your-sandbox-key"
```

Consulte [API keys](https://docs.didit.me/pt-br/console/api-keys.md) para ver a lista completa de recursos.

## Etapa 2: criar um link

Um link é uma execução das telas em que uma pessoa conecta um banco.
Crie um link contínuo para o Test Bank:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/links/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "access": "ongoing",
    "country": "ESP",
    "data": ["accounts", "balances", "transactions"],
    "history_days": 90,
    "vendor_data": "client-7731"
  }'
```

`country` é o código de três letras do país do banco da pessoa e é opcional.
Envie-o quando souber, para que a pessoa veja apenas os bancos desse país; sem ele, ela escolhe entre todos os países que você pode atender.
Para acesso único, envie `"access": "one_time"` (o padrão).

```json theme={null}
{
  "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40",
  "mode": "connect",
  "access": "ongoing",
  "status": "created",
  "url": "https://verify.didit.me/bank/link/...",
  "expires_at": "2026-11-22T13:00:00Z",
  "connection_id": null
}
```

Guarde o `id` do link junto com o seu usuário.
A `url` e o `client_token` são retornados uma única vez, quando o link é criado.

## Etapa 3: abra o link e conecte o Didit Test Bank

Abra a `url` em um navegador ou envie-a para a pessoa por e-mail ou chat.
A pessoa vê a tela de consentimento, escolhe **Didit Test Bank**, faz login com um dos clientes de teste e escolhe as contas que quer compartilhar.
A [página do sandbox](https://docs.didit.me/pt-br/core-technology/bank-verification/sandbox.md) lista os clientes de teste e o que cada um oferece.

Para devolver a pessoa ao seu site depois, veja [Retornar ao seu site](https://docs.didit.me/pt-br/integration/bank-link/return-to-your-site.md).
Sem `redirect_url`, a pessoa termina na página de resultado da Didit, e você fica sabendo do resultado por meio do webhook ou de uma consulta.

## Etapa 4: receber os webhooks e confirmar

Inscreva um destino do webhook nos eventos `bank.*` no console, como faria para qualquer [webhook](https://docs.didit.me/pt-br/integration/webhooks.md).
Quando a pessoa concluir o fluxo, `bank.link.completed` chega com o `link_id` e o `connection_id`. Depois, `bank.connection.created` chega quando a primeira sincronização já tiver armazenado as contas.

Nunca confie em um ID de link que o navegador enviar para você.
Consulte o link por conta própria:

```bash theme={null}
curl https://verification.didit.me/v3/bank/links/$LINK_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{ "id": "0b9c4f1e-6a2d-4e8b-9f31-7c5d2e1a8b40", "status": "completed", "connection_id": "5e1d2a70-3b4c-4d5e-8f60-71829304a5b6" }
```

O `status` é `completed` ou um status final (`cancelled`, `expired`, `failed`). Um link `failed` traz um `error.code`; um link `cancelled` retorna `error: null`.

## Passo 5: ler contas, saldos e transações

```bash theme={null}
curl https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/accounts/ -H "x-api-key: $DIDIT_API_KEY"
curl https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/balances/ -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/accounts/$ACCOUNT_ID/transactions/?date_from=2026-01-01" -H "x-api-key: $DIDIT_API_KEY"
```

Os valores são strings decimais, com sinal negativo para dinheiro que sai.
Uma página de transações traz `next_page_token` enquanto houver mais itens para ler.
Veja [Contas, saldos e transações](https://docs.didit.me/pt-br/core-technology/bank-verification/accounts-balances-transactions.md).

## Etapa 6: acompanhe o feed de alterações

O feed de alterações retorna apenas o que mudou desde a sua última leitura.
Sua primeira leitura, sem cursor, é o snapshot completo: todas as transações da conexão, cada uma como `added`, com `reset: true`.
Uma primeira página pode trazer `has_more: true` com um `next_page_token` e nenhum `next_cursor` ainda.
Continue lendo com `page_token` enquanto `has_more` for `true`, e armazene o `next_cursor` da última página (a que tem `has_more: false`) para a próxima vez:

```bash theme={null}
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/" -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?page_token=$NEXT_PAGE_TOKEN" -H "x-api-key: $DIDIT_API_KEY"
curl "https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/transactions/sync/?cursor=$NEXT_CURSOR" -H "x-api-key: $DIDIT_API_KEY"
```

`reset: true` significa que a resposta é um snapshot completo: substitua sua cópia por ela, em vez de acrescentar dados a ela.
`bank.data.updated` avisa quando uma sincronização armazenou algo novo.

## Etapa 7: sincronizar agora

Uma conexão contínua sincroniza automaticamente.
Para ler o banco agora, solicite uma sincronização:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/refresh/ -H "x-api-key: $DIDIT_API_KEY"
```

Um banco permite um número limitado de leituras automáticas por dia.
`sync.live_syncs_left_today` e `sync.budgets` da conexão informam quantas restam e quando são redefinidas, e uma chamada que ultrapassa o limite responde com `429 refresh_limit_reached` e o horário de redefinição.
Consulte [Atualizar os dados bancários sob demanda](https://docs.didit.me/pt-br/use-cases/refresh-bank-data-on-demand.md).

## Etapa 8: interromper o acesso e excluir

Interromper o acesso e excluir são duas chamadas diferentes.

```bash theme={null}
# Stop access at the bank. The connection keeps its data until you delete it.
curl -X POST https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/revoke/ -H "x-api-key: $DIDIT_API_KEY"

# Delete the connection and its data. Irreversible.
curl -X DELETE https://verification.didit.me/v3/bank/connections/$CONNECTION_ID/ -H "x-api-key: $DIDIT_API_KEY"
```

Uma conexão excluída responde apenas com os campos `id`, `status`, `status_reason`, `created_at` e `erasure`.
Consulte [Dados, consentimento e exclusão](https://docs.didit.me/pt-br/core-technology/bank-verification/data-consent-and-deletion.md).

## Próximos passos

* [Conexões](https://docs.didit.me/pt-br/core-technology/bank-verification/connections.md): acesso único e contínuo, consentimento e renovação.
* [Webhooks bancários](https://docs.didit.me/pt-br/core-technology/bank-verification/webhooks.md)
* [Preços](https://docs.didit.me/pt-br/getting-started/bank-verification-pricing.md)
* [Referência da API](https://docs.didit.me/pt-br/standalone-apis/bank-data.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.