Aparência
Primeiros passos: da credencial à primeira leitura de transações
Este guia leva o backend do participante da credencial da aplicação à primeira leitura das transações de uma conta no Open Finance Brasil, como receptora, numa instalação de sandbox. Cada passo traz o comando curl, a requisição equivalente da coleção Bruno e o que a resposta mostra quando deu certo. O caminho completo cabe em 30 minutos.
Os detalhes de escopos, endereços e modos de instalação estão em Acesso por aplicação. As respostas de erro estão em Erros das APIs de aplicação.
Para instalar a plataforma só com o Open Finance, do Diretório ao deploy, veja o Guia OFB da participante.
Antes de começar
Os endereços reais da sua instalação e o ID do cliente estão no Admin dela, em Developer › Primeiros passos da API.
Quem opera a instalação entrega ao time do backend:
- [ ] o domínio da instalação (
<domínio>nos exemplos); - [ ] o
client_ide oclient_secretda aplicação embutidafinnest-power-ofb-application; - [ ] o certificado de transporte de sandbox e a chave dele, quando o endpoint de token fica em
matls-auth.<domínio>(o Admin mostra o endereço); - [ ] o
authorisationServerIdda transmissora de sandbox no Diretório; - [ ] o usuário de teste da transmissora, com que o cliente final autoriza o compartilhamento;
- [ ] a release da CLI
finnestcom que a instalação foi feita.
A release de referência é a da CLI finnest que instalou a plataforma. Cada release da CLI fixa a tag da imagem de cada serviço, e o info.version de /banking/openapi.json da instalação é a tag do serviço bancário que essa CLI fixou: o check runtime-image de finnest doctor a mostra como banking=…:<tag>. O contrato desta receptora está na referência interativa, como APIs de aplicação (receptora OFB), com a versão do serviço bancário no info.version; se ela for diferente da tag da sua instalação, confira as operações no /banking/openapi.json dela.
Use só dados sintéticos: o CPF de teste da transmissora ou o CPF fictício 52998224725. Nunca um documento real.
1. Obter o token da aplicação
Com a superfície regulada ligada, o backend apresenta o certificado de transporte só nesta chamada. É o certificado de transporte de sandbox do próprio participante, emitido para a organização dele no Diretório. Se o Admin mostrar o endpoint de token em auth.<domínio>, use esse host e tire --cert e --key.
bash
TOKEN=$(curl -sS https://matls-auth.<domínio>/realms/finnest-ofb/protocol/openid-connect/token \
--cert transporte.crt --key transporte.key \
-d grant_type=client_credentials \
-d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" | jq -r .access_token)Na coleção, toda requisição de receptora pede o token sozinha (lib/finnest-auth.js).
Deu certo quando a resposta traz access_token e expires_in. Um 401 aqui é credencial errada; um erro de TLS é o certificado de transporte que falta ou não é aceito.
2. Abrir o consentimento
Peça as permissões de contas e de transações, além de RESOURCES_READ:
bash
curl -sS https://api.<domínio>/banking-receiver/consents/v1/consents \
-H "Authorization: Bearer $TOKEN" \
-H "x-fapi-interaction-id: $(uuidgen)" \
-H "x-idempotency-key: $(uuidgen)" \
-H 'content-type: application/json' \
-d '{
"data": {
"authorisationServerId": "<authorisationServerId>",
"redirectUri": "https://api.<domínio>/banking-receiver/consents/v1/callback/fragment",
"loggedUser": { "document": { "identification": "52998224725", "rel": "CPF" } },
"permissions": ["RESOURCES_READ", "ACCOUNTS_READ", "ACCOUNTS_TRANSACTIONS_READ"]
}
}'Na coleção: receptora/consentimento/Criar consentimento.
Deu certo quando a resposta é 201, com data.connection.status igual a awaiting_authorisation. Guarde data.connection.id (o connectionId) e data.redirectUrl.
3. Autorizar na transmissora
Abra o redirectUrl no navegador e entre com o usuário de teste da transmissora. Ela devolve o navegador ao callback da plataforma, que ativa a conexão.
Deu certo quando o navegador volta para api.<domínio> sem página de erro da transmissora.
4. Confirmar a conexão ativa
bash
curl -sS https://api.<domínio>/banking-receiver/consents/v1/consents/<connectionId> \
-H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"Na coleção: receptora/consentimento/Consultar consentimento.
Deu certo quando data.status é active. O token que a plataforma recebeu da transmissora é renovado com o refresh token quando vence. Se a transmissora recusar a renovação, a conexão passa a error e é preciso abrir um consentimento novo.
5. Coletar as contas
bash
curl -sS -X POST \
https://api.<domínio>/banking-receiver/v1/connections/<connectionId>/sync \
-H "Authorization: Bearer $TOKEN" -H "x-fapi-interaction-id: $(uuidgen)"Na coleção: receptora/dados/Coletar dados da conexão, que guarda o accountId da primeira conta.
Deu certo quando a resposta é 201 e traz uma agregação com kind igual a accounts e status igual a completed. O payload dela é a resposta da transmissora: o accountId de cada conta está em payload.data[].accountId.
6. Ler as transações
bash
curl -sS https://api.<domínio>/banking-receiver/v1/aggregations \
-H "Authorization: Bearer $TOKEN" \
-H "x-fapi-interaction-id: $(uuidgen)" \
-H 'content-type: application/json' \
-d '{
"data": {
"connectionId": "<connectionId>",
"kind": "account-transactions",
"accountId": "<accountId>",
"period": { "from": "2026-10-01", "to": "2026-10-22" }
}
}'Sem period, a transmissora devolve as transações do dia. Na coleção: receptora/dados/Ler transações da conta.
Deu certo quando a resposta é 201, com data.kind igual a account-transactions e data.status igual a completed. As transações estão em data.payload.data.
Limites conhecidos
GET /banking-receiver/v1/aggregationslista todas as agregações da aplicação, sem filtro porkindnem por conexão; filtre do seu lado, ou leia uma agregação peloid.- Cada aplicação só enxerga as conexões e os dados que ela mesma abriu. Uma conexão de outra aplicação responde
404.
Se algo falhar
Toda resposta de erro traz o envelope errors[], com code, title e detail, e meta. O catálogo de erros diz o que fazer em cada caso. Ao pedir suporte, envie o x-fapi-interaction-id da chamada, nunca o token nem o corpo com dados do cliente final.
Postman e outras ferramentas
A coleção Bruno é a forma testada deste guia. Para o Postman ou o Insomnia, importe o contrato da receptora, /api/specs/banking-receiver/openapi.json: as operações de /banking-receiver vêm com o esquema oauth2 de client_credentials e os escopos de cada uma. Troque seu-dominio.com.br pelo domínio da instalação.
Próximos passos
- Saldos:
kindaccount-balancescom oaccountId, e a permissãoACCOUNTS_BALANCES_READ. - Cartão de crédito: as permissões
CREDIT_CARDS_ACCOUNTS_*e oskindcredit-card-*, com o escopoofb:receiver:credit-cards.