> ## 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 Bank da Didit: contas com IDs estáveis, saldos tipados, transações lançadas e pendentes, e um 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 ligação e disponibiliza-os através de endpoints de leitura com paginação (`cursor` nas listas, `page_token` nas leituras de transações).
Os montantes são cadeias de caracteres decimais com um campo `currency` separado, em conformidade com a norma ISO 4217, as datas seguem a norma ISO 8601 e os países são representados por códigos alfa-3 da ISO.
As leituras nunca são faturadas.

## Contas

`GET /v3/bank/connections/{id}/accounts/` lista as contas de uma ligação, e `GET /v3/bank/accounts/{account_id}/` devolve uma.

| Campo | Significado |
| - | - |
| `id` | Pertence à ligação e não muda enquanto esta existir, incluindo as renovações. |
| `account_ref` | Identifica a mesma conta bancária em várias ligações de uma aplicação e de um ambiente. É um hash com chave dos identificadores do próprio banco, e é `null` quando o banco não fornece nenhum identificador fiável. |
| `type`, `usage` | `current`, `savings`, `card`, `loan`, `investment` ou `other`, e `personal`, `business` ou `unknown`. |
| `identifiers` | O IBAN, o BIC e outros identificadores. Os chamadores do lado do servidor com a permissão de dados bancários recebem-nos na íntegra. |
| `holders[]` | Cada titular com um `name` e um `role`: `holder`, `joint_holder`, `representative` ou `unknown`. |
| `sync.last_synced_at` | Quando a Didit obteve pela última vez os dados do banco, e não quando os leu pela última vez. |
| `history_coverage` | O que o banco entregou do histórico que pediu: `requested_from`, `oldest_booking_date`, `covered_ranges`, `missing_ranges` e um `status` de `complete`, `partial`, `empty`, `unavailable` ou `unknown`. |

Use `account_ref` para reconhecer uma conta bancária quando uma pessoa volta a ligá-la, e `id` para tudo o que estiver dentro de uma mesma ligação.

## Saldos

`GET /v3/bank/accounts/{account_id}/balances/` devolve os saldos por tipo, com as respetivas 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"
}
```

O campo `type` é `booked`, `available` ou `expected`, e `iso_type` contém o código ISO 20022 do banco, quando este o fornece.

## Transações

`GET /v3/bank/accounts/{account_id}/transactions/` lê um intervalo de datas.
Aceita `date_from` e `date_to` (datas de calendário tal como o banco as reporta, inclusive), `status` (`booked` ou `pending`, ambos por predefinição), `limit` (até 500) e `page_token`.
Ordena por `effective_date` de forma decrescente e, depois, 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 na primeira leitura. O mesmo movimento 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 o movimento foi associado pelo seu conteúdo, pelo que uma correção do banco pode aparecer como um `removed` e um `added`.
* **`status`** é `booked` ou `pending`. Uma transação pendente tem um id próprio. Quando o banco a lança, 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 associa.
* **`amount`** tem sinal: negativo significa dinheiro que sai. `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 inventa.
* **`category`** é a categorização própria da Didit, quando aplicável.
* Uma correção do banco a uma transação lançada é `modified`. Uma reversão é uma nova transação, com `reverses_id` quando o banco a associa.

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

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

### Paginar um intervalo de datas

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

## O fluxo de alterações

`GET /v3/bank/connections/{id}/transactions/sync/` devolve o que mudou em todas as contas de uma ligaçã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 devolve todas as transações atuais como `added` com `reset: true`. Substitua a sua cópia por estas, em vez de as acrescentar.
* Continue a paginar com `page_token` enquanto `has_more` for verdadeiro. Guarde `next_cursor` apenas depois de uma resposta com `has_more: false`. Se a paginação falhar a meio, reinicie a partir do cursor que guardou.
* Um cursor é opaco e está associado à ligação e ao ambiente. O registo de alterações pode ser reproduzido durante 90 dias. Um cursor mais antigo responde com `410 cursor_expired` e `bootstrap: true`: comece de novo a partir de um cursor vazio e substitua a sua cópia.
* `removed[].reason` é `pending_booked`, `pending_expired`, `bank_removed` ou `access_removed`.

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

## Cabeçalhos

Ambas as leituras de transações devolvem os cabeçalhos `X-RateLimit-*` (600 leituras e 300 escritas 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 a obtenção de dados são coisas distintas: veja [Atualizar dados bancários sob pedido](https://docs.didit.me/pt/use-cases/refresh-bank-data-on-demand.md).


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