Watch-IP

Referência da API de Deteção de Viagem Impossível

POST/v1/risk/check

Compara a localização resolvida de um IP fornecido com uma base de referência armazenada por utilizador, e classifica a velocidade de viagem implícita. Um sinal em bruto para o seu próprio processo de deteção de fraude, não um veredito final — contacte-nos para confirmar a disponibilidade antes de integrar; a aplicação independente de um plano de risco e a preparação do checkout ainda não foram verificadas.

Autenticação

Forneça uma chave secreta através de Authorization: Bearer YOUR_SECRET_KEY, o mesmo tipo de chave dos endpoints de pesquisa. Envie um corpo JSON com userId, ip, e um booleano commit opcional (predefinição true; defina como false para uma verificação especulativa que não deva alterar a base de referência armazenada).

Campos de resposta

risk
low, medium, ou high.
impossibleTravel
Forma abreviada booleana para saber se a velocidade implícita entre a localização anterior e a atual excede uma velocidade de viagem plausível.
distanceKm, impliedSpeedKmh, elapsedSeconds
A distância e o tempo entre a observação anterior e a atual, e a velocidade que isso implica. Nulo na primeira verificação de sempre de um utilizador, quando não há localização anterior com que comparar.
previousLocation
country, latitude, longitude, e observedAt para a base de referência armazenada antes desta chamada. Nulo quando esta é a primeira verificação de sempre para este userId.
currentLocation
country, latitude, e longitude resolvidos a partir do ip que forneceu nesta chamada.

Erros

400
Endereço IP mal formado ou userId em falta.
401
Chave de API em falta ou inválida.
403
Foi utilizada uma chave publicável em vez de uma chave secreta.
422
O IP fornecido não pôde ser resolvido para uma localização.
429
Limite de taxa excedido para a janela de um minuto atual.

Exemplo

Pedido

curl https://api.watch-ip.com/v1/risk/check \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"userId": "u_123", "ip": "203.0.113.1"}'

Resposta

{
  "risk": "high",
  "impossibleTravel": true,
  "distanceKm": 8843.2,
  "impliedSpeedKmh": 4421.6,
  "elapsedSeconds": 7200,
  "previousLocation": { "country": "FR", "latitude": 48.8566, "longitude": 2.3522, "observedAt": "2026-09-06T12:00:00.000Z" },
  "currentLocation": { "country": "US", "latitude": 30.2672, "longitude": -97.7431 }
}

Limites

A v1 armazena apenas a localização mais recente por utilizador, não uma janela de histórico — espere falsos positivos causados pela alternância rápida de VPN ou pela rotação de IP em redes móveis, uma vez que ainda não existe supressão consciente de VPN/centro de dados. Trate o resultado como um sinal em bruto, não como um veredito final. Uma vez que este endpoint armazena uma localização associada a userId para além de um único ciclo de pedido/resposta, utilizá-lo torna o Watch-IP um subcontratante (processor) desses dados em seu nome — consulte o Anexo de Tratamento de Dados.

Páginas relacionadas