Verificación de ubicación API: geofencing y distancia IP

La Verificación de ubicación de Didit confirma dónde se encuentra una persona mientras se verifica. Para ello lee una vez la posición del dispositivo (navegador o SDK nativo) o la ubicación IP de la conexión, y la compara con las zonas permitidas y bloqueadas, con la ubicación IP y con la dirección que figura en sus documentos. En los flujos de verificación (workflows) y en la API es la función GEOLOCATION, su configuración son las claves geolocation_* y su resultado es geolocation_checks[] en la decisión de la sesión.

​

Cuándo usarla

• Tienes licencia solo en algunas jurisdicciones (juego, intermediación bursátil, préstamos) y debes demostrar que la persona estaba dentro de una de ellas cuando presentó su solicitud.
• Debes impedir el acceso desde lugares bloqueados, como una región sancionada o un estado en el que no prestas servicio.
• Quieres una señal de fraude adicional: una posición del dispositivo lejana a la ubicación IP o a la dirección del documento de identidad, una posición simulada, una VPN o un emulador.
• No necesitas los desplazamientos ni el historial de la persona, solo una lectura tomada durante la sesión.

​

Cómo funciona

​

Fuentes de la posición

Eliges de dónde procede la posición con geolocation_position_source. En un nodo que consulta al dispositivo, un intento sin posición se evalúa como lo que es, una denegación o un fallo: la ubicación IP nunca la sustituye.

​

Valores predeterminados y límites de configuración

Todas las claves son opcionales. La lista completa está en la referencia de configuración de funciones del flujo.

​

Ajustes predefinidos

geolocation_preset define el valor predeterminado de cada acción que no configures. licensing rechaza una posición fuera de las zonas permitidas, dentro de una zona bloqueada, a través de una VPN o de la red Tor, o en un emulador, y envía a revisión los casos que usan un proxy. fraud_screening aplica los mismos criterios, pero envía a revisión todo lo que licensing rechazaría. Una acción que configures explícitamente siempre prevalece.

​

Geocercas

Activa is_geolocation_geofencing_enabled y define la lista geolocation_areas. Una zona puede ser un país completo, regiones (ISO 3166-2) de un mismo país, un círculo (de 1 a 500 km) o un polígono (de 3 a 200 puntos). Solo pasa una posición que esté dentro de una zona permitida, y una zona bloqueada siempre prevalece sobre una permitida. Una lista admite hasta 50 zonas y necesita al menos una zona permitida. Didit evalúa todo el círculo de precisión de la posición, no solo su centro:

• Un círculo totalmente fuera de todas las zonas permitidas es LOCATION_OUTSIDE_GEOFENCE.
• Un círculo que cruza un límite determinante para la respuesta es LOCATION_GEOFENCE_UNDETERMINED, nunca “fuera”.
• Un círculo totalmente dentro de una zona bloqueada es LOCATION_IN_BLOCKED_AREA, y se genera además del veredicto sobre las zonas permitidas.

Un país o una región termina donde empieza otra masa terrestre, no en su línea de costa. A la persona se le muestra dónde está disponible el servicio, pero nunca qué zonas están bloqueadas. Las reglas de zonas también funcionan en un paso ip_only, evaluadas a partir de la ubicación IP. La configuración anterior geolocation_geofencing_by_country sigue funcionando, pero no puede combinarse con geolocation_areas.

​

Comprobaciones de distancia

geolocation_document_distance_basis elige la dirección: document (el documento de identidad y, después, la prueba de domicilio), proof_of_address o declared (expected_details.address de la creación de la sesión). Con geolocation_travel_tolerance_enabled, una persona que se haya detectado cerca de su dirección en los últimos geolocation_travel_max_days días no se marca por estar lejos de ella ahora. La tolerancia a viajes nunca justifica una VPN, una ubicación falsificada, un área bloqueada ni una posición fuera de las áreas permitidas.

​

Señales de suplantación e integridad

• Proveedores simulados: Android e iOS informan cuando una posición es simulada en lugar de medida.
• Atestación del dispositivo: los SDK nativos pueden adjuntar una atestación del dispositivo. Una atestación fallida siempre rechaza. Si falta, se registra y, por defecto, no se aplica ninguna acción. Los navegadores no pueden realizar atestaciones y se registran como unsupported, no como un fallo.
• VPN, proxy y Tor: se detectan en la conexión desde la que se compartió la ubicación. Cuando tu acción para alguno de ellos no es NO_ACTION, se pide a la persona que lo desactive y vuelva a comprobarlo mientras queden intentos.
• Emuladores: solo los reportan las aplicaciones nativas. Un emulador finaliza el paso en ese intento, porque ningún reintento cambia el dispositivo.
• Repetición: un desafío presentado en otra sesión siempre rechaza.

