Pular para o conteúdo principal
Toda requisição se autentica com uma chave de API da conta, enviada no header Authorization:
Ainda não há modo de teste. Não existe chave de teste nem ambiente de sandbox: toda chamada, com qualquer chave, lê dados reais de produção da conta.

Enviar a chave

  • Só no header. A chave nunca é aceita na query string (?api_key=, ?key=, ?token=). Uma requisição assim recebe 401.
  • 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.
Revogue na hora qualquer chave que possa ter vazado: publicada num repositório, enviada por chat ou por HTTP.

Quando a chave é recusada

Chave ausente, malformada, inexistente, revogada ou expirada recebe sempre o mesmo 401 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ó aceita https://. 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.