API pública do Cloaker

v1 — /api/v1 — para automatizar criação de projetos, campanhas, tokens e consultar logs/alertas sem entrar no painel.

Base URL: https://SEU-DOMINIO-CLOAKER/api/v1

Autenticação: header x-api-key: SUA_CHAVE em toda requisição. Gere/revogue chaves em Painel → Chaves de API.

Rate limit: 60 requisições/minuto por conta (não por IP).

Projetos Campanhas Tokens Bot stats Logs e alertas Webhooks Conversão (vendas) Proteção de origem Erros

Projetos

GET /projects

Lista todos os projetos da conta autenticada.

curl -H "x-api-key: SUA_CHAVE" https://seu-dominio/api/v1/projects

POST /projects

Cria um projeto novo. domain precisa ser único na plataforma inteira.

curl -X POST https://seu-dominio/api/v1/projects \
  -H "x-api-key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"name":"Minha oferta","domain":"meudominio.com","funnel_url":"/","safe_page_url":"/safe"}'

Resposta inclui verification_instructions (registro TXT que precisa existir no DNS antes do domínio começar a servir tráfego real).

Campanhas

POST /projects/:projectId/campaigns

Cria (ou atualiza o nome de) uma campanha vinculada a uma plataforma de anúncios.

curl -X POST https://seu-dominio/api/v1/projects/PROJECT_ID/campaigns \
  -H "x-api-key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"platform":"meta","platform_campaign_id":"120210...", "name":"Campanha BR"}'

Tokens

POST /campaigns/:campaignId/tokens

Gera (ou reaproveita) o token de divulgação de uma campanha — o link final é /go/<token>.

curl -X POST https://seu-dominio/api/v1/campaigns/CAMPAIGN_ID/tokens \
  -H "x-api-key: SUA_CHAVE" -H "Content-Type: application/json" \
  -d '{"maxUses":0,"expiresAt":null}'

POST /tokens/:id/revoke

Revoga um token imediatamente (qualquer clique nele passa a ver a página White/segura).

Estatísticas de bloqueio

GET /campaigns/:id/bot-stats?days=30

Contagem de acessos negados por motivo, nos últimos days dias (máx. 90).

Campo	Descrição
`totalDenied`	Total de acessos negados no período
`botRelatedTotal`	Subconjunto que representa bot/ataque de verdade (não config/billing)
`breakdown`	Array `{reason, count}`

Logs e alertas (somente leitura)

GET /logs?limit=100

Últimos acessos (liberados e negados) da conta, mais recentes primeiro. limit máx. 500.

GET /alerts

Últimos 200 alertas da conta (uso anômalo de token, tentativa de forjar campaign_id, quota perto do limite etc.).

Webhooks (Zapier, Make, ou seu próprio backend)

Cadastre um webhook em Painel → Webhooks (ou via automação com o "Webhook" do Make / "Webhooks by Zapier" da Zapier — ambos aceitam qualquer URL HTTPS que receba POST). Eventos disponíveis hoje:

Evento	Quando dispara
`access.denied`	Toda vez que um acesso é bloqueado (bot, quota, regra de cloaker etc.)
`alert.created`	Novo alerta (uso anômalo, tentativa de forja, quota perto do limite)

Corpo da requisição enviado ao seu endpoint:

{
  "event": "access.denied",
  "data": { "projectId": "...", "campaignId": "...", "reason": "bot_suspected", "ip": "...", "userAgent": "..." },
  "sentAt": "2026-07-07T12:00:00.000Z"
}

A requisição inclui o header X-Cloaker-Signature (HMAC-SHA256 do corpo bruto, usando o secret mostrado uma única vez na criação do webhook) e X-Cloaker-Event. Valide a assinatura antes de confiar no payload — qualquer um pode enviar um POST parecido pro seu endpoint.

Conversão (vendas)

O Cloaker sabe, por padrão, quem viu a oferta (acesso liberado) — mas não sabe quem comprou, porque a venda acontece na sua plataforma de checkout, fora do Cloaker. Esta seção liga as duas pontas: cada acesso liberado ganha um identificador de clique (click_id), embutido na URL da sua oferta; quando sua plataforma de venda avisar o Cloaker (via webhook) que aquele identificador converteu, a venda aparece no painel já ligada à campanha — e à variante, se a regra tiver teste A/B ativo.

Sem configurar o webhook do lado da sua plataforma de venda, nenhuma venda aparece aqui — é exatamente esse passo que esta seção explica. Conecte em Painel → Conversão (vendas).

Como o identificador de clique chega até você

O Cloaker anexa automaticamente sck=<identificador> (e também _cid=<identificador>, genérico) na URL da Black configurada na regra — não precisa fazer nada pra isso acontecer. O parâmetro sck foi escolhido porque a Hotmart, a Kiwify e a HubPay já reconhecem esse parâmetro nativamente e o devolvem no payload do webhook de venda, sem nenhuma configuração extra na URL de checkout. Se você já usa sck manualmente pra outra coisa nessa plataforma, o valor do Cloaker vai substituir o seu enquanto a conversão estiver conectada — some as duas coisas na mesma campanha com cuidado.

Hotmart

