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_ide oclient_secretdo 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?
- Chamada vinda de navegador: recusada (405).
- Limite geral por IP antes da autenticação.
- Token ausente ou inválido: 401.
- Empresa suspensa: 402.
- Plano sem API: 403, com o código de plano sem API.
- Permissão (escopo) não concedida ao aplicativo: 403.
- Limite de requisições por minuto do plano: 429.
- Cota mensal de escritas (POST e PATCH) do plano: 403, com o código de cota excedida.
- 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-Keydeve 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?
| Item | Regra |
|---|---|
| Endereço | HTTPS, porta 443, até 2.048 caracteres, sem usuário e senha na URL. |
| Endereços recusados | localhost, nomes terminados em .local ou .internal e qualquer nome que aponte para rede privada. |
| Tentativas | Até 5, com espera crescente entre elas. |
| Assinatura | Verifique a assinatura. O horário aceito tem tolerância de 300 segundos. |
| Duplicidade | O cabeçalho X-Klyro-Delivery é o mesmo entre tentativas, para você descartar repetidos. |
| Histórico | Registros de tentativas são apagados após 30 dias. O trecho guardado da resposta tem 512 caracteres. |
| Plano | Webhooks 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.