Aparência
Coleção Bruno: receptora e iniciadora do Open Finance
A coleção do Bruno chama as APIs de aplicação do Finnest Power na ordem em que o backend do participante as usa: pede o token da aplicação, abre o consentimento, espera o cliente final autorizar e segue com a coleta de dados ou com o Pix. O mesmo arquivo roda no aplicativo do Bruno, para explorar a API, e na linha de comando, para testar a integração num pipeline.
O fluxo de acesso, os escopos e os endereços estão em Acesso por aplicação. A coleção é a forma executável desse guia.
Onde obter
A coleção acompanha cada versão da plataforma, na pasta services/banking/bruno do Finnest Power. Quem opera a instalação a entrega ao time do backend. O contrato da receptora está na referência interativa, como APIs de aplicação (receptora OFB).
Versões
A coleção usa o formato OpenCollection (YAML), o padrão do Bruno desde a versão 3.1. Abra-a no aplicativo do Bruno 4 ou rode-a com a CLI @usebruno/cli 4.2.1, a versão que a plataforma testa contra o serviço bancário a cada mudança. Fixe essa versão no pipeline (@usebruno/cli@4.2.1), em vez de latest, para que uma versão nova da CLI não mude o resultado sem aviso.
Os scripts da coleção rodam no modo seguro da CLI (--sandbox safe, o padrão): não é preciso liberar o modo developer.
Conteúdo
| Pasta | Requisições |
|---|---|
receptora/consentimento | Criar consentimento, consultar consentimento, listar consentimentos |
receptora/dados | Coletar dados da conexão, listar e consultar dados coletados, ler transações |
iniciadora/pagamento-pix | Criar consentimento de pagamento, consultar consentimento, iniciar e consultar Pix |
environments/local.yml | O serviço bancário e o Keycloak locais |
environments/sandbox.yml | Uma instalação em api.<domínio>, com o token em matls-auth.<domínio> |
lib/finnest-auth.js | O pedido do token da aplicação, guardado por escopo até perto de expirar |
Cada requisição tem duas tags: a área (receptora ou iniciadora) e o tipo, consulta para as que só leem e comando para as que criam ou mudam algo. Cada requisição da receptora também traz um exemplo de resposta (aba Examples no aplicativo), tirado do serviço bancário e conferido contra ele a cada mudança.
Cada requisição guarda o que a seguinte precisa: criar o consentimento guarda connectionId e redirectUrl; coletar os dados guarda o accountId da primeira conta; listar os dados guarda aggregationId; criar o consentimento de pagamento guarda paymentConsentId; iniciar o Pix guarda paymentId. Cada requisição também confere a resposta, com o status e os campos que o fluxo depende.
Credenciais
Copie .env.example para .env na raiz da coleção. O .env fica fora do Git, e o Bruno o lê como process.env.
| Variável | Quando |
|---|---|
FINNEST_CLIENT_SECRET | tokenAuthMethod é client_secret_post, o padrão da aplicação embutida |
FINNEST_PRIVATE_KEY_PEM | tokenAuthMethod é private_key_jwt: a chave privada PEM da aplicação |
FINNEST_KEY_ID | private_key_jwt: o kid da chave no JWKS da aplicação |
FINNEST_MTLS_CERT_PATH | O certificado de transporte, apresentado só a matls-auth.<domain> do ambiente |
FINNEST_MTLS_KEY_PATH | A chave desse certificado |
Com private_key_jwt, a coleção assina a asserção do cliente com PS256, com iss e sub iguais ao clientId, aud igual ao endpoint de token, um jti novo e validade de 60 segundos. O cliente da aplicação no Keycloak precisa estar configurado para esse método, com a chave pública registrada.
Rodar no aplicativo
- Abra a pasta da coleção no Bruno (Open Collection).
- Escolha o ambiente
localousandbox. Nosandbox, troquedomainpelo domínio da instalação e preenchaauthorisationServerIdcom o servidor de autorização da transmissora no Diretório. - Rode
receptora/consentimento/Criar consentimento, abra oredirectUrlda resposta no navegador e autorize na transmissora. - Rode as demais requisições de
receptoraem ordem. O fluxo do Pix eminiciadoraé igual.
Rodar na linha de comando
Na pasta da coleção, o primeiro passo abre o consentimento. Depois que o cliente final autoriza, o segundo passo usa a conexão criada:
bash
npx @usebruno/cli@4.2.1 run receptora/consentimento/criar-consentimento.yml --env sandbox \
--env-var authorisationServerId=<id do servidor no Diretório>
npx @usebruno/cli@4.2.1 run receptora/consentimento/consultar-consentimento.yml receptora/dados \
--env sandbox --env-var connectionId=<connectionId da primeira execução> \
--reporter-junit ../resultado-bruno.xmlA CLI lê as credenciais do .env da coleção ou do ambiente do processo, que é o caminho para a chave PEM do private_key_jwt num pipeline: --env-var aceita só valores de uma linha.
As tags escolhem o que roda. Para conferir uma conexão sem criar nada, rode só as consultas (-r entra nas subpastas de receptora):
bash
npx @usebruno/cli@4.2.1 run receptora -r --env sandbox --tags consulta \
--env-var connectionId=<connectionId>--exclude-tags comando tem o mesmo efeito, e --bail para na primeira falha em vez de seguir com as requisições que dependem dela.
Rodar no pipeline
A CLI termina com código diferente de zero quando uma requisição ou conferência falha, e --reporter-junit, --reporter-html ou --reporter-json grava o resultado. O relatório traz por padrão os cabeçalhos e os corpos de cada requisição: o token da aplicação e dados pessoais do cliente final, como o CPF. Para guardá-lo como artefato do pipeline, grave-o sem eles e fora da pasta da coleção:
bash
npx @usebruno/cli@4.2.1 run receptora/consentimento/consultar-consentimento.yml receptora/dados \
--env sandbox --env-var connectionId="$CONNECTION_ID" --bail \
--reporter-junit ../resultados/bruno.xml --reporter-skip-all-headers --reporter-skip-bodyNo GitHub Actions, as credenciais vêm dos segredos do repositório. O certificado de transporte e a chave dele vão para arquivos temporários do runner, porque a coleção os lê por caminho. O relatório sobe como artefato mesmo quando o passo falha:
yaml
- name: Coleção Bruno
working-directory: finnest-bruno
env:
FINNEST_CLIENT_SECRET: ${{ secrets.FINNEST_CLIENT_SECRET }}
FINNEST_MTLS_CERT: ${{ secrets.FINNEST_MTLS_CERT }}
FINNEST_MTLS_KEY: ${{ secrets.FINNEST_MTLS_KEY }}
CONNECTION_ID: ${{ vars.FINNEST_CONNECTION_ID }}
run: |
export FINNEST_MTLS_CERT_PATH="$RUNNER_TEMP/mtls.crt" FINNEST_MTLS_KEY_PATH="$RUNNER_TEMP/mtls.key"
printf '%s' "$FINNEST_MTLS_CERT" > "$FINNEST_MTLS_CERT_PATH"
(umask 077 && printf '%s' "$FINNEST_MTLS_KEY" > "$FINNEST_MTLS_KEY_PATH")
mkdir -p ../resultados
npx @usebruno/cli@4.2.1 run receptora -r --env sandbox --tags consulta \
--env-var connectionId="$CONNECTION_ID" --bail \
--reporter-junit ../resultados/bruno.xml --reporter-skip-all-headers --reporter-skip-body
- name: Relatório da coleção
if: ${{ !cancelled() }}
uses: actions/upload-artifact@v7
with:
name: bruno
path: resultados/bruno.xml
if-no-files-found: errorComo a coleção é verificada
A cada mudança no serviço bancário:
- cada requisição da coleção é conferida contra o documento OpenAPI do serviço: a rota existe, o token pedido tem os escopos que a operação exige e os cabeçalhos obrigatórios são enviados;
- cada variável que uma requisição lê vem do ambiente ou de uma requisição anterior;
- cada requisição tem as tags da sua área e do seu tipo, e cada exemplo de resposta usa um status que a operação documenta;
- a CLI do Bruno roda a receptora inteira contra o serviço bancário com Postgres de verdade, do token à coleta dos dados, e cada resposta tem os campos e os tipos do exemplo da requisição; a CLI pede o token também com
private_key_jwte leva as requisições da iniciadora até a consulta da detentora; - o pedido de token é testado por propriedades: o segredo vai só com
client_secret_post, e a asserção deprivate_key_jwtverifica com a chave pública para qualquer cliente e endpoint.