Primeiros Passos

Documentação da API

A Shieldprint oferece uma API REST para geolocalização de IP, fingerprinting de navegador e detecção de fraude. Todas as respostas são em JSON.

Base URL

https://shieldprint.io/api/v1

Quickstart

Crie uma conta

Acesse /register e crie sua conta gratuita.

Gere uma API Key

No Dashboard, clique em "Nova API Key".

Faça sua primeira requisição

Use sua key no header X-API-Key ou no query param ?key=.

cURL

curl -H "X-API-Key: sk_live_sua_chave_aqui" \
  https://shieldprint.io/api/v1/ip/8.8.8.8

Segurança

Autenticação

Todas as requisições precisam de uma API Key válida. Você pode enviar de duas formas:

Recomendado

Header

Envie a chave no header HTTP.

X-API-Key: sk_live_sua_chave_aqui

Query Parameter

Envie como parâmetro na URL.

GET /api/v1/ip/8.8.8.8?key=sk_live_sua_chave_aqui

Nunca exponha sua API Key no frontend. Use-a apenas no backend/servidor.

Endpoint

IP Geolocation

Retorna dados completos de geolocalização de qualquer endereço IPv4 ou IPv6.

GET /api/v1/ip/{ip}

Parâmetros

Parâmetro	Tipo	Obrigatório	Descrição
`ip`	string	Sim	Endereço IP válido (IPv4 ou IPv6)

Exemplo de Requisição

cURL

curl -H "X-API-Key: sk_live_abc123" \
  https://shieldprint.io/api/v1/ip/8.8.8.8

Resposta

JSON 200 OK

{
  "ip": "8.8.8.8",
  "pais": "United States",
  "codigo_pais": "US",
  "regiao": "Virginia",
  "codigo_regiao": "VA",
  "cidade": "Ashburn",
  "cep": "20149",
  "latitude": 39.03,
  "longitude": -77.5,
  "timezone": "America/New_York",
  "isp": "Google LLC",
  "organizacao": "Google Public DNS",
  "as": "AS15169 Google LLC",
  "cache": false
}

Campos da Resposta

Campo	Tipo	Descrição
`ip`	string	IP consultado
`pais`	string	Nome do país
`codigo_pais`	string	Código ISO do país (BR, US...)
`regiao`	string	Estado/região
`cidade`	string	Cidade
`cep`	string	Código postal
`latitude`	number	Latitude
`longitude`	number	Longitude
`timezone`	string	Timezone IANA
`isp`	string	Provedor de internet
`organizacao`	string	Organização dona do IP
`as`	string	Autonomous System
`cache`	boolean	Se veio do cache (TTL: 5 min)

Endpoint

Identify (Fingerprint)

Identifica um visitante único a partir do fingerprint do navegador. Retorna um visitorId determinístico, dados de geolocalização e flags de risco.

POST /api/v1/identify

Body (JSON)

Campo	Tipo	Obrigatório	Descrição
`fingerprint.components`	object	Sim	Componentes do fingerprint
`ip`	string	Sim	IP do visitante (IPv4/IPv6)
`userAgent`	string	Sim	User-Agent do navegador

Exemplo de Requisição

cURL

curl -X POST https://shieldprint.io/api/v1/identify \
  -H "X-API-Key: sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "fingerprint": {
      "components": {
        "userAgent": "Mozilla/5.0...",
        "language": "pt-BR",
        "platform": "Linux x86_64",
        "screenResolution": "1920x1080",
        "timezone": "America/Sao_Paulo",
        "cookiesEnabled": true,
        "touchSupport": false
      }
    },
    "ip": "200.100.50.25",
    "userAgent": "Mozilla/5.0..."
  }'

Resposta

JSON 200 OK

