Compare a localização de um início de sessão com a localização anteriormente armazenada

Uma grande alteração na localização derivada do IP num curto intervalo pode justificar revisão. POST /v1/risk/check compara a estimativa de localização atual de um utilizador com o ponto anteriormente armazenado e devolve a distância, o tempo decorrido, a velocidade implícita e uma classificação de risco — contacte-nos para confirmar a disponibilidade antes de integrar, uma vez que a aplicação independente de um plano de risco e a preparação do checkout ainda não foram verificadas.

Discutir o acesso à verificação de risco Ler a referência de verificação de risco →

Disponibilidade

Este endpoint partilha o mesmo middleware de chave secreta que a pesquisa de IP, que verifica apenas se uma chave é uma chave secreta — não aplica de forma independente uma família de planos de risco separada, e o preço de risco pré-configurado não tem um preço ativo definido. Confirme connosco os termos e a disponibilidade atuais antes de depender disto em produção.

Entrada e utilização da chave secreta

Envie um corpo JSON com userId, ip, e um booleano commit opcional (predefinição true) para POST /v1/risk/check com uma chave secreta através de Authorization: Bearer YOUR_SECRET_KEY — apenas servidor-a-servidor, nunca a partir de um navegador.

A primeira observação

A primeira verificação de sempre de um utilizador não tem localização anterior com que comparar: devolve risk: "low", impossibleTravel: false, valores nulos de distância/velocidade/tempo decorrido, e um previousLocation nulo, e — se commit não for false — armazena esta observação como a nova base de referência.

Observações subsequentes

As verificações posteriores comparam a distância em grande círculo entre o ponto anterior e o atual com o tempo decorrido, para obter uma velocidade implícita. Abaixo de 500 km/h, o resultado é "low"; entre 500 e 900 km/h, "medium" (um voo de longo curso real pode aterrar perto deste limite); acima de 900 km/h, "high" e impossibleTravel: true.

O sinalizador commit

commit é true por predefinição. Defina-o como false para uma pré-verificação especulativa — por exemplo, antes de uma decisão de autenticação reforçada — que lê a base de referência armazenada sem a alterar, para que uma verificação legítima não corrompa o histórico real de localização do utilizador.

Localizações em falta

Se ip não puder ser resolvido para uma latitude/longitude, o endpoint devolve um 422 em vez de uma estimativa de baixa confiança.

Retenção e eliminação

A v1 armazena exatamente uma localização por par (a sua conta, userId) — a observação confirmada mais recente — sem expiração automática e sem um endpoint de eliminação atualmente disponível; persiste até à próxima verificação confirmada a sobrepor. Uma vez que armazena uma localização associada a userId para além de um único ciclo de pedido/resposta, a utilização deste endpoint torna o Watch-IP um subcontratante (processor) desses dados em seu nome — consulte o Anexo de Tratamento de Dados.

Falsos positivos

A v1 não tem supressão consciente de VPN ou centro de dados, pelo que a alternância rápida de VPN ou a rotação comum de IP de rede móvel podem produzir um resultado elevado. Trate cada classificação como um sinal em bruto para o seu próprio processo de revisão, não como um veredito final.

Campos de resposta

risk: low, medium, ou high, a partir dos limiares de velocidade implícita acima.
impossibleTravel: Forma abreviada booleana para risk: "high".
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.
previousLocation: country, latitude, longitude, e observedAt para a base de referência armazenada antes desta chamada. Nulo na primeira verificação de sempre de um utilizador.
currentLocation: country, latitude, e longitude resolvidos a partir do ip que forneceu nesta chamada.

Pré-verifique, depois confirme

cURL no back-end

# Verificação especulativa antes da sua própria decisão de autenticação — não altera a base de referência.
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}'

# Depois de a sua própria verificação de palavra-passe/2FA ser bem-sucedida, confirme a nova base de referência.
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 é true por predefinição, pelo que a segunda chamada acima atualiza a base de referência armazenada; a primeira, com commit: false, não o faz.

Perguntas frequentes

O que acontece na primeira verificação?

Devolve sempre risk: "low" com um previousLocation nulo — ainda não há nada com que comparar a localização atual.

Suprime saltos de VPN?

Não. A v1 não tem supressão consciente de VPN ou centro de dados, pelo que mudar de rede ou de saídas VPN entre inícios de sessão pode, por si só, produzir um resultado médio ou alto.

Um resultado alto é prova de comprometimento?

Não. É um cálculo em bruto de distância sobre tempo. Combine-o com as suas próprias evidências de autenticação, em vez de o tratar como um veredito autónomo.

Posso evitar atualizar a base de referência?

Sim — passe commit: false. A verificação continua a ser executada e devolve um resultado, mas a localização armazenada não é substituída.

Durante quanto tempo é retida a localização anterior?

Indefinidamente, até à próxima verificação confirmada para esse userId a sobrepor — não existe expiração automática nem endpoint de eliminação na implementação atual.