Aparência
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 | shAbra 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=sandboxversionmostra a versão da CLI, que é também a versão da plataforma que ela implanta.update --checksó consulta se há versão nova; não muda nada. Comself_update = falsena seção[plane], valor que ofinnest initgrava por padrão, ele falha comPLANE_CAPABILITY_DISABLED.doctorconfere os pré-requisitos e mostra como corrigir cada um que faltar. O Node.js só é exigido para odeploye os outros comandos de ciclo de vida;version,status,smokeehealthrodam 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 listPara 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-deployO --confirm repete a identidade do alvo: aws:<conta>:<ambiente> na AWS ou azure:<tenant>:<assinatura>:<ambiente> na Azure. Sem ele, o --apply é recusado.
| Comando | O que responde |
|---|---|
finnest status | Identidade do alvo, versão implantada, prontidão, pendências e próximos passos. |
finnest smoke | Se 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 doctor | Se 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 --json6. 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.keyCom 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 statusO 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.jwtNa 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 opinUma 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> --yesCada 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. Ofinnest deploy --applygera e grava o token quando ele falta. Para gravá-lo antes, ou se o deploy pedir:bashfinnest secrets write opin-monitoring-internal-token --yesReporte 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, informeopin_mop = "off"e o motivo emopin_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 mesmokiddo 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_idem[opin], o servidor de autorização sob o qual reporta as chamadas que atende. Ofinnest doctorpara a instalação sem oopin_pcm_signing_kidou, num papel que transmite, sem oas_id. O deploy a recusa sem a senha do RabbitMQ ou com a chave do BRSEAL fora do PKCS#8.- da senha do RabbitMQ do gateway do MOP, gerada pela CLI com
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 verifyPara 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> --liveSem --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> --liveO --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.
| Papel | Telas | Ações |
|---|---|---|
owner | Todas | Todas |
admin | Todas | Agir, aprovar (atestar relatórios, aprovar lotes da PCM, decidir achados) e gerir membros |
operator | Todas | Agir, sem aprovar nem gerir membros |
auditor | Todas | Só leitura |
developer | Só Primeiros passos da API e Documentação das APIs | Só leitura da documentação |
Ajuda e automação
finnest help <comando>lista as opções e os exemplos de cada comando, por exemplofinnest help target use. A Referência de comandos traz o mesmo conteúdo.--jsonimprime 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 queadmin owner create,admin owner resete os comandos deadmin userque emitem senha mostram uma vez numa sessão interativa.