Watch-IP

Riferimento API di rilevamento spostamento impossibile

POST/v1/risk/check

Confronta la posizione risolta di un IP fornito con una baseline memorizzata per utente e classifica la velocità di spostamento implicita. Un segnale grezzo per il tuo flusso antifrode, non un verdetto definitivo — contattaci per confermare la disponibilità prima di integrare; l'applicazione indipendente di un piano di rischio e la prontezza del checkout non sono state verificate.

Autenticazione

Fornisci una chiave segreta tramite Authorization: Bearer YOUR_SECRET_KEY, lo stesso tipo di chiave degli endpoint di ricerca. Invia un corpo JSON con userId, ip, e un booleano opzionale commit (predefinito true; imposta false per un controllo speculativo che non deve modificare la baseline memorizzata).

Campi della risposta

risk
low, medium o high.
impossibleTravel
Scorciatoia booleana per indicare se la velocità implicita tra la posizione precedente e quella attuale supera una velocità di spostamento plausibile.
distanceKm, impliedSpeedKmh, elapsedSeconds
La distanza e il tempo tra l'osservazione precedente e quella attuale, e la velocità che ne deriva. Null al primo controllo di un utente, quando non esiste una posizione precedente con cui confrontare.
previousLocation
country, latitude, longitude e observedAt per la baseline memorizzata prima di questa chiamata. Null quando questo è il primo controllo per questo userId.
currentLocation
country, latitude e longitude per l'ip fornito in questa chiamata.

Errori

400
Indirizzo IP malformato o userId mancante.
401
Chiave API mancante o non valida.
403
È stata usata una chiave pubblicabile invece di una chiave segreta.
422
L'IP fornito non ha potuto essere risolto in una posizione.
429
Limite di frequenza superato per l'attuale finestra di un minuto.

Esempio

Richiesta

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"}'

Risposta

{
  "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 }
}

Limiti

La v1 memorizza solo la posizione più recente per utente, non una finestra storica — aspettati falsi positivi da un rapido cambio di VPN o dal turnover di IP delle reti mobili, poiché non esiste ancora una soppressione consapevole di VPN/datacenter. Tratta il risultato come un segnale grezzo, non come un verdetto definitivo. Poiché questo endpoint memorizza una posizione collegata a un userId oltre il singolo ciclo di richiesta/risposta, usarlo rende Watch-IP un responsabile del trattamento di tali dati per tuo conto — consulta l'Addendum sul Trattamento dei Dati.

Pagine correlate