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 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.

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)