Skip to content

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 ​

PastaRequisições
receptora/consentimentoCriar consentimento, consultar consentimento, listar consentimentos
receptora/dadosColetar dados da conexão, listar e consultar dados coletados, ler transações
iniciadora/pagamento-pixCriar consentimento de pagamento, consultar consentimento, iniciar e consultar Pix
environments/local.ymlO serviço bancário e o Keycloak locais
environments/sandbox.ymlUma instalação em api.<domínio>, com o token em matls-auth.<domínio>
lib/finnest-auth.jsO 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ávelQuando
FINNEST_CLIENT_SECRETtokenAuthMethod é client_secret_post, o padrão da aplicação embutida
FINNEST_PRIVATE_KEY_PEMtokenAuthMethod é private_key_jwt: a chave privada PEM da aplicação
FINNEST_KEY_IDprivate_key_jwt: o kid da chave no JWKS da aplicação
FINNEST_MTLS_CERT_PATHO certificado de transporte, apresentado só a matls-auth.<domain> do ambiente
FINNEST_MTLS_KEY_PATHA 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 ​

  1. Abra a pasta da coleção no Bruno (Open Collection).
  2. Escolha o ambiente local ou sandbox. No sandbox, troque domain pelo domínio da instalação e preencha authorisationServerId com o servidor de autorização da transmissora no Diretório.
  3. Rode receptora/consentimento/Criar consentimento, abra o redirectUrl da resposta no navegador e autorize na transmissora.
  4. Rode as demais requisições de receptora em ordem. O fluxo do Pix em iniciadora é 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.xml

A 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-body

No 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: error

Como 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_jwt e 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 de private_key_jwt verifica com a chave pública para qualquer cliente e endpoint.

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