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.
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_qualityindica a força dessa garantia.bank_referenceeroute_idsão estáveis.derivedsignifica que o movimento foi associado pelo seu conteúdo, pelo que uma correção do banco pode aparecer como umremovede umadded.statusébookedoupending. Uma transação pendente tem um id próprio. Quando o banco a lança, a transação lançada chega comoaddede a pendente comoremovedcomreason: pending_booked.pending_idsó é preenchido quando o banco as associa.amounttem sinal: negativo significa dinheiro que sai.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 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, comreverses_idquando o banco a associa.
Campos que o banco não envia são null
Todos os campos que o banco não envia sãonull.
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 compage_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
addedcomreset: true. Substitua a sua cópia por estas, em vez de as acrescentar. - Continue a paginar com
page_tokenenquantohas_morefor verdadeiro. Guardenext_cursorapenas depois de uma resposta comhas_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_expiredebootstrap: true: comece de novo a partir de um cursor vazio e substitua a sua cópia. removed[].reasonépending_booked,pending_expired,bank_removedouaccess_removed.
Cabeçalhos
Ambas as leituras de transações devolvem os cabeçalhosX-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.