Compara la ubicación de un inicio de sesión con la ubicación anterior almacenada

Un cambio grande en la ubicación derivada de la IP en un intervalo corto puede justificar una revisión. POST /v1/risk/check compara la estimación de ubicación actual de un usuario con el punto anterior almacenado y devuelve distancia, tiempo transcurrido, velocidad implícita y una clasificación de riesgo — contáctanos para confirmar la disponibilidad antes de integrarlo, ya que la aplicación independiente de un plan de riesgo y la preparación del checkout no han sido verificadas.

Conversa sobre el acceso a la verificación de riesgo Lee la referencia de verificación de riesgo →

Disponibilidad

Este endpoint comparte el mismo middleware de clave secreta que la búsqueda de IP, el cual verifica que una clave sea una clave secreta — no aplica de forma independiente una familia de planes de riesgo separada, y el precio de riesgo sembrado no tiene un precio activo configurado. Confirma los términos y la disponibilidad actuales con nosotros antes de depender de esto en producción.

Entrada y uso de la clave secreta

Envía un cuerpo JSON con userId, ip y un booleano opcional commit (por defecto true) a POST /v1/risk/check con una clave secreta mediante Authorization: Bearer YOUR_SECRET_KEY — exclusivamente de servidor a servidor, nunca desde un navegador.

La primera observación

La primera verificación de un usuario no tiene una ubicación anterior con la cual comparar: devuelve risk: "low", impossibleTravel: false, valores nulos de distancia/velocidad/tiempo transcurrido, y un previousLocation nulo, y — si commit no es false — almacena esta observación como la nueva línea base.

Observaciones posteriores

Las verificaciones posteriores comparan la distancia de círculo máximo entre el punto anterior y el actual contra el tiempo transcurrido para obtener una velocidad implícita. Por debajo de 500 km/h, el resultado es "low"; entre 500 y 900 km/h, "medium" (un vuelo de larga distancia real puede aterrizar cerca de este límite); por encima de 900 km/h, "high" e impossibleTravel: true.

La marca commit

commit tiene como valor predeterminado true. Establécelo en false para una verificación previa especulativa — por ejemplo, antes de una decisión de autenticación reforzada — que lee la línea base almacenada sin modificarla, para que una verificación legítima no corrompa el historial real de ubicaciones del usuario.

Ubicaciones faltantes

Si ip no se puede resolver a una latitud/longitud, el endpoint devuelve un 422 en lugar de una suposición de baja confianza.

Retención y eliminación

v1 almacena exactamente una ubicación por cada par (tu cuenta, userId) — la observación confirmada más reciente — sin expiración automática y sin un endpoint de eliminación disponible actualmente; persiste hasta que la siguiente verificación confirmada la sobrescriba. Debido a que almacena una ubicación vinculada a un userId más allá de un solo ciclo de solicitud/respuesta, el uso de este endpoint convierte a Watch-IP en un encargado del tratamiento de esos datos por cuenta tuya — consulta el Anexo de Tratamiento de Datos (DPA).

Falsos positivos

v1 no tiene supresión consciente de VPN o centro de datos, así que el cambio rápido de VPN o el cambio habitual de IP en redes móviles pueden producir un resultado elevado. Trata cada clasificación como una señal en bruto para tu propio proceso de revisión, no como un veredicto final.

Campos de respuesta

risk: low, medium o high, según los umbrales de velocidad implícita anteriores.
impossibleTravel: Abreviatura booleana de risk: "high".
distanceKm, impliedSpeedKmh, elapsedSeconds: La distancia y el tiempo entre la observación anterior y la actual, y la velocidad que eso implica. Nulo en la primera verificación de un usuario.
previousLocation: country, latitude, longitude y observedAt para la línea base almacenada antes de esta llamada. Nulo en la primera verificación de un usuario.
currentLocation: country, latitude y longitude resueltos a partir de la ip que proporcionaste en esta llamada.

Verifica primero, luego confirma

cURL de backend

# Verificación especulativa antes de tu propia decisión de autenticación — no modifica la línea base.
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", "commit": false}'

# Una vez que tu propia verificación de contraseña/2FA sea exitosa, confirma la nueva línea base.
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"}'

commit tiene como valor predeterminado true, así que la segunda llamada anterior actualiza la línea base almacenada; la primera, con commit: false, no lo hace.

Preguntas frecuentes

¿Qué sucede en la primera verificación?

Siempre devuelve risk: "low" con un previousLocation nulo — todavía no hay nada con qué comparar la ubicación actual.

¿Suprime los saltos de VPN?

No. v1 no tiene supresión consciente de VPN o centro de datos, así que cambiar de red o de salida de VPN entre inicios de sesión puede producir por sí solo un resultado medium o high.

¿Es un resultado high prueba de compromiso?

No. Es un cálculo bruto de distancia sobre tiempo. Combínalo con tu propia evidencia de autenticación en lugar de tratarlo como un veredicto independiente.

¿Puedo evitar actualizar la línea base?

Sí — pasa commit: false. La verificación se sigue ejecutando y devuelve un resultado, pero la ubicación almacenada no se reemplaza.

¿Por cuánto tiempo se retiene la ubicación anterior?

Indefinidamente, hasta que la siguiente verificación confirmada para ese userId la sobrescriba — no hay expiración automática ni un endpoint de eliminación en la implementación actual.