Autenticação

A API ADS-Tools utiliza Bearer Tokens (API Keys) para autenticação. Cada API Key possui escopos específicos que controlam o acesso aos recursos.

API Keys

Todas as requisições devem incluir o header Authorizationcom sua API Key no formato Bearer Token.

Bash

# Formato do header de autorização
Authorization: Bearer ads_live_abc123...

# Exemplo com curl
curl -X GET "https://dev-api-tools.helbioads.com/api/v1/integration/leads" \
  -H "Authorization: Bearer ads_live_abc123..." \
  -H "Content-Type: application/json"

Importante

Nunca exponha sua API Key em código frontend ou repositórios públicos. Use sempre variáveis de ambiente.

Prefixos de API Key

sk_live_*

Chave de produção. Use em seu ambiente de produção.

sk_test_*

Chave de teste. Use durante desenvolvimento e testes.

Escopos

Cada API Key possui escopos que determinam quais operações podem ser realizadas. Ao criar uma API Key, escolha apenas os escopos necessários para sua integração.

Escopo	Descrição	Endpoints
`sync`	Sincronização de dados em lote	POST /sync
`leads:read`	Leitura de leads	GET /leads, GET /leads/:id
`leads:write`	Criação e atualização de leads	POST /leads, PUT /leads/:id
`contacts:read`	Leitura de contatos	GET /contacts, GET /contacts/:id
`contacts:write`	Criação e atualização de contatos	POST /contacts, PUT /contacts/:id
`tags:read`	Leitura de tags	GET /tags
`tags:write`	Criação de tags	POST /tags
`interactions:write`	Registro de interações	POST /leads/:id/interactions
`conversations:read`	Leitura de conversas	GET /leads/:id/conversations
`conversations:write`	Criação de conversas e mensagens	POST /leads/:id/conversations

Rate Limiting

Para garantir a estabilidade da API, aplicamos limites de taxa por API Key. O limite padrão é de 1000 requisições por minuto.

Headers de Rate Limit

Todas as respostas incluem headers informativos sobre o rate limit:

HTTP

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 985
X-RateLimit-Reset: 1704067200

Campo	Tipo	Descricao
`X-RateLimit-Limit`	number	Limite total de requisições por minuto
`X-RateLimit-Remaining`	number	Requisições restantes na janela atual
`X-RateLimit-Reset`	timestamp	Unix timestamp quando o limite será resetado

Erro 429: Too Many Requests

Quando o limite é excedido, a API retorna status 429:

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retryAfter": 45
  }
}

Dica: Use o header Retry-After ou o campo retryAfterna resposta para saber quando pode tentar novamente.

Erros de Autenticação

HTTP	Codigo	Descricao	Acao
401	`UNAUTHORIZED`	API Key inválida ou não fornecida	Verifique se a API Key está correta e no formato Bearer Token
403	`FORBIDDEN`	API Key válida mas sem permissão para o recurso	Verifique se a API Key possui o escopo necessário
403	`API_KEY_REVOKED`	API Key foi revogada	Crie uma nova API Key no dashboard
429	`RATE_LIMIT_EXCEEDED`	Limite de requisições excedido	Aguarde o tempo indicado em Retry-After

Boas Práticas

Use variáveis de ambiente para armazenar a API Key

Crie API Keys separadas para cada ambiente (dev, staging, prod)

Implemente retry com backoff exponencial para erros 429 e 5xx

Monitore os headers de rate limit para evitar bloqueios

Compartilhar API Keys entre múltiplos sistemas

Expor a API Key em código frontend ou logs

Fazer requisições sem verificar o rate limit restante