Autenticação
Como mandar a chave de API e como guardá-la com segurança.
Esta página é para quem vai configurar a chave no sistema que chama o TOPO. Ela explica os três jeitos de mandar a chave e as regras para ela não vazar.
Como conseguir a chave
A chave é gerada pela equipe TOPO. Peça ao suporte TOPO por um chamado, informando:
- o nome do sistema que vai usá-la, por exemplo "SAP balancete" ou "Power BI controladoria";
- o ambiente (staging para testes, produção para os dados reais);
- o que ele vai fazer: enviar balancete (
trial_balances:write), ler dados para BI (companies:read,chart_of_accounts:read,trial_balances:read,reconciliations:read,analytics:read) ou os dois.
O suporte entrega o segredo uma vez só. O TOPO guarda apenas o hash SHA-256 da chave e não consegue mostrá-la de novo. Se você perder a chave, peça outra.
Os três jeitos de mandar a chave
A chave vai sempre no cabeçalho HTTP. Escolha o jeito que o seu sistema guarda melhor. Os três valem para todas as rotas.
# 1. Authorization: Bearer
curl -s "$TOPO_API/api/v1/companies?limit=1" -H "Authorization: Bearer $TOPO_CHAVE"
# 2. X-API-Key
curl -s "$TOPO_API/api/v1/companies?limit=1" -H "X-API-Key: $TOPO_CHAVE"
# 3. Authorization: Basic, usuário "topo" e a chave como senha
curl -s "$TOPO_API/api/v1/companies?limit=1" -u "topo:$TOPO_CHAVE"No Basic, o TOPO usa a senha quando ela vem preenchida. Com a senha vazia, ele usa o usuário. O nome do usuário não importa: topo é só uma convenção. O Basic existe para o SAP guardar a chave no cofre de credenciais dele (veja a receita do SAP).
Na URL a chave é recusada. ?api_key=... responde 401, porque endereço aparece em log de proxy e no histórico do navegador.
Regras para usar a chave com segurança
- Uma chave por integração, com um nome que diga quem a usa ("SAP balancete"), e só com os escopos que aquela integração precisa. Assim, se uma chave vazar, você troca só ela.
- A chave mora no cofre do sistema que chama: User Credentials no SAP CPI, canal REST com Basic no PI/PO, destino SM59 no ABAP. Nunca em código de navegador, planilha compartilhada ou e-mail. No Power BI, a chave fica na credencial da fonte de dados ou num parâmetro do relatório. Nesse caso, não compartilhe o arquivo .pbix que tem a chave.
- Para trocar a chave, abra um chamado e peça a nova ao suporte TOPO, troque no cofre do sistema e avise o suporte para revogar a antiga. A revogação vale na chamada seguinte: a chave antiga passa a receber 401.
- Chave de staging começa com
topo_test_, e de produção comtopo_live_. Quem achar uma chave vazada sabe de que ambiente ela é. Se isso acontecer, avise o suporte TOPO por um chamado na hora.
Respostas de autenticação
| Status | Corpo | Quando |
|---|---|---|
| 401 | {"success":false,"error":"Chave de API inválida"} | Sem chave, chave errada, revogada, de outro ambiente ou na URL. O motivo não é dito, de propósito. |
| 403 | {"success":false,"error":"Escopo insuficiente: a chave não tem trial_balances:read"} | A chave é válida mas não tem o escopo da rota. A mensagem diz qual falta. |
| 429 | {"success":false,"error":"Muitas requisições em pouco tempo. Aguarde alguns segundos e tente de novo."} | Mais de 30 chamadas por minuto na mesma rota. Veja limites. |
O que a chave alcança
A chave age como um usuário de serviço do cliente, criado só para ela. Ela vê só as empresas do cliente que pediu a chave, e só os módulos que cada empresa contratou. Cada chamada fica registrada no TOPO em nome desse usuário de serviço, com o nome da chave. Um balancete enviado pela chave "SAP balancete" mostra como autor Chave de API SAP balancete (<prefixo>).
A chave tem o formato topo_<live|test>_<prefixo>_<segredo>. O prefixo tem 16 caracteres e o segredo tem 32. O prefixo é a parte visível da chave e não é segredo: é por ele que o suporte TOPO identifica a chave, por exemplo para revogá-la. Guarde a chave inteira em sigilo, mas pode citar o prefixo num chamado.
Use sempre https nos endereços da API.