API REST

Quickstart

1. Crie uma API key (1 minuto)
2. Envie POST pra /v1/check com a URL ou domínio
3. Receba score, verdict e red flags em JSON

curl -X POST https://www.naocaia.com.br/api/v1/check \
  -H "Authorization: Bearer naocaia_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "imagens-icloud.com", "type": "domain"}'

Autenticação

Toda chamada exige Authorization: Bearer <sua-key>. Keys têm o formato naocaia_sk_live_* e são armazenadas só em hash SHA-256 do nosso lado.

• Nunca commite a chave no seu repositório
• Use variável de ambiente no servidor
• Revogue imediatamente em caso de vazamento (dashboard → API Keys → Revogar)
• Crie chaves separadas por ambiente (dev/staging/prod)

POST /v1/check

Verifica uma URL, domínio, marca, @ do Instagram ou CNPJ. Retorna análise completa.

Body

Resposta 200

{
  "request_id": "a1b2c3d4-...",
  "query": "imagens-icloud.com",
  "type": "domain",
  "score": 5,
  "verdict": "POSSIVEL_GOLPE",
  "summary": "Domínio imita iCloud da Apple. Não é oficial.",
  "confidence": "ALTA",
  "red_flags": [
    {
      "title": "Imitação de marca conhecida",
      "description": "...",
      "severity": "HIGH"
    }
  ],
  "positive_points": [],
  "claim_analysis": [],
  "data_quality": "COMPLETA",
  "disclaimer": "Análise informativa, não oficial.",
  "analyzed_at": "2026-06-28T15:43:01Z"
}

Verdicts possíveis

• CONFIAVEL (score 70-100) — empresa real, sem sinais críticos
• SUSPEITO (score 40-69) — dados insuficientes ou ambíguos
• PROVAVEL_GOLPE (score 20-39) — vários sinais de fraude
• POSSIVEL_GOLPE (score 0-19) — golpe confirmado ou padrão phishing

POST /v1/pix-key

Verifica reputação de uma chave PIX (CPF/CNPJ/email/telefone/aleatória) antes da transação. Útil pra fintechs, PSPs, e wallets que querem checar o beneficiário antes de liberar o pagamento. Consome 1 quota igual ao /v1/check.

Privacy LGPD: a chave NÃO é armazenada em texto — apenas hash SHA256. O preview no response é sempre mascarado.

curl https://www.naocaia.com.br/api/v1/pix-key \
  -H "Authorization: Bearer naocaia_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"key": "47960950000121"}'

Tipos de chave aceitos

• cpf — 11 dígitos com dígitos verificadores válidos
• cnpj — 14 dígitos, valida dígitos verificadores, enriquece com ReceitaWS
• email — formato RFC 5322 básico
• phone — +55 com DDD (10-11 dígitos após código de país)
• random — UUID v4 (chave aleatória PIX)

Resposta 200

{
  "request_id": "86ea1469-4536-4248-887d-d55cc6e9060b",
  "key_type": "cnpj",
  "key_preview": "47.***.***/0001-21",
  "score": 80,
  "verdict": "SUSPEITO",
  "confidence": "BAIXA",
  "summary": "Essa chave PIX não tem histórico negativo na nossa base. Vinculada ao CNPJ 47.960.950/0001-21 (MAGAZINE LUIZA S/A)...",
  "red_flags": [],
  "positive_points": [
    {
      "title": "CNPJ ativo",
      "description": "CNPJ 47.960.950/0001-21 pertence a \"MAGAZINE LUIZA S/A\" e está ATIVO na Receita Federal."
    }
  ],
  "reputation": {
    "times_queried_24h": 0,
    "times_queried_total": 0,
    "times_reported_scam": 0,
    "distinct_reporters": 0,
    "days_known": 0,
    "is_new_key": true,
    "first_seen_at": null
  },
  "identity": {
    "cnpj": {
      "cnpj": "47.960.950/0001-21",
      "razao_social": "MAGAZINE LUIZA S/A",
      "situacao": "ATIVA",
      "idade_descricao": "Empresa aberta em 24/10/1966, tem 60 anos e 6 meses de existencia"
    },
    "phone": null,
    "email": null
  }
}

Sinais analisados

• Reputação crowdsourced — quantas vezes a chave foi consultada nas últimas 24h/7d/total + quantas vezes foi reportada como golpe por usuários diferentes
• Idade da chave — first_seen_at + flag is_new_key (true se < 30 dias)
• Identidade — pra CNPJ, full lookup ReceitaWS com situação cadastral
• Vínculos com domínios golpe — chaves vistas junto com URLs já flagadas

Thresholds de verdict

POST /v1/resolve

Quando você tem só um nome cru de empresa (ex: do CRM, do e-mail do prospect) e quer descobrir qual domínio analisar antes de gastar uma chamada do /v1/check. Retorna lista de candidatos com IDs descartáveis que valem por 30 min.

Não consome quota mensal. Rate-limit separado: 60 req/min por chave (independente do plano).

curl https://www.naocaia.com.br/api/v1/resolve \
  -H "Authorization: Bearer naocaia_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "projetoal"}'

Resposta 200

