Aparência
Portal de API da instalação
A referência das APIs (portal Scalar) aparece em três lugares:
| Portal | Endereço | Chamadas pelo navegador |
|---|---|---|
| Referência pública | Referência interativa | Nenhuma. Só mostra o formato das requisições. |
| Portal da instalação | https://docs.<domínio> | A referência mostra requisições e cURL para api.<domínio>, sem executá-las. Só a página /playground executa chamadas, e só às APIs de dados públicos, quando o módulo de dados públicos está ligado. |
| Power Admin, Documentação das APIs | /documentacao no Power Admin | Nenhuma. Mostra as especificações dos ecossistemas que a instalação atende, para quem tem a permissão docs.read. |
As APIs protegidas de Open Finance e Open Insurance não podem ser chamadas do navegador: o FAPI-BR exige mTLS, PAR, requisição assinada e JARM.
Ativar o portal da instalação
O portal vem desligado. Para ativá-lo, ligue a opção no alvo de deploy, no finnest.toml:
toml
# Alvo nomeado (perfil):
[profile.banco-prod]
# …demais campos do alvo…
docs_enabled = true
# Formato antigo, com um único alvo:
[deployment.docs]
enabled = trueDepois rode o deploy:
bash
CLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --preview
# <confirmação>: aws:<conta>:<ambiente> ou azure:<tenant>:<assinatura>:<ambiente>
finnest deploy --cloud="$CLOUD" --environment="$ENVIRONMENT" --apply --yes --confirm=<confirmação>Com o portal ligado, o resultado do deploy mostra o endereço em Endpoints → docs.
Certificado TLS na primeira ativação
docs.<domínio> é um host novo. O certificado TLS é emitido pelo Let's Encrypt, via cert-manager, depois que a rota é aplicada, e isso leva alguns minutos. Se o navegador mostrar um aviso de certificado (por exemplo, NET::ERR_CERT_COMMON_NAME_INVALID) logo após o deploy, espere alguns minutos e recarregue a página.
Para confirmar que o portal está no ar:
bash
CLOUD=aws ENVIRONMENT=sandbox # ou: azure, prod
finnest doctor --cloud="$CLOUD" --environment="$ENVIRONMENT"Com o portal ligado no finnest.toml, o doctor roda duas verificações. docs-portal-reach confirma que https://docs.<domínio>/ responde por HTTPS sem erro 5xx; uma falha de TLS conta como fora do ar. docs-portal-spec confirma que specs/banking/openapi.json é um documento OpenAPI com ao menos um caminho.
Verificação
- O resultado de
finnest deploymostrahttps://docs.<domínio>em Endpoints → docs. - Depois da emissão do certificado,
docs.<domínio>abre a referência sem aviso de TLS. - Com o módulo de dados públicos ligado, uma chamada em
https://docs.<domínio>/playgrounddevolve uma resposta real da instalação. finnest doctormostra as verificações do portal sem falhas.