> ## 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: ligar um banco de teste e ler transações

> Da aplicação de sandbox às contas, saldos e transações do Didit Test Bank: crie uma chave e uma ligação, ligue, leia, sincronize e elimine.

Os dados bancários estão disponíveis para aplicações de sandbox.
As chamadas de uma aplicação em produção respondem com `404` até o acesso em produção ser anunciado, e em sandbox nada é cobrado.
Este guia de início rápido leva-o de uma aplicação de sandbox às contas, saldos e transações do Didit Test Bank, com pedidos prontos a copiar e colar.

> [!NOTE]
>
> Cada resposta abaixo está reduzida aos campos que importam.
> Mantenha a chave de API no seu servidor: ela nunca chega a um navegador ou a uma aplicação.

## Passo 1: crie uma chave de API com a permissão Dados bancários

Os dados bancários não fazem parte do acesso total.
Uma chave com acesso total, incluindo o segredo principal da aplicação, é recusada em todas as chamadas de dados bancários com `403 bank_data_access_denied`.

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

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

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

## Passo 2: criar uma ligação

Uma ligação corresponde a uma execução dos ecrãs em que uma pessoa liga o seu banco.
Crie uma ligação contínua 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 o souber, para que a pessoa veja apenas os bancos desse país; sem ele, pode escolher entre todos os países para os quais presta serviço.
Para acesso único, envie `"access": "one_time"` (o valor predefinido).

```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` da ligação associado ao seu utilizador.
O `url` e o `client_token` são devolvidos uma única vez, quando a ligação é criada.

## Passo 3: abra a ligação e estabeleça ligação ao Didit Test Bank

Abra o `url` num navegador, ou envie-o à pessoa por e-mail ou chat.
A pessoa vê o ecrã de consentimento, escolhe **Didit Test Bank**, inicia sessão com um dos clientes de teste e escolhe as contas a partilhar.
A [página de sandbox](https://docs.didit.me/pt/core-technology/bank-verification/sandbox.md) lista os clientes de teste e o que cada um lhe proporciona.

Para devolver a pessoa ao seu site depois, veja [Voltar ao seu site](https://docs.didit.me/pt/integration/bank-link/return-to-your-site.md).
Sem um `redirect_url`, a pessoa termina na página de resultados da Didit e você fica a saber o resultado através do webhook ou de uma leitura.

## Passo 4: receber os webhooks e confirmar

Associe um destino aos eventos `bank.*` na consola, tal como para qualquer [webhook](https://docs.didit.me/pt/integration/webhooks.md).
Quando a pessoa concluir o processo, chega `bank.link.completed` com o `link_id` e o `connection_id`; depois, chega `bank.connection.created` quando a primeira sincronização tiver guardado as contas.

Nunca confie num id de ligação que um navegador lhe envie.
Leia a ligação diretamente:

```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 estado final (`cancelled`, `expired`, `failed`). Uma ligação `failed` traz um `error.code`; uma ligação `cancelled` tem `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 montantes são strings decimais, negativos para saídas de dinheiro.
Uma página de transações inclui `next_page_token` enquanto houver mais para ler.
Consulte [Contas, saldos e transações](https://docs.didit.me/pt/core-technology/bank-verification/accounts-balances-transactions.md).

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

O feed de alterações devolve apenas o que foi alterado desde a sua última leitura.
A sua primeira leitura, sem cursor, é o instantâneo completo: todas as transações da ligação, cada uma como `added`, com `reset: true`.
Uma primeira página pode trazer `has_more: true` com um `next_page_token` e ainda sem `next_cursor`.
Continue a ler com `page_token` enquanto `has_more` for `true`, e guarde 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 instantâneo completo: substitua a sua cópia por ela, em vez de a adicionar à sua cópia.
`bank.data.updated` indica-lhe quando uma sincronização guardou algo novo.

## Passo 7: sincronizar agora

Uma ligação contínua sincroniza-se automaticamente.
Para ler o banco agora, peça 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 sem intervenção por dia.
`sync.live_syncs_left_today` e `sync.budgets` na ligação indicam quantas restam e quando são repostos, e uma chamada que ultrapasse o limite responde com `429 refresh_limit_reached` e indica a hora de reposição.
Consulte [Atualizar os dados bancários a pedido](https://docs.didit.me/pt/use-cases/refresh-bank-data-on-demand.md).

## Passo 8: interromper o acesso e eliminar

Interromper o acesso e eliminar 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 ligação eliminada devolve apenas os campos `id`, `status`, `status_reason`, `created_at` e `erasure`.
Consulte [Dados, consentimento e eliminação](https://docs.didit.me/pt/core-technology/bank-verification/data-consent-and-deletion.md).

## Próximos passos

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


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