{
  "requestId": "req_a1b2c3d4e5f6...",
  "visitorId": "fp_8a3b4c5d6e7f8901",
  "confidence": 0.95,
  "ip": {
    "address": "200.100.50.25",
    "location": {
      "pais": "Brazil",
      "codigo_pais": "BR",
      "regiao": "Sao Paulo",
      "cidade": "Sao Paulo",
      "latitude": -23.55,
      "longitude": -46.63,
      "timezone": "America/Sao_Paulo"
    },
    "isp": "Vivo"
  },
  "flags": {
    "isVpn": false,
    "isProxy": false,
    "isTor": false,
    "isBot": false
  },
  "riskScore": 0,
  "firstSeen": "2026-03-01T12:00:00.000Z",
  "lastSeen": "2026-03-03T15:30:00.000Z"
}

Campos da Resposta

Campo	Tipo	Descrição
`requestId`	string	ID único da requisição
`visitorId`	string	ID determinístico do visitante
`confidence`	number	Confiança da identificação (0.5–0.99)
`ip.location`	object	Dados de geolocalização
`flags.isVpn`	boolean	Detectou uso de VPN
`flags.isProxy`	boolean	Detectou uso de proxy
`flags.isTor`	boolean	Detectou rede Tor
`flags.isBot`	boolean	Detectou bot/crawler
`riskScore`	number	Score de risco (0–100)

Endpoint

Visitors

Consulta o histórico de um visitante já identificado.

GET /api/v1/visitors/{visitorId}

Exemplo de Requisição

cURL

curl -H "X-API-Key: sk_live_abc123" \
  https://shieldprint.io/api/v1/visitors/fp_8a3b4c5d6e7f8901

Resposta

JSON 200 OK

{
  "visitorId": "fp_8a3b4c5d6e7f8901",
  "visits": 12,
  "firstSeen": "2026-03-01T12:00:00.000Z",
  "lastSeen": "2026-03-03T15:30:00.000Z",
  "ips": ["200.100.50.25", "187.45.32.10"],
  "countries": ["BR"],
  "riskScore": 0,
  "recentVisits": [
    {
      "ip": "200.100.50.25",
      "userAgent": "Mozilla/5.0...",
      "createdAt": "2026-03-03T15:30:00.000Z"
    }
  ]
}

Campos da Resposta

Campo	Tipo	Descrição
`visitorId`	string	ID do visitante
`visits`	number	Total de visitas registradas
`ips`	string[]	Lista de IPs únicos usados
`countries`	string[]	Lista de países
`riskScore`	number	Score de risco atual
`recentVisits`	array	Últimas 20 visitas

Referência

Rate Limits

Cada requisição consome 1 token do seu plano mensal. Os headers de resposta indicam seu uso:

Header	Descrição
`X-RateLimit-Limit`	Limite total do plano
`X-RateLimit-Remaining`	Requisições restantes
`X-RateLimit-Used`	Requisições já usadas
`X-RateLimit-Reset`	Timestamp Unix de quando o contador reseta

Nota

O contador reseta automaticamente no primeiro dia de cada mês.

Referência

Códigos de Erro

Todas as respostas de erro seguem o formato:

{ "error": "Mensagem do erro", "code": 401 }

Código	Significado	Descrição
`400`	Bad Request	IP inválido ou body mal formatado
`401`	Unauthorized	API key ausente, inválida ou desativada
`404`	Not Found	Recurso não encontrado
`429`	Too Many Requests	Limite mensal atingido
`500`	Internal Error	Erro interno do servidor

Preços

Planos

Free

Grátis

100 requisições/mês
1 API Key
Geolocalização completa
Dashboard completo

Começar Grátis

Mais Popular

Starter

R$49/mês

5.000 requisições/mês
5 API Keys
Fingerprinting de visitantes
Detecção de VPN/Proxy/Tor
Cache inteligente
Logs de requisições
Suporte por email

Escolher Starter

Pro

R$99/mês

15.000 requisições/mês
API Keys ilimitadas
Risk Score por visitante
Detecção de bots/crawlers
Histórico completo de visitantes
Webhooks em tempo real
Métricas avançadas
Exportação CSV/JSON
Suporte prioritário

Escolher Pro

Nota

Todos os planos incluem acesso a todos os endpoints, dashboard e suporte.