Skip to main content
Toda requisição precisa apresentar a chave de API em um cabeçalho HTTP. Não há autenticação por corpo da requisição nem por query string.
Se você seguiu uma versão anterior desta documentação, sua integração não funciona. Aquela versão instruía a enviar a chave no corpo da requisição, num formato que nunca foi aceito pela API — requisições assim sempre receberam 401. Use o cabeçalho abaixo. Os detalhes da mudança estão em Migração das rotas antigas.

​
Forma padrão

É a forma usada em todos os exemplos desta documentação, e a que a maioria dos clientes HTTP monta por padrão quando você configura um token.

​
Formas alternativas

As duas formas abaixo também são aceitas e produzem exatamente o mesmo resultado. Use-as se o seu cliente já estiver montado assim.
As três formas são equivalentes, inclusive para o limite de requisições: a mesma chave consome o mesmo saldo, independentemente do cabeçalho escolhido. Não há ganho em alternar entre elas.

​
A API é de servidor para servidor

Não chame esta API a partir de um navegador, aplicativo móvel ou qualquer código que o usuário final consiga inspecionar.
Há duas razões:
  1. A chave dá acesso total à sua conta. Exposta no navegador, ela pode ser lida por qualquer visitante.
  2. Tecnicamente não funciona. A política de CORS do servidor não libera os cabeçalhos de autenticação para origens de navegador, então a requisição de verificação prévia falha antes mesmo de a chamada sair.
O caminho correto é o seu servidor chamar a API e o seu front-end chamar o seu servidor.

​
Obter a chave

A chave é gerada no painel, em Configurações → API Keys. Ela é exibida uma única vez, no momento da criação.
Guarde a chave em local seguro e nunca a coloque em código-fonte público, aplicativo móvel ou página web.

​
Ciclo de vida da chave

Se a chave vazar, revogue-a no painel e gere outra. Não existe rotação parcial: a chave antiga para de funcionar assim que é revogada.

​
Erros de autenticação

Falha de autenticação segue o mesmo envelope de erro de qualquer outro problema. Veja Respostas e erros.
O 401 é o mesmo para chave ausente, chave inválida, chave revogada, chave expirada e empresa inativa. Essa indistinção é proposital — devolver o motivo exato permitiria descobrir quais chaves existem.

​
Testar a conexão

O endpoint GET /ping confirma que a chave é válida sem produzir efeito nenhum. Ele tem limite de 5 requisições por minuto, então serve para verificação pontual e para monitoramento em intervalos de 30 segundos ou mais — não para verificação a cada poucos segundos.