{
  "query": "projetoal",
  "status": "ambiguous",
  "candidates": [
    {
      "candidate_id": "cand_a1b2c3d4e5f6",
      "kind": "domain",
      "title": "Página inicial - ProjetoAlumínio®",
      "domain": "projetoaluminio.com.br",
      "instagram_handle": null,
      "snippet": "Fabricante de ACM...",
      "category": null
    },
    {
      "candidate_id": "cand_x9y8z7w6v5u4",
      "kind": "domain",
      "title": "PROJETOAL",
      "domain": "afeal.com.br",
      "instagram_handle": null,
      "snippet": "Possui uma operação completa...",
      "category": "Pet"
    }
  ]
}

Status possíveis

• unique — só 1 candidato. Pode mandar pro /check sem perguntar nada ao usuário.
• ambiguous — 2 ou mais. Apresente as opções pro decisor final escolher.
• not_found — 0 candidatos. Peça outro termo.

Como usar o candidate_id no /check

Passe candidate_id em vez de query:

curl https://www.naocaia.com.br/api/v1/check \
  -H "Authorization: Bearer naocaia_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"candidate_id": "cand_a1b2c3d4e5f6"}'

Cada candidate_id vale por 30 minutos e é vinculado à conta que fez o resolve — não dá pra reutilizar entre contas. Depois desse TTL, refaça o /v1/resolve.

GET /v1/account

Retorna o plano atual, status, uso (chamadas/quota) e detalhes da assinatura (data de início, vencimento, dias restantes). Útil pra você renderizar painéis e antecipar renovações.

curl https://www.naocaia.com.br/api/v1/account \
  -H "Authorization: Bearer naocaia_sk_live_..."

Resposta 200

{
  "plan": {
    "id": "pro",
    "name": "Pro",
    "monthly_quota": 100,
    "lifetime_quota": null,
    "rate_limit_per_min": 10,
    "max_keys": 1
  },
  "status": "active",
  "quota_mode": "monthly",
  "usage": {
    "total_calls": 42,
    "remaining_calls": 58,
    "quota_cap": 100,
    "used_percent": 42
  },
  "subscription": {
    "started_at": "2026-06-28T20:31:12Z",
    "expires_at": "2026-07-28T20:31:12Z",
    "signed_up_at": "2026-06-28T20:31:00Z",
    "days_in_period": 30,
    "days_elapsed": 7,
    "days_remaining": 23,
    "is_expired": false,
    "cancel_at_period_end": false
  }
}

Campos da resposta

• plan — plano vigente (trial/pro/business) com quota e limite
• status — active / canceled / past_due / trialing
• quota_mode — lifetime (trial) ou monthly (pago)
• usage.remaining_calls — quanto ainda dá pra usar
• subscription.expires_at — quando vence (ISO 8601 UTC)
• subscription.days_remaining — dias até vencer
• subscription.signed_up_at — primeira assinatura (criação da linha)
• subscription.is_expired — true se o vencimento já passou

Códigos de erro (RFC 9457)

Erros seguem o padrão application/problem+json.

Rate limits

Cada resposta inclui os headers:

• X-RateLimit-Limit: requests permitidas por minuto
• X-RateLimit-Remaining: quantas sobram nesta janela
• X-RateLimit-Reset: timestamp Unix do próximo reset

Quando atingir 429, leia Retry-After (segundos) e dê backoff exponencial.

Idempotência

Use o header Idempotency-Key: <sua-chave> para garantir que retries não geram análises duplicadas.

• Cache 24h da resposta original
• Replay do mesmo body retorna 200 idempotente com header Idempotent-Replayed: true
• Reuso da mesma key com body diferente → 409 Conflict
• Formato aceito: 8-255 chars, letras/números/hífen/underscore

Changelog

• v1.3 — 2026-06-29

  Novo endpoint POST /v1/pix-key — verificação de reputação de chave PIX (CPF/CNPJ/email/telefone/aleatória) com base em reputação crowdsourced, identidade vinculada e vínculos com domínios já flagados. Privacy: chave nunca armazenada em texto, só hash SHA256. Consome 1 quota igual /v1/check.

• v1.2 — 2026-06-29

  Pipeline /v1/check ganha 4 novas fontes externas: CEPIM (Portal da Transparência — empresas impedidas de receber recursos federais, adicionado às sanções CEIS/CNEP existentes), PhishTank (base global de URLs de phishing verificadas pela comunidade), URLhaus (abuse.ch — feed de malware C2 e URLs maliciosas), OpenPhish (feed comunitário grátis sincronizado diariamente para Redis) e Certificate Transparency (crt.sh) — quando o primeiro SSL do domínio é mais novo que 14 dias o score recebe penalidade. Todos rodam em paralelo, com timeout independente; falha em qualquer um deles NÃO quebra o orchestrator.

• v1.1 — 2026-06-28

  Novo endpoint GET /v1/account (plano + uso + dias da assinatura). Recibos de pagamento em PDF/print no painel. Expiração de assinatura no fim do ciclo + bloqueio na auth.

• v1.0 — 2026-06-28

  Lançamento público. Endpoint POST /v1/check, planos Trial (3 consultas vitalícias), Pro (100/mês) e Business (1.000/mês). Idempotência, rate limit, problem+json errors.