Skip to content

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_id e o client_secret da aplicação embutida finnest-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 authorisationServerId da 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 finnest com 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/aggregations lista todas as agregações da aplicação, sem filtro por kind nem por conexão; filtre do seu lado, ou leia uma agregação pelo id.
  • 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: kind account-balances com o accountId, e a permissão ACCOUNTS_BALANCES_READ.
  • Cartão de crédito: as permissões CREDIT_CARDS_ACCOUNTS_* e os kind credit-card-*, com o escopo ofb:receiver:credit-cards.

Finnest Power — plataforma Open Finance Brasil e Open Insurance Brasil. Contato: oi@finnest.com.br