Authorization:
Enviar a chave
- Só no header. A chave nunca é aceita na query string (
?api_key=,?key=,?token=). Uma requisição assim recebe401. - Exatamente como foi copiada. Um espaço ou uma quebra de linha antes ou depois invalida a chave.
- A conta é a dona da chave. Não existe parâmetro de conta: nenhum caminho, query ou header troca a conta consultada. Para ler outra conta, use uma chave criada nela.
Criar uma chave
A chave é criada no dashboard, em Configurações → Chaves de API → Criar chave, por um administrador da conta.- Nome da chave: diga onde ela é usada (
ERP,n8n,Planilha financeira). O nome ajuda a saber qual chave revogar depois. - Expiração (opcional): no mínimo 1 hora a partir da criação. Sem data, a chave não expira.
- Aparece uma única vez. A chave é exibida só na criação, no painel Chave de API criada. A Zouti guarda apenas um hash e não consegue mostrá-la de novo. Perdeu a chave? Crie outra e revogue a antiga.
- Cerca de 1 segundo para valer. Se a primeira chamada logo depois da criação receber
401, espere alguns segundos e repita. - Até 10 chaves ativas por conta. Para criar a 11ª, revogue uma.
Guardar a chave
Uma chave lê todos os recursos públicos da conta, inclusive os dados completos dos compradores: nome, e-mail, telefone, CPF/CNPJ e endereço. Trate-a como uma senha.- Guarde-a num cofre de segredos ou numa variável de ambiente do servidor (
ZOUTI_API_KEY). - Nunca a coloque em código de front-end, aplicativo móvel ou repositório de código.
- A API não tem CORS: chamadas feitas do navegador são bloqueadas. Chame a API só do seu servidor.
- Use uma chave por sistema. Assim, revogar a chave de um sistema não para os outros.
Trocar a chave sem parar a integração
1
Crie a chave nova
Em Configurações → Chaves de API, crie uma chave nova. A antiga continua valendo.
2
Troque nos seus sistemas
Atualize o segredo em todos os lugares que usam a chave antiga e confira que as chamadas
seguem respondendo
200.3
Revogue a antiga
No menu ⋮ da chave antiga, escolha Revogar. A revogação vale na requisição seguinte: a
partir dela, a chave antiga recebe
401.Quando a chave é recusada
Chave ausente, malformada, inexistente, revogada ou expirada recebe sempre o mesmo401
invalid_api_key, com a mesma mensagem. A resposta não diz qual foi o caso.
A chave é conferida antes dos parâmetros. Uma requisição com chave errada e parâmetro inválido
(por exemplo, limit=500) recebe 401, não 400.
Não repita um 401 em laço: 30 respostas 401 para o mesmo IP em 60 segundos bloqueiam o IP com
429. Veja Limites de requisição.
Somente HTTPS
A API só aceitahttps://. Uma requisição em HTTP recebe 400 com corpo em texto puro
(Use HTTPS: a API pública da Zouti não aceita HTTP.), sem redirecionamento.
Se uma chave já foi enviada por HTTP, ela trafegou sem criptografia: revogue-a e crie outra.

