Skip to content

Portal de API da instalação ​

A referência das APIs (portal Scalar) aparece em três lugares:

PortalEndereçoChamadas pelo navegador
Referência públicaReferência interativaNenhuma. Só mostra o formato das requisições.
Portal da instalaçãohttps://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 AdminNenhuma. 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 = true

Depois 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 deploy mostra https://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>/playground devolve uma resposta real da instalação.
  • finnest doctor mostra as verificações do portal sem falhas.

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