Referência da API

API antifraude

Um SDK de navegador para identificação, webhooks assinados para eventos em tempo real e uma Server API somente leitura para o histórico. Tudo o que você precisa para impedir fraudes no nível do dispositivo.

Obter chave de API API Playground

Endpoints

SDK@tracio/sdk

Identifique um visitante no navegador com o SDK de cliente. Retorna um visitor ID estável e um veredito de bot sem ida e volta ao servidor. A chave pública pode ser embarcada com segurança no código do lado do cliente.

Requisição

import { Tracio } from '@tracio/sdk'
const tracio = Tracio.init({ publicKey: '5ca175fc...' })
const result = await tracio.getResult()

Resposta

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "bot": {
    "detected": false,
    "confidence": 2,
    "reasons": []
  }
}

POST/webhook/tracio

A TRACIO entrega um evento assinado ao seu endpoint a cada identificação. Verifique o cabeçalho X-Tracio-Signature e, em seguida, aja sobre o payload JSON plano. Esta é a superfície de push: você não precisa fazer polling. Se precisar mesmo ler uma visita depois do fato, a Server API responde por requestId.

Requisição

POST /webhook/tracio HTTP/1.1
Host: your-server.com
Content-Type: application/json
X-Tracio-Payload-Version: 2
X-Tracio-Event-Type: identification
X-Tracio-Signature: t=1710432000,v1=5257a869e7ecebed...

Resposta

{
  "version": 2,
  "event": "identification",
  "eventId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9:primary",
  "requestId": "9c1f4b2e-7d3a-4f18-8b6c-2e5a71d0c4f9",
  "phase": "primary",
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "timestamp": "2026-03-12T16:00:00Z",
  "bot": { "result": "human", "score": 2 },
  "identification": { "confidence": 0.95, "incognito": false },
  "network": { "vpn": false, "proxy": false, "tor": false, "datacenter": false },
  "decision": { "action": "real", "riskScore": 4 }
}

GET/.well-known/webhook-keys

Busque as chaves públicas Ed25519 da plataforma usadas para verificar as entregas de webhook. Esta rota não exige autenticação e fica em cache por cinco minutos. O kid no cabeçalho de assinatura indica qual chave usar.

Requisição

curl https://api.tracio.ai/.well-known/webhook-keys

Resposta

{
  "keys": [
    {
      "kid": "k1",
      "alg": "Ed25519",
      "publicKey": "MCowBQYDK2VwAyEA9tR2v1kQ..."
    }
  ]
}

GET/v1/visitors/{visitorId}

Leia o histórico de um visitante pela Server API com sua chave secreta. Disponível a partir do plano Pro. A janela é limitada ao seu plano, e a janela que você realmente obteve é informada em meta. Dá suporte a solicitações de direito de acesso do GDPR.

Requisição

# Server API — available on the Pro plan and above
curl "https://api.tracio.ai/v1/visitors/X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y" \
  -H "Authorization: Bearer tracio_sk_XXXX...XXXX"

Resposta

{
  "visitorId": "X7fh2Hg9LkMn3pQr5tBvQw3xZa9mK2pL4nR8dT6y",
  "firstSeenAt": "2026-03-01T08:11:00Z",
  "lastSeenAt": "2026-03-16T14:22:01Z",
  "visits": 12,
  "incognitoVisits": 1,
  "uniqueIps": 4,
  "uniqueCountries": 2,
  "risk": { "maxRiskScore": 63, "lastDecision": "real" },
  "network": {
    "vpnSeen": false,
    "proxySeen": false,
    "torSeen": false,
    "datacenterSeen": true
  },
  "meta": {
    "plan": "pro",
    "retentionDays": 30,
    "from": "2026-02-14T00:00:00Z",
    "to": "2026-03-16T14:30:00Z"
  }
}

Autenticação

A TRACIO usa três credenciais, uma por superfície: uma chave pública para o SDK de navegador, uma chave secreta (tracio_sk_…) enviada como Authorization: Bearer para a Server API e um segredo de assinatura HMAC para verificar as entregas de webhook. A chave secreta é criada no painel, exibida uma única vez e nunca deve chegar a um navegador — a Server API deliberadamente não retorna cabeçalhos CORS.

# Client SDK — public key (safe to ship in the browser)
Tracio.init({ publicKey: '5ca175fc...' })
# Server API — secret key, created in the dashboard and shown once
Authorization: Bearer tracio_sk_XXXX...XXXX
# Webhook verification — HMAC-SHA256 over "<t>.<rawBody>"
X-Tracio-Signature: t=<unix>,v1=<hmac_sha256_hex>

Limites de requisições

Os limites são por workspace. As chamadas à Server API são contadas separadamente das identificações, então ler o seu próprio histórico nunca gasta a cota que você paga. Toda resposta traz X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset, além de Retry-After em um 429. A Server API não faz parte do plano Free.

Plano	Taxa da Server API	Server API por dia	Endpoints de webhook	Janela de consulta
Grátis	Não incluído	Não incluído	0	7 days
Pro	10 req/s	10,000	5	30 days
Business	50 req/s	100,000	20	90 days
Enterprise	200 req/s	Ilimitado	100	365 days

Códigos de erro

Todo erro retorna o mesmo envelope: um objeto error com um code em string, uma message legível e o requestId da chamada que falhou.

400Bad RequestParâmetros de consulta malformados, uma janela não suportada ou um identificador que não é um visitor ID válido.

401UnauthorizedCredenciais ausentes ou inválidas — chave pública (SDK), chave secreta (Server API) ou assinatura de webhook.

402Upgrade RequiredSeu plano não inclui acesso à Server API. Ele começa no plano Pro.

404Not FoundNenhum visitante ou sessão com esse identificador dentro da janela de consulta do seu plano.

405Method Not AllowedA Server API é somente leitura. Toda rota responde GET e nada mais.

429Rate LimitedRequisições em excesso por segundo, ou a cota diária foi consumida. Verifique o cabeçalho Retry-After e os limites do seu plano.

500Internal ErrorErro no servidor. Tente novamente com backoff exponencial. Se persistir, entre em contato com o suporte informando o requestId.

503Service UnavailableA API está temporariamente sem condições de responder. Tente novamente com backoff exponencial.

Formato da resposta de erro

{
  "error": {
    "code": "rate_limited",
    "message": "too many requests",
    "requestId": "8f14e45fceea167a5a36dedd"
  }
}

Comece a construir

Obtenha sua chave de API e faça sua primeira requisição de identificação em menos de 5 minutos.

Obter chave de API Documentação completa da API