​
API Keys

A ZucroPay usa API Keys para autenticar requisições. Você pode gerenciar suas API Keys no Dashboard.

​
Formato da API Key

As API Keys seguem o formato: 
zp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Nunca compartilhe sua API Key! Ela dá acesso completo à sua conta. Se você suspeitar que ela foi comprometida, revogue-a imediatamente no Dashboard.

​
Como Autenticar

Existem duas formas de enviar sua API Key:

​
Header X-API-Key (Recomendado)

curl -X GET https://api.appzucropay.com/api/v1/charges \
  -H "X-API-Key: zp_sua_api_key_aqui"

​
Header Authorization

curl -X GET https://api.appzucropay.com/api/v1/charges \
  -H "Authorization: Bearer zp_sua_api_key_aqui"

​
Gerenciando API Keys

​
Criar uma API Key

1

Acesse o Dashboard

Faça login em dashboard.appzucropay.com
2

Vá em Integrações

No menu lateral, clique em Integrações
3

Crie a Key

Clique em Criar Nova API Key e dê um nome descritivo
4

Copie e guarde

Copie sua API Key e guarde em local seguro. Ela não será exibida novamente!

​
Revogar uma API Key

Se você precisa revogar uma API Key (por segurança ou porque não está mais usando):
  1. Vá em Integrações no Dashboard
  2. Encontre a API Key que deseja revogar
  3. Clique no botão Revogar
  4. Confirme a ação
API Keys revogadas param de funcionar imediatamente. Certifique-se de atualizar suas integrações antes de revogar.

​
Erros de Autenticação

​
401 - API Key não fornecida

{
  "error": "API Key não fornecida",
  "code": "API_KEY_MISSING"
}
Solução: Adicione o header X-API-Key com sua API Key.

​
401 - API Key inválida

{
  "error": "API Key inválida ou inativa",
  "code": "API_KEY_INVALID"
}
Solução: Verifique se a API Key está correta e não foi revogada.

​
403 - Conta suspensa

{
  "error": "Conta suspensa ou bloqueada",
  "code": "ACCOUNT_SUSPENDED"
}
Solução: Entre em contato com o suporte.

​
Rate Limiting

A API possui limites de requisições para garantir estabilidade:
EndpointLimiteJanela
Geral100 req1 min
Criação de cobranças60 req1 min
Webhooks500 req1 min
Quando você excede o limite, a API retorna status 429: 
{
  "error": "Muitas requisições. Tente novamente em alguns minutos.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 45
}

​
Headers de Rate Limit

Cada resposta inclui headers informativos: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705761300

​
Boas Práticas

Segurança

  • Nunca exponha a API Key no frontend
  • Use variáveis de ambiente
  • Revogue keys comprometidas imediatamente

Rotação

  • Crie novas keys periodicamente
  • Use keys diferentes para dev/prod
  • Mantenha apenas keys em uso

Implementação

  • Trate erros 401/403 adequadamente
  • Implemente retry com backoff para 429
  • Log de uso para auditoria

Armazenamento

  • Use secrets managers (AWS Secrets, Vault)
  • Nunca commite keys no código
  • Criptografe em repouso