No painel da Hotmart: Ferramentas → Webhook (API e notificações) → Cadastrar Webhook.
Escolha o produto e os eventos (recomendado: compra aprovada, reembolsada, chargeback).
Cole a URL de webhook mostrada em Painel → Conversão (vendas) depois de conectar a Hotmart.
Copie o Hottok (token de validação, mostrado na mesma tela da Hotmart) e cole na tela de conexão do Cloaker.

O Cloaker lê origin.sck do payload da Hotmart como identificador de clique, e o evento (PURCHASE_APPROVED, PURCHASE_REFUNDED, PURCHASE_CHARGEBACK etc.) como status da venda.

HubPay

No painel da HubPay: Dashboard → Webhooks → Adicionar webhook.
Marque o evento "Transação aprovada".
Cole a URL de webhook mostrada em Painel → Conversão (vendas) depois de conectar a HubPay.
Copie o Secret gerado pela HubPay na hora de criar o webhook e cole na tela de conexão do Cloaker.

O Cloaker lê data.clickId do payload da HubPay como identificador de clique e event (purchase.completed) como status da venda.

Kiwify

No painel da Kiwify: Apps → Webhooks → Criar Webhook.
Escolha o produto e os eventos (recomendado: compra aprovada, reembolso, chargeback).
Cole a URL de webhook mostrada em Painel → Conversão (vendas) depois de conectar a Kiwify.
Copie o token do webhook (mostrado na Kiwify na hora de criar/editar o webhook) e cole na tela de conexão do Cloaker.

O Cloaker lê TrackingParameters.sck como identificador de clique, order_status como status da venda (paid → aprovada, refunded → reembolsada, chargedback → chargeback), e Commissions.charge_amount (em centavos) como valor.

Personalizada (Zapier, Make, sistema próprio)

Para qualquer plataforma sem integração nativa, use a URL "personalizada" — ela aceita um POST em JSON com este contrato:

POST /webhooks/conversions/custom/<webhookPath>
Content-Type: application/json
X-Cloaker-Webhook-Token: <token mostrado no painel>

{
  "clickId": "o valor do parâmetro sck ou _cid que chegou no seu checkout",
  "externalTransactionId": "id único da venda na sua plataforma (evita duplicar)",
  "ip": "IP do comprador no momento da compra (opcional, ver abaixo)",
  "status": "approved",
  "value": 97.00,
  "currency": "BRL"
}

Campo	Obrigatório	Descrição
`clickId`	Não*	Sem ele (e sem `ip`) a venda é registrada mas não é ligada a nenhuma campanha/variante
`externalTransactionId`	Sim	Identificador único da venda — usado pra não contar a mesma venda duas vezes
`ip`	Não	IP do comprador (não o da sua plataforma) — usado como reserva de atribuição quando o `clickId` não bate com nenhum acesso nosso (ex: alguma etapa do funil sobrescreveu o parâmetro). Cloaker procura o acesso liberado mais recente desse IP na sua conta, até 2h antes da venda. Não é infalível (IP compartilhado pode juntar visitantes diferentes) — quando usado, a venda aparece no painel marcada como "atribuição aproximada por IP", não como correspondência exata.
`status`	Não (padrão `approved`)	`approved`, `refunded`, `chargeback`, ou outro texto livre
`value` / `currency`	Não	Usados pra somar receita no painel

O token pode vir no header X-Cloaker-Webhook-Token, ou (se sua ferramenta não permitir headers customizados) em ?token= na URL ou "token" no corpo.

Proteção de origem (bloquear scraper direto no seu servidor)

O Cloaker protege o funil por redirecionamento: depois de validar o acesso, ele manda o navegador direto pra URL real do seu site. Isso significa que um scraper que descobrir essa URL — via curl, Python requests, Scrapy — pode ignorar o Cloaker inteiramente e bater direto no seu servidor de origem, sem passar pela validação. A única proteção que funciona de verdade contra isso é o próprio servidor de origem perguntar ao Cloaker, antes de servir qualquer página, se a sessão do visitante é válida.

Dois endpoints fazem essa pergunta, dependendo de como seu servidor de origem consegue integrar:

POST /api/validate-session

Sempre responde 200 com {"valid": true|false} — use quando seu servidor consegue ler o JSON da resposta (Node/Express, PHP, qualquer linguagem com HTTP client).

curl -X POST https://seu-dominio-cloaker/api/validate-session \
  -H "Content-Type: application/json" \
  -d '{"sessionCookie":""}'
# -> {"valid": true}  ou  {"valid": false}

POST /api/validate-session-status

Responde 204 (válido) ou 401 (inválido), sem corpo — pensado pra integrações de infraestrutura que decidem allow/deny pelo status HTTP, como o auth_request do Nginx.

Kits prontos por stack (middleware Node/Express, config Nginx via auth_request, mu-plugin WordPress/PHP, e o Edge Middleware da Vercel/Next.js) ficam em deploy/origin-protection-kits/ no repositório do projeto, com instalação passo a passo em cada pasta. Nenhum segredo novo precisa ser gerado — a validação usa a mesma sessão (cloak_session) que o Cloaker já cria no /go.

Erros

Erros sempre vêm como JSON {"error": "codigo_do_erro"}, com o status HTTP correspondente:

Status	Significado
400	Campo obrigatório faltando ou inválido
401	`missing_api_key` / `invalid_api_key`
404	Recurso não existe ou não pertence à sua conta
409	Conflito (ex: `domain_already_in_use`)
429	Rate limit excedido (60 req/min por conta)