Documentação da API

Introdução

A API do Cliker usa URLs previsíveis orientadas a recursos, corpos e respostas em JSON, e códigos de status HTTP padrão. Toda chamada é escopada à sua conta — você nunca vê dados de outra conta, e uma chave de API só enxerga o que os escopos dela permitem.

A URL base para todas as chamadas é:

http://localhost:3100/api-v1

Como começar: gere uma chave em http://localhost:3100/api-keys (é preciso estar logado — entre na sua conta primeiro), escolha os escopos que essa chave vai usar, e faça sua primeira chamada:

curl http://localhost:3100/api-v1/account \
  -H "Api-Key: cn_sua_chave_aqui"

Autenticação

Envie sua chave de API no header Api-Key em toda requisição. Chaves são específicas da sua conta (não de um usuário) e podem ser revogadas a qualquer momento em Configurações → Chaves de API.

Api-Key: cn_0a9cd8d838ad847ce88aa08eff07e4e89b4e56fe1982a82c

Cada chave tem um ou mais escopos, definidos na criação:

• read — informações da conta
• contacts — listar e criar contatos
• campaigns — listar e disparar campanhas
• transactional — enviar e-mails transacionais avulsos

Uma chamada sem a chave retorna 401 missing_api_key; com uma chave inválida, 401 invalid_api_key; sem o escopo necessário, 403 insufficient_scope.

Limites de taxa

Cada plano tem um limite de requisições por minuto, aplicado por conta (não por chave — todas as chaves da mesma conta dividem o mesmo limite). Ultrapassar o limite retorna 429 rate_limit_exceeded.

Erros

Erros sempre retornam JSON com um código de status HTTP apropriado:

{
  "error": "mensagem descrevendo o problema",
  "data": []
}

Conta

Retorna informações básicas da conta dona da chave usada — nome, status, plano e limites atuais.

curl http://localhost:3100/api-v1/account \
  -H "Api-Key: cn_sua_chave_aqui"

{
  "name": "Minha Empresa",
  "status": "active",
  "plan_code": "business",
  "max_contacts": 50000,
  "max_emails_per_month": 200000
}

Contatos

Contatos vivem dentro de uma lista específica — ao criar um contato pela API, informe a qual lista ele pertence. A listagem, porém, é unificada: retorna contatos de todas as listas que a conta possui, sem duplicar por e-mail.

Parâmetros opcionais: status (1=inscrito, 2=descadastrado, 3=bounce, 4=reclamação) e limit (padrão 100, máximo 500).

curl "http://localhost:3100/api-v1/contacts?status=1&limit=50" \
  -H "Api-Key: cn_sua_chave_aqui"

{
  "data": [
    {
      "email": "ana@exemplo.com.br",
      "status": 1,
      "lists": [
        "Newsletter"
      ],
      "created": "2026-06-01T12:00:00.000Z"
    }
  ]
}

Cria (ou atualiza, se o e-mail já existir na lista) um contato. Campos além de email dependem dos campos customizados configurados na lista de destino — o exemplo abaixo assume campos "first_name"/"last_name".

curl -X POST http://localhost:3100/api-v1/contacts \
  -H "Api-Key: cn_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": 12,
    "email": "ana@exemplo.com.br",
    "first_name": "Ana"
  }'

{
  "id": 4831
}

Campanhas

Parâmetro opcional: limit (padrão 50, máximo 200).

curl http://localhost:3100/api-v1/campaigns \
  -H "Api-Key: cn_sua_chave_aqui"

{
  "data": [
    {
      "id": 88,
      "name": "Newsletter de julho",
      "cid": "cmp-xyz",
      "status": 1,
      "scheduled": null,
      "created": "2026-06-01T12:00:00.000Z"
    }
  ]
}

Agenda o envio imediato de uma campanha existente (criada pela interface). Só funciona se ela estiver em um estado que permita iniciar o envio — do contrário retorna 409.

curl -X POST http://localhost:3100/api-v1/campaigns/88/send \
  -H "Api-Key: cn_sua_chave_aqui"

{
  "status": 5
}

E-mail transacional

Envia um e-mail avulso (recibo, confirmação, redefinição de senha) fora do fluxo de campanhas e listas — não passa por inscrição/descadastro. Requer o id de uma configuração de envio já existente na sua conta.

curl -X POST http://localhost:3100/api-v1/transactional/send \
  -H "Api-Key: cn_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "send_configuration_id": 3,
    "to": "cliente@exemplo.com.br",
    "subject": "Seu pedido foi confirmado",
    "html": "<p>Obrigado pela compra!</p>"
  }'

{
  "queued": true
}