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.
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.
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.
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_qualityindica a força dessa garantia.bank_referenceeroute_idsão estáveis.derivedsignifica que a movimentação foi correlacionada pelo seu conteúdo, então uma correção do banco pode aparecer como umremovede umadded.statusébookedoupending. Uma transação pendente tem id próprio. Quando o banco a lança como efetivada, a transação lançada chega comoadded, e a pendente comoremovedcomreason: pending_booked.pending_idsó é preenchido quando o banco as vincula.amounttem sinal: negativo significa saída de dinheiro.directionrepete o sinal.bank_referenceé a referência imutável do lançamento no banco,nullquando 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, comreverses_idquando 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 para testar seu código com um banco que envia poucos dados.
Paginação de um intervalo de datas
Continue lendo compage_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.
- Um cursor vazio retorna todas as transações atuais como
addedcomreset: true. Substitua sua cópia por elas, em vez de acrescentá-las. - Continue paginando com
page_tokenenquantohas_morefor true. Armazenenext_cursorsomente após uma resposta comhas_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_expiredcombootstrap: true: comece novamente a partir de um cursor vazio e substitua sua cópia. removed[].reasonépending_booked,pending_expired,bank_removedouaccess_removed.
Cabeçalhos
Ambas as leituras de transações retornam os cabeçalhosX-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.