API pública e webhooks: autenticação, limites e erros

Como obter o token, em que ordem a Klyro valida cada chamada e as regras dos webhooks de saída.

A API pública permite integrar o seu sistema à Klyro, e os webhooks avisam o seu sistema quando algo acontece. Esta página resume como a Klyro valida cada chamada e por que um pedido pode ser recusado. Para o passo a passo de criar aplicativos, veja o artigo “Aplicativos OAuth e API REST da Klyro”.

Como obter um token?

  • Troque o client_id e o client_secret do seu aplicativo por um token de acesso.
  • O token vale 3.600 segundos (1 hora).
  • A troca é de servidor para servidor. A API não aceita chamadas diretas do navegador.
  • Falhas de autenticação são limitadas a 60 por minuto.

Em que ordem a Klyro valida cada chamada?

  1. Chamada vinda de navegador: recusada (405).
  2. Limite geral por IP antes da autenticação.
  3. Token ausente ou inválido: 401.
  4. Empresa suspensa: 402.
  5. Plano sem API: 403, com o código de plano sem API.
  6. Permissão (escopo) não concedida ao aplicativo: 403.
  7. Limite de requisições por minuto do plano: 429.
  8. Cota mensal de escritas (POST e PATCH) do plano: 403, com o código de cota excedida.
  9. Versão da API desconhecida ou descontinuada.

A API não está incluída no plano Starter. Nos demais planos, o limite por minuto e a cota mensal de escritas aumentam com o plano. A cota mensal usa o mês civil em UTC e pode atrasar até cerca de 3 horas na contagem.

Que regras de uso valem?

  • Paginação: 25 itens por padrão, no máximo 100, com cursor.
  • Idempotência: a chave Idempotency-Key deve ter de 1 a 256 caracteres.
  • Mensagens de WhatsApp pela API: número no formato E.164; só modelos aprovados de autenticação; até 5 envios por hora por destinatário e 200 por hora por aplicativo.
  • Mensagens de saída: só os canais Telegram e WhatsApp oficial, e o canal precisa ser o da conversa. Envio de SMS e e-mail pela API não está disponível.
  • Campanhas: de 1 a 500 destinatários por chamada.

Quais as regras dos webhooks?

ItemRegra
EndereçoHTTPS, porta 443, até 2.048 caracteres, sem usuário e senha na URL.
Endereços recusadoslocalhost, nomes terminados em .local ou .internal e qualquer nome que aponte para rede privada.
TentativasAté 5, com espera crescente entre elas.
AssinaturaVerifique a assinatura. O horário aceito tem tolerância de 300 segundos.
DuplicidadeO cabeçalho X-Klyro-Delivery é o mesmo entre tentativas, para você descartar repetidos.
HistóricoRegistros de tentativas são apagados após 30 dias. O trecho guardado da resposta tem 512 caracteres.
PlanoWebhooks não estão incluídos no plano Starter.

Resumo: token de 1 hora, chamadas só de servidor. 401 é token, 402 é conta suspensa, 403 é plano ou permissão, 429 é ritmo. Webhooks só em HTTPS na porta 443.

Checklist rápido

  • Renove o token antes de expirar.
  • Trate o 429 esperando e tentando de novo.
  • Use a chave de idempotência nas escritas.
  • Valide a assinatura dos webhooks e descarte entregas repetidas.