Watch-IP

Referencia de la API de detección de viaje imposible

POST/v1/risk/check

Compara la ubicación resuelta de una IP proporcionada contra una línea base almacenada por usuario y clasifica la velocidad de desplazamiento implícita. Es una señal en bruto para tu propio flujo de trabajo antifraude, no un veredicto final; contáctanos para confirmar la disponibilidad antes de integrarlo: la aplicación independiente del plan de riesgo y la disponibilidad del checkout no se han verificado.

Autenticación

Proporciona una clave secreta mediante Authorization: Bearer YOUR_SECRET_KEY, el mismo tipo de clave que los endpoints de lookup. Envía un cuerpo JSON con userId, ip y un booleano opcional commit (por defecto true; configúralo como false para una comprobación especulativa que no deba modificar la línea base almacenada).

Campos de la respuesta

risk
low, medium o high.
impossibleTravel
Atajo booleano que indica si la velocidad implícita entre la ubicación anterior y la actual supera una velocidad de desplazamiento plausible.
distanceKm, impliedSpeedKmh, elapsedSeconds
La distancia y el tiempo entre la observación anterior y la actual, y la velocidad que eso implica. Es null en la primera comprobación de un usuario, cuando no hay ninguna ubicación anterior con la cual comparar.
previousLocation
country, latitude, longitude y observedAt de la línea base almacenada antes de esta llamada. Es null cuando esta es la primera comprobación para este userId.
currentLocation
country, latitude y longitude para la ip que proporcionaste en esta llamada.

Errores

400
Dirección IP malformada o userId faltante.
401
Clave de API faltante o no válida.
403
Se usó una clave publicable en lugar de una clave secreta.
422
La IP proporcionada no se pudo resolver a una ubicación.
429
Límite de tasa superado para la ventana de un minuto actual.

Ejemplo

Solicitud

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

Respuesta

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

Límites

v1 almacena solo la ubicación más reciente por usuario, no una ventana de historial, así que espera falsos positivos por cambios rápidos de VPN o por el churn de IP de redes móviles, ya que todavía no hay ninguna supresión consciente de VPN/centro de datos. Trata el resultado como una señal en bruto, no como un veredicto final. Como este endpoint almacena una ubicación vinculada a un userId más allá de un único ciclo de solicitud/respuesta, usarlo hace que Watch-IP sea un encargado del tratamiento de esos datos en tu nombre; consulta el Anexo de Tratamiento de Datos.

Páginas relacionadas