Skip to content

Operar a sua instalação ​

Este guia é o caminho da participante que instala e roda o Finnest Power na própria conta de nuvem, numa máquina sem o código-fonte da plataforma. A CLI finnest é a ferramenta do operador: ela instala, implanta e confere a instalação. Consentimentos, leitura de dados e pagamentos são feitos pela API da plataforma, não pela CLI.

1. Instalar a CLI ​

O instalador atende macOS (Apple Silicon e Intel) e Linux glibc (amd64 e arm64):

bash
curl --proto '=https' --proto-redir '=https' -fL https://get.finnest.com.br | sh

Abra um novo shell antes do próximo passo. Os detalhes, inclusive o Windows nativo, estão em Instalar a CLI.

2. Conferir a versão e a estação ​

bash
finnest version
finnest update --check
finnest doctor --cloud=aws --environment=sandbox
  • version mostra a versão da CLI, que é também a versão da plataforma que ela implanta.
  • update --check só consulta se há versão nova; não muda nada. Com self_update = false na seção [plane], valor que o finnest init grava por padrão, ele falha com PLANE_CAPABILITY_DISABLED.
  • doctor confere os pré-requisitos e mostra como corrigir cada um que faltar. O Node.js só é exigido para o deploy e os outros comandos de ciclo de vida; version, status, smoke e health rodam sem ele.

3. Preparar o alvo e a configuração ​

O alvo é a combinação de nuvem, ambiente e região. O setup grava o alvo no finnest.toml e o deixa ativo, e os comandos seguintes dispensam --cloud e --environment. Informe sempre o --participant-role: é o papel de Open Insurance (OPIN) da instalação (transmitter, receiver ou both), e sem ele vale transmitter. Em seguida, o Configuration Workspace recebe o material regulado, e o commit revisado dele grava o recibo que o deploy exige. Os detalhes estão em Primeiros passos.

bash
finnest setup --cloud=aws --environment=sandbox --participant-role=transmitter
finnest config workspace open --goal=apply
finnest config readiness --goal=apply
finnest target list

Para trocar de alvo, use finnest target use <id>, por exemplo finnest target use aws-sandbox.

Não há login separado na Finnest: todos os comandos deste guia usam as credenciais de nuvem do alvo (perfil SSO da AWS ou az login).

4. Implantar e confirmar a saúde ​

Siga Deploy na AWS ou Azure para as configurações do alvo (domínio, DNS, material regulado). Depois do deploy, confirme a saúde e a versão antes de usar a API:

bash
finnest deploy --preview
finnest deploy --apply --yes --confirm=aws:<conta>:sandbox
finnest status
finnest smoke
finnest health --suite=post-deploy

O --confirm repete a identidade do alvo: aws:<conta>:<ambiente> na AWS ou azure:<tenant>:<assinatura>:<ambiente> na Azure. Sem ele, o --apply é recusado.

ComandoO que responde
finnest statusIdentidade do alvo, versão implantada, prontidão, pendências e próximos passos.
finnest smokeSe o runtime implantado responde aos testes de fumaça.
finnest health --suite=<s>Suítes de endpoints: quick, post-deploy, resources, regulatory ou deep.
finnest doctorSe a estação e o alvo estão prontos para o deploy.

Um comando que falha sai com código diferente de zero, mostra o código do erro, os próximos passos e o link para a documentação do erro.

5. Guardar a evidência ​

Cada comando grava um registro da execução em .finnest/runs. Para um chamado de suporte, exporte o pacote em vez de copiar a saída do terminal:

bash
finnest evidence list aws-sandbox
finnest evidence export aws-sandbox --json

6. Diretório e registro dinâmico (Open Insurance) ​

Ligue o alvo à sua organização no Diretório do OPIN uma vez. O comando lê o Diretório com o seu BRCAC, sem alterar nada, e preenche no finnest.toml os ids da organização, do servidor de autorização e do software:

bash
finnest opin directory link --directory-client-id <client-id> --brcac-cert ./brcac.pem --brcac-key ./brcac.key

Com as mesmas opções, finnest opin directory diff compara o registro do servidor de autorização no Diretório com o issuer implantado e falha quando eles divergem.

Na receptora, o catálogo de transmissoras se atualiza a partir do Diretório a cada seis horas. Para atualizar agora e ver como terminou a última atualização:

bash
finnest opin directory run --yes
finnest opin directory status

O servidor de autorização que recebe um registro dinâmico só aceita uma SSA emitida há menos de 5 minutos. Para buscar uma nova:

bash
finnest dcr fetch-ssa --org-id <id> --software-id <id> --directory-client-id <client-id> --brcac-cert ./brcac.pem --brcac-key ./brcac.key --out ./ssa.jwt

Na receptora, o comando abaixo mostra o estado sanitizado do registro dinâmico com uma transmissora. --ecosystem é obrigatório: ofb para Open Finance Brasil (receptora no banking, realm finnest-ofb) e opin para Open Insurance (receptora no insurance, realm finnest-opin).

bash
finnest dcr registration-status <authorisation-server-id> --ecosystem ofb
finnest dcr registration-status <authorisation-server-id> --ecosystem opin

