Voltar ao início

Como funciona a API do Klyk

Última atualização: Agosto de 2026

A API serve para o seu sistema fazer sozinho o que você faria no painel: criar um link por campanha, trocar o destino de um link já publicado, puxar o relatório para o seu próprio relatório. Este texto conta o percurso inteiro, na ordem em que ele acontece — a referência campo a campo está na documentação.

Em que planos existe

A API está no Pro e no Business. Numa conta Free toda chamada responde 403, inclusive a de teste — não é limite de volume, é ausência do recurso.
DemonstraçãoDa chave ao webhook, do lado de quem integra1/6
  1. 1Ter o plano, e gerar a chave

    A API existe no Pro e no Business. Numa conta Free toda chamada responde 403 — inclusive a de teste.

    • A chave se gera no painel, em Configurações → API, e aparece uma vez só.
    • O Klyk não guarda a chave: guarda o SHA-256 dela. Perdeu, é gerar outra — e a antiga morre no mesmo instante.
    • Guarde em variável de ambiente. Nunca no código versionado, e nunca como argumento de linha de comando.
  2. 2A primeira chamada, que não altera nada

    GET /api/v1/me confirma se a chave vale, antes de você escrever o resto da integração.

    • 401 é chave errada ou revogada. 403 é chave certa e plano sem API. São coisas diferentes, e a resposta diz qual.
    • Esta resposta é a única achatada, sem o envelope do resto — Zapier e Make montam o nome da conexão a partir dos campos de primeiro nível.
  3. 3O sistema dele cria links sozinho

    É aqui que a integração vira produto: a loja gera um link por campanha, o CRM um por vendedor, o disparo de e-mail um por envio.

    • O campo do apelido é custom_code, e não alias. Campo desconhecido é ignorado em silêncio — quem mandar alias recebe 201 e fica com um código aleatório.
    • Código já em uso devolve 409. URL inválida, 400.
    • O link aparece no painel na mesma hora, junto com os criados à mão. Não há links da API separados.
  4. 4Ler de volta, e ler o relatório

    Guardando o id, dá para pegar o estado atual do link e os cliques dele quando quiser.

    • GET /v1/links/:id traz o link com total_clicks.
    • GET /v1/links/:id/analytics traz by_country, by_device e by_source, no período pedido.
    • Link que não é seu e link que não existe respondem os dois 404: distinguir contaria a um estranho que aquele id existe.
  5. 5O webhook: agora a seta inverte

    Nas quatro etapas anteriores o sistema dele chamou o Klyk. A partir daqui é o Klyk que chama o sistema dele, a cada evento, sem ser perguntado.

    • A assinatura é o HMAC-SHA256 de timestamp + "." + corpo cru— e não do corpo sozinho. Quem implementar como "HMAC do payload" rejeita todas as entregas legítimas e conclui que o Klyk manda assinatura errada.
    • Compare sobre o corpo CRU, antes de qualquer JSON.parse: reserializar muda espaços e ordem de chaves.
    • Cada entrega espera até 10 segundos pela resposta. Responda rápido e processe depois, em fila.
  6. 6Os limites, e o que fazer com cada recusa

    100 requisições por hora, por chave, em janela deslizante. Vale igual para Pro e Business — não é degrau de plano.

    • Toda resposta traz X-RateLimit-Remaining e X-RateLimit-Reset, para o sistema dele parar antes de estourar.
    • Os limites de links do plano valem igual pela API: Free 25, Pro 1.000, Business 3.500 links novos por mês.
    • 400 é corpo inválido — repetir não resolve. 429 é esperar até o Reset. 500 é nosso.

1. A chave, e por que ela aparece uma vez só

Você gera a chave no painel, em Configurações → API. Ela aparece na tela naquele instante, e não volta a aparecer: o Klyk guarda o SHA-256 dela, não a chave. É o mesmo raciocínio da senha — um vazamento do banco não entrega a chave de ninguém.

Perdeu, não há recuperar: gera outra, e a anterior deixa de valer no mesmo instante.

Onde guardar

Em variável de ambiente. Nunca no código versionado, e nunca como argumento de linha de comando — argumento fica no histórico do terminal e aparece na lista de processos para qualquer usuário da máquina.

2. As rotas

MétodoRotaO que faz
GET/api/v1/meA conta: id, e-mail, plano. É o teste da chave
GET/api/v1/linksLista os links, do mais novo para o mais antigo
POST/api/v1/linksCria um link
GET/api/v1/links/:idLê um link, com o total de cliques
PATCH/api/v1/links/:idTroca destino, título ou ativação
DELETE/api/v1/links/:idApaga — e o histórico vai junto
GET/api/v1/links/:id/analyticsO relatório de cliques
GET/api/v1/webhooksLista as inscrições
POST/api/v1/webhooksInscreve uma URL sua
DELETE/api/v1/webhooks/:idCancela a inscrição

Salvo /v1/me, toda resposta vem no envelope { "data": …, "error": … }. O /v1/me é achatado de propósito: Zapier, Make e n8n montam o nome da conexão a partir dos campos de primeiro nível, e um envelope faria a conexão aparecer sem nome.

3. O limite de requisições

100 por hora, por chave, em janela deslizante. Vale igual para Pro e Business: não é degrau de plano.

Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset — inclusive as que deram certo. É o que permite ao seu sistema parar antes de estourar, em vez de descobrir no 429.

Os limites do plano valem igual pela API, porque saem da mesma tabela: Free 25, Pro 1.000 e Business 3.500 links novos por mês. Nada do que já foi criado deixa de funcionar por causa do limite.

4. O webhook inverte o sentido

Nas rotas acima, o seu sistema chama o Klyk. O webhook é o contrário: você inscreve uma URL sua, e o Klyk passa a chamá-la a cada evento — link criado, link clicado, destino alterado, link pausado, link apagado.

A assinatura não é o que parece

O HMAC-SHA256 é calculado sobre o timestamp, um ponto, e o corpo cru — e não sobre o corpo sozinho. O cabeçalho vem com o prefixo sha256=. Quem implementar a verificação como "HMAC do payload" vai rejeitar todas as entregas legítimas e concluir que o Klyk manda assinatura errada.

Compare sobre o corpo cru, antes de qualquer JSON.parse: reserializar muda espaços e ordem de chaves, e a assinatura deixa de bater.

Três coisas que fazem perder tempo

Como testar antes de escrever a integração

A conta que você usa para testar é a sua conta de verdade: link criado pela API é link no painel. Vale começar por GET /api/v1/me, que não altera nada, e só depois criar.

Ver a documentação completaComo funcionam as contas em equipeTodos os textos