​

Resultados

El intento aceptado del paso tiene un único outcome: Mientras queden intentos, un resultado que indique un radio demasiado amplio, una posición antigua o aproximada, una negativa o un problema relacionado con un área pide a la persona que lo intente de nuevo, y solo el último intento genera advertencias. Una posición simulada, o un emulador sobre el que actúa tu flujo, finaliza el paso en el intento en que se reportó.

​

Experiencia de la persona

​

Consentimiento y permiso

No se lee nada antes de que la persona acepte el aviso y responda a la solicitud del sistema. El aviso indica que la ubicación se obtiene una sola vez, para esta verificación, y que no es un registro de sus movimientos. Una persona que se niega se trata según geolocation_refusal_path:

• retry_then_handoff vuelve a preguntar mientras queden intentos y después ofrece continuar en un celular o móvil.
• continue_without_location ofrece seguir sin ubicación y registra la negativa como resultado.
• end_session finaliza el paso y la sesión con la primera negativa. Requiere que geolocation_permission_denied_action sea REVIEW o DECLINE, y la sesión nunca se aprueba.

Con geolocation_allow_skip activado, la persona puede continuar sin ubicación en cualquier momento, y el paso se evalúa según geolocation_unavailable_action.

​

Navegador

El flujo alojado solicita la posición al navegador y muestra ayuda paso a paso para Chrome y Safari cuando la ubicación está desactivada para el sitio. Un navegador no puede distinguir un permiso preciso de uno aproximado, por lo que los resultados web nunca generan LOCATION_APPROXIMATE_ONLY, y nunca informa de un proveedor simulado, un emulador ni una atestación. Un equipo de escritorio no puede compartir una posición precisa, por lo que el flujo ofrece un código QR que permite continuar la misma verificación en el celular o móvil de la persona (geolocation_allow_qr_handoff, activado por defecto), y el equipo de escritorio avanza por sí solo cuando el celular o móvil termina. Cuando incrustes el flujo en un iframe, incluye geolocation en el atributo allow; consulta iframe integrado. Una página que bloquea la política de permisos de geolocalización se trata como una decisión del sitio, no como una negativa de la persona.

​

SDK nativos

Los SDK de iOS y Android solicitan permiso al sistema operativo y pueden adjuntar la atestación del dispositivo y los indicadores de ubicación simulada. En iOS, añade NSLocationWhenInUseUsageDescription a Info.plist; en Android, el SDK declara ACCESS_FINE_LOCATION y ACCESS_COARSE_LOCATION y solicita el permiso en tiempo de ejecución solo cuando un flujo incluye este paso. Consulta los SDK nativos. Un permiso aproximado en iOS o Android genera LOCATION_APPROXIMATE_ONLY, salvo que geolocation_accuracy_mode sea approximate_allowed. Una sesión que usa una versión de la aplicación o del SDK que no incluye este paso finaliza con unsupported_client en lugar de quedar bloqueada.

​

Qué devuelve la decisión

La decisión de la sesión y el webhook status.updated incluyen dos listas:

• geolocation_checks[]: un elemento por cada paso de ubicación, con el intento aceptado de ese paso y sus warnings.
• geolocation_attempts[]: todos los intentos de todos los pasos de ubicación, del más antiguo al más reciente.

Consulta el informe de verificación de ubicación para ver todos los campos. Las coordenadas, la precisión, la ciudad y el país son datos personales del usuario final, por lo que los atributos de respuesta de un flujo pueden limitar qué campos de geolocation_checks devuelve tu decisión.

​

Precios

La verificación de ubicación cuesta $0.05 por comprobación y no forma parte del plan gratuito. Didit cobra una vez por cada paso de ubicación de una sesión, sea cual sea su resultado, porque la comprobación se ejecutó y devolvió una respuesta. Los reintentos dentro del mismo paso son gratuitos. Un nuevo envío que vuelve a completar el paso se cobra de nuevo.

​

Sandbox

Las sesiones de sandbox ejecutan el mismo paso en el mismo flujo alojado, y el dispositivo o el navegador siguen informando una ubicación real. Las sesiones de sandbox nunca llegan al servicio de consulta de IP, por lo que la comparación de IP solo usa lo que la sesión ya tiene. El uso se registra con un precio de 0, así que una sesión de sandbox nunca genera cargos. Este paso no tiene valores de entrada especiales.

​

Páginas relacionadas

• Informe de verificación de ubicación - todos los campos de geolocation_checks[] y geolocation_attempts[].
• Advertencias de verificación de ubicación - todos los códigos LOCATION_* y su acción.
• Configuración de funciones del flujo - todas las claves geolocation_*.
• Análisis de dispositivo e IP - geolocalización por IP y comprobaciones de VPN de la sesión.