Uma tentativa que ficou em registering só é liberada depois que a transmissora confirma o estado do registro, fora do Finnest. Com o attemptId lido acima e a referência dessa confirmação:

bash
finnest dcr reconcile <authorisation-server-id> <attempt-id> provider_confirmed_not_created \
  --ecosystem ofb --evidence-reference <referencia-da-transmissora> --yes

Cada ecossistema usa a credencial do próprio cliente operador: ofb-dcr-operator-client-secret (finnest-ofb-dcr-operator) ou opin-dcr-operator-client-secret (finnest-opin-dcr-operator).

7. Material de Open Insurance ​

  • Token de monitoramento. Toda instalação de Open Insurance usa opin-monitoring-internal-token. O finnest deploy --apply gera e grava o token quando ele falta. Para gravá-lo antes, ou se o deploy pedir:

    bash
    finnest secrets write opin-monitoring-internal-token --yes
  • Reporte ao MOP. Toda participante OPIN reporta ao MOP as chamadas que faz como receptora e as que atende como transmissora. O reporte vem ligado (opin_mop = "on" no alvo). Para desligá-lo, informe opin_mop = "off" e o motivo em opin_mop_off_reason. Com o reporte ligado, qualquer papel precisa:

    • da senha do RabbitMQ do gateway do MOP, gerada pela CLI com finnest secrets write opin-mop-rabbitmq-password --yes;
    • de opin_pcm_signing_kid, o mesmo kid do BRSEAL que o PCM usa;
    • da chave privada do BRSEAL no formato PKCS#8 (-----BEGIN PRIVATE KEY-----).

    Um papel que transmite dados também precisa de as_id em [opin], o servidor de autorização sob o qual reporta as chamadas que atende. O finnest doctor para a instalação sem o opin_pcm_signing_kid ou, num papel que transmite, sem o as_id. O deploy a recusa sem a senha do RabbitMQ ou com a chave do BRSEAL fora do PKCS#8.

8. Retenção e jornada da receptora (Open Insurance) ​

A receptora guarda o ciclo de vida dos consentimentos e a trilha de x-fapi-interaction-id pelo prazo regulatório. Os dois comandos abaixo só leem: o primeiro mostra onde a retenção está, e o segundo confere o arquivo regulatório selado.

bash
finnest opin retention
finnest opin retention verify

Para percorrer a jornada da receptora passo a passo:

bash
finnest opin receiver smoke --cloud=<nuvem> --environment=<ambiente>
finnest opin receiver smoke --cloud=<nuvem> --environment=<ambiente> --live

Sem --live, nada sai da máquina: o comando só monta as URLs a partir da configuração local. Com --live, ele lê o Diretório, a última atualização do catálogo e a página de retorno do redirect_uri. A opção --create-connection cria uma conexão real com uma transmissora e, em produção, é uma escrita real.

No Open Finance, a receptora e a iniciadora têm o mesmo percurso:

bash
finnest ofb receiver smoke --cloud=<nuvem> --environment=<ambiente> --live
finnest ofb initiator smoke --cloud=<nuvem> --environment=<ambiente> --live

O --live lê o Diretório, o discovery do realm finnest-ofb, a página de callback e, com --transmitter, o registro de DCR. A escrita real (--create-connection na receptora, --create-payment na iniciadora, esta só no sandbox e até R$ 1,00) recebe o CPF do titular só por --stdin, exige --yes e usa o segredo ofb-smoke-client-secret, gerado por finnest secrets write ofb-smoke-client-secret --yes. O passo a passo, o arquivo de pagamento e a tabela de status e de exit estão no Guia OFB da participante.

9. Console Power Admin ​

O Power Admin fica em admin.<domínio>. As telas são: Início, Indicadores, Onboarding, Conformidade, Drift regulatório, Testes de endpoint, DCR, PCM, Relatório do Diretor, Receptora, Monitoramento, Operações, Primeiros passos da API, Aplicações, Documentação das APIs e Usuários. Receptora, Monitoramento e Aplicações só aparecem quando a instalação serve o Open Insurance.

O papel do membro define o que ele vê e faz. O dono e o admin gerenciam os membros na tela Usuários. O operador com as credenciais da nuvem também pode gerenciá-los com finnest admin user, que roda no pod do Power em nome de um membro (--actor, por padrão o owner.email do perfil). O pod recusa o comando se esse membro estiver desativado ou não puder gerir membros, e não deixa dar um papel acima do dele.

PapelTelasAções
ownerTodasTodas
adminTodasAgir, aprovar (atestar relatórios, aprovar lotes da PCM, decidir achados) e gerir membros
operatorTodasAgir, sem aprovar nem gerir membros
auditorTodasSó leitura
developerSó Primeiros passos da API e Documentação das APIsSó leitura da documentação

Ajuda e automação ​

  • finnest help <comando> lista as opções e os exemplos de cada comando, por exemplo finnest help target use. A Referência de comandos traz o mesmo conteúdo.
  • --json imprime o envelope versionado, para automação.
  • A saída --json, os logs e a evidência nunca trazem segredo, token ou número de documento de cliente. A única exceção no terminal é a senha temporária que admin owner create, admin owner reset e os comandos de admin user que emitem senha mostram uma vez numa sessão interativa.

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