> ## 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.

# Contas bancárias, saldos e transações: modelo de dados

> Modelo de dados bancários da Didit: contas com IDs estáveis, saldos tipados, transações lançadas e pendentes e feed de alterações com cursor durável.

A API de dados bancários da Didit armazena as contas, os saldos e as transações de cada conexão e os disponibiliza por meio de endpoints de leitura com paginação (`cursor` nas listas, `page_token` nas leituras de transações). Os valores são strings decimais com um campo `currency` separado no padrão ISO 4217, as datas seguem o padrão ISO 8601 e os países usam o formato ISO alpha-3. As leituras nunca são cobradas.

## Contas

`GET /v3/bank/connections/{id}/accounts/` lista as contas de uma conexão, e `GET /v3/bank/accounts/{account_id}/` retorna uma delas.

| Campo | Significado |
| - | - |
| `id` | Pertence à conexão e não muda enquanto ela existir, inclusive nas renovações. |
| `account_ref` | Identifica a mesma conta bancária em conexões de uma mesma aplicação e ambiente. É um hash com chave dos identificadores do próprio banco, e fica `null` quando o banco não fornece um identificador confiável. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` ou `other`, e `personal`, `business` ou `unknown`. |
| `identifiers` | O IBAN, o BIC e outros identificadores. Chamadas feitas do lado do servidor com a permissão de dados bancários recebem os valores completos. |
| `holders[]` | Cada titular com um `name` e um `role`: `holder`, `joint_holder`, `representative` ou `unknown`. |
| `sync.last_synced_at` | Quando a Didit buscou os dados no banco pela última vez, e não quando você os leu pela última vez. |
| `history_coverage` | O que o banco entregou do histórico solicitado: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` e um `status` que pode ser `complete`, `partial`, `empty`, `unavailable` ou `unknown`. |

Use `account_ref` para reconhecer uma conta bancária quando uma pessoa a conectar novamente, e `id` para tudo o que estiver dentro de uma mesma conexão.

## Saldos

`GET /v3/bank/accounts/{account_id}/balances/` retorna os saldos classificados por tipo, com suas datas de referência.

```json theme={null}
{
  "account_id": "a71f0c2e-...",
  "balances": [
    { "type": "booked", "amount": "18250.34", "currency": "EUR", "reference_date": "2026-11-20" },
    { "type": "available", "amount": "17990.34", "currency": "EUR", "reference_date": "2026-11-21" }
  ],
  "last_synced_at": "2026-11-21T12:04:40Z"
}
```

`type` é `booked`, `available` ou `expected`, e `iso_type` traz o código ISO 20022 do banco quando o banco informa um.

## Transações

`GET /v3/bank/accounts/{account_id}/transactions/` lê um intervalo de datas.
Ele recebe `date_from` e `date_to` (datas de calendário conforme o banco as informa, inclusivas), `status` (`booked` ou `pending`, ambos por padrão), `limit` (até 500) e `page_token`.
Ele ordena por `effective_date` em ordem decrescente e, em seguida, por `id`.

```json theme={null}
{
  "id": "8f2b...",
  "status": "booked",
  "booking_date": "2026-11-19",
  "value_date": "2026-11-20",
  "amount": "-1210.00",
  "currency": "EUR",
  "direction": "debit",
  "description": "RECIBO SEGURIDAD SOCIAL",
  "counterparty": { "name": "TESORERIA GENERAL SEG SOCIAL", "iban": "ES7620770024003102575766" },
  "remittance": { "unstructured": ["RECIBO SEGURIDAD SOCIAL 10/2026"], "reference": "0028123456789" },
  "bank_transaction_code": "PMNT-RDDT-ESDD",
  "bank_reference": "2026111900012345",
  "identity_quality": "bank_reference",
  "balance_after": "18250.34",
  "category": "taxes_and_social_security"
}
```

