​
Conexão e consentimento

No backend, troque clientId/clientSecret por apiKey em POST /auth e crie um POST /connect_token para o widget. Opções como clientUserId e webhookUrl ficam dentro de options, não na raiz. Guarde o itemId recebido: não existe listagem pública GET /items. Acompanhe GET /items/{id} e os eventos de Item. A resposta inicial pode preceder a coleta; aguarde a conclusão e examine executionStatus e statusDetail, inclusive em PARTIAL_SUCCESS. GET /consents?itemId=... mostra os metadados disponíveis, não tokens bancários. No sandbox local a lista pode ser vazia: isso não representa autorização real na instituição.

​
Contas e saldo

GET /accounts exige itemId; o saldo é o último snapshot persistido e a leitura não força uma consulta ao banco. Confira balanceAvailable, balanceUpdatedAt/updateDateTime e a moeda. balance: null no endpoint de saldo significa indisponibilidade, não zero. GET /accounts/{id}/statements ainda responde página vazia; use transações para movimentos.

​
Transações

Itere até next ser null, seguindo paginação e o guia incremental. Reaplique os filtros de data/ingestão a cada página: next contém somente accountId e after. Não misture dateFrom e createdAtFrom.

​
Autorização encerrada

Para reconectar, use o mesmo ID e encaminhe o usuário para a nova connector.oauthUrl:
Este PATCH requer uma jornada de autorização na instituição; o teste sintético local não simula uma autorização bancária real. Detalhes em consentimentos.

​
Webhooks e desconexão

Registre uma assinatura application-level para o evento ou all. Uma webhookUrl por Item precisa dessa assinatura habilitada. Leia o recurso REST quando o evento chegar, verifique a assinatura e deduplique por eventId. No CRUD, envie enabled: false para suspender e enabled: true para reativar entregas. A resposta usa disabledAt; headers customizados não aparecem nas respostas públicas. DELETE /webhooks/{id} e DELETE /items/{id} bem-sucedidos retornam 204, sem JSON. Só considere o Item desconectado após o sucesso da exclusão; falhas retornadas pelo servidor não confirmam remoção. Não exclua o Item apenas para recuperar uma autorização expirada.

​
Reprodução local dos exemplos

O repositório malvo-docs inclui scripts/run-local-examples.py e scripts/local-api-fixture.go. O runner usa a API Go real em loopback com PostgreSQL exclusivo e geração sintética sandbox, sem clientes institucionais, Stripe ou workers de entrega. Ele valida respostas HTTP contra os schemas desta referência e encerra o processo ao terminar. Veja instruções no README.