Saltar para o conteúdo principal
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. 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.
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.
  • 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 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.
  • 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.

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.
Última modificação em 22 de novembro de 2026