* **`id`** é atribuído pela Didit no primeiro contato com a transação e armazenado. A mesma movimentação mantém o seu id entre leituras, sincronizações e renovações.
* **`identity_quality`** indica a força dessa garantia. `bank_reference` e `route_id` são estáveis. `derived` significa que a movimentação foi correlacionada pelo seu conteúdo, então uma correção do banco pode aparecer como um `removed` e um `added`.
* **`status`** é `booked` ou `pending`. Uma transação pendente tem id próprio. Quando o banco a lança como efetivada, a transação lançada chega como `added`, e a pendente como `removed` com `reason: pending_booked`. `pending_id` só é preenchido quando o banco as vincula.
* **`amount`** tem sinal: negativo significa saída de dinheiro. `direction` repete o sinal.
* **`bank_reference`** é a referência imutável do lançamento no banco, `null` quando o banco não a fornece. A Didit nunca a cria.
* **`category`** é a categorização própria da Didit, quando aplicável.
* Uma correção feita pelo banco em uma transação lançada é `modified`. Um estorno é uma nova transação, com `reverses_id` quando o banco o vincula.

### Campos que o banco não envia são null

Todo campo que o banco não envia é `null`.
A instituição lista os campos que se sabe que ela envia em `transaction_fields`, junto com `pending_transactions`, `pending_linkage`, `balance_types` e `history_days_max`, para que ninguém descubra lacunas em produção.
Use o cliente de teste `sparse_fields` no [sandbox](https://docs.didit.me/pt-br/core-technology/bank-verification/sandbox.md) para testar seu código com um banco que envia poucos dados.

### Paginação de um intervalo de datas

Continue lendo com `page_token` enquanto `has_more` for verdadeiro.
O token fixa o instantâneo da leitura por uma hora: adições feitas após a primeira página não estão incluídas, cada linha é retornada em seu estado atual, e uma linha removida durante a paginação deixa de aparecer nas páginas seguintes e aparece no feed de alterações.
Um token expirado retorna `410 page_expired`: reinicie a leitura a partir da consulta original.

## O feed de alterações

`GET /v3/bank/connections/{id}/transactions/sync/` retorna o que mudou em todas as contas de uma conexão desde um `cursor`.

```json theme={null}
{
  "added": [ { "id": "...", "status": "booked", "amount": "-35.00" } ],
  "modified": [],
  "removed": [ { "id": "...", "reason": "pending_booked" } ],
  "has_more": false,
  "next_cursor": "...",
  "reset": false
}
```

* Um cursor vazio retorna todas as transações atuais como `added` com `reset: true`. Substitua sua cópia por elas, em vez de acrescentá-las.
* Continue paginando com `page_token` enquanto `has_more` for true. Armazene `next_cursor` somente após uma resposta com `has_more: false`. Se a paginação falhar no meio do caminho, reinicie a partir do cursor que você armazenou.
* Um cursor é opaco e está vinculado à conexão e ao ambiente. O log de alterações pode ser reproduzido por 90 dias. Uma requisição com um cursor mais antigo retorna a resposta `410 cursor_expired` com `bootstrap: true`: comece novamente a partir de um cursor vazio e substitua sua cópia.
* `removed[].reason` é `pending_booked`, `pending_expired`, `bank_removed` ou `access_removed`.

O passo a passo está em [Feed bancário contínuo para contabilidade](https://docs.didit.me/pt-br/use-cases/bank-data-for-accounting.md).

## Cabeçalhos

Ambas as leituras de transações retornam os cabeçalhos `X-RateLimit-*` (600 leituras e 300 gravações por minuto por aplicação, com 429 e `Retry-After` quando esse limite é excedido) e `X-Bank-Last-Synced-At`.
Os limites da API e os limites próprios do banco para buscar dados são coisas separadas: veja [Atualizar dados do banco sob demanda](https://docs.didit.me/pt-br/use-cases/refresh-bank-data-on-demand.md).


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