> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # API проверки местоположения: геозоны и расстояние по IP > Didit подтверждает местоположение: координаты устройства, геозоны, расстояние по IP и документу, защита от спуфинга. $0.05 за проверку. Шаг верификации местоположения Didit подтверждает, где находится человек во время прохождения верификации. Для этого однократно считываются координаты устройства (через браузер или нативный SDK) или определяется локация по IP-адресу соединения, после чего полученные данные сверяются с разрешенными и заблокированными зонами, локацией по IP и адресом из документов. В сценариях и API это функция `GEOLOCATION`, ее параметры задаются ключами `geolocation_*`, а результат возвращается в массиве `geolocation_checks[]` в решении по сессии. ## Когда использовать * У вас есть лицензия только для определенных юрисдикций (гемблинг, брокерские услуги, кредитование), и вам необходимо подтвердить, что пользователь находился в пределах одной из них при подаче заявки. * Вам необходимо ограничить доступ пользователям из заблокированных регионов, таких как подсанкционные территории или штаты/регионы, которые вы не обслуживаете. * Вам нужен дополнительный сигнал для защиты от фрода: координаты устройства значительно отличаются от локации по IP или адреса в удостоверении личности, обнаружены подмена геопозиции, VPN или эмулятор. * Вам не требуется отслеживать перемещения или историю передвижений человека, достаточно единичного замера, сделанного во время сессии. ## Как это работает **1. Уведомление и разрешение** Пользователь видит, зачем требуется его местоположение и что оно запрашивается однократно только для этой верификации. Затем браузер или телефон запрашивает разрешение на доступ к геопозиции. Didit сохраняет параметры принятого уведомления (версию, язык и время) в поле `consent` в результатах. **2. Одно определение координат на попытку** Клиент фиксирует наиболее точные координаты, пока не будет достигнута достаточная точность либо не истечет таймаут попытки (по умолчанию 20 секунд). Каждая попытка содержит одноразовый проверочный токен, действительный в течение 5 минут и привязанный к сессии, что исключает возможность повторного использования перехваченных данных. **3. Проверки** Didit оценивает точность, актуальность данных, разрешения на приблизительное местоположение, сигналы спуфинга, геозоны, расстояние до локации по IP и до адреса в документе, наличие VPN, прокси, Tor и эмуляторов, а также результаты предыдущих проверок пользователя. **4. Итог** Каждый результат проверки формирует [предупреждение](https://docs.didit.me/ru/core-technology/location-verification/warnings-location-verification.md), для которого настроенное действие (`NO_ACTION`, `REVIEW` или `DECLINE`) определяет статус шага. Применяется наиболее строгое действие из сработавших. ## Источники координат Вы можете выбрать источник координат с помощью параметра `geolocation_position_source`. | Значение | Что происходит | | - | - | | `device_and_ip` | Координаты устройства сверяются с локацией по IP соединения, с которого они были отправлены. | | `device_only` | Используются только координаты устройства. Они не сравниваются с локацией по IP. | | `ip_only` | У пользователя не запрашивается разрешение на доступ к геопозиции. Вместо этого оценивается локация соединения по IP (на уровне города, радиус 50 км) без применения правил точности, актуальности или приблизительных координат. | | не задано | Координаты запрашиваются у устройства и сравниваются с локацией по IP, определенной на шаге Анализ устройства и IP сессии. Узел, настроенный на реагирование на VPN, прокси или Tor, проверяет соединение и работает аналогично `device_and_ip`. | Если узел настроен на запрос координат у устройства, попытка без полученных данных расценивается как отказ или сбой: локация по IP ни при каких обстоятельствах их не заменяет. ## Значения по умолчанию и лимиты конфигурации Все параметры являются необязательными. Полный список приведен в [справочнике конфигураций функций сценариев](https://docs.didit.me/ru/management-api/workflows/feature-configs.md#верификация-местоположения). | Настройка | По умолчанию | Лимиты | | - | - | - | | `geolocation_max_accuracy_radius_m` | 250 м | от 10 до 50,000 м | | `geolocation_max_age_seconds` | 120 с | от 5 до 3,600 с | | `geolocation_timeout_seconds` | 20 с | от 5 до 120 с | | `geolocation_max_attempts` | 3 | от 1 до 5 | | `geolocation_accuracy_mode` | `precise` | `precise` или `approximate_allowed` | | `geolocation_low_accuracy_behavior` | `ask_again` | `ask_again` или `fail` | | `geolocation_allow_qr_handoff` | on | on или off | | `geolocation_allow_skip` | off | on или off | | `geolocation_refusal_path` | `retry_then_handoff` | `retry_then_handoff`, `continue_without_location`, `end_session` | | `is_geolocation_geofencing_enabled` | off | on или off | | `geolocation_ip_distance_km` | 200 км | 0 или более, `null` отключает сравнение | | `geolocation_document_distance_km` | off | 0 или более | | `geolocation_travel_tolerance_enabled` | off | обычная зона от 10 до 500 км (по умолчанию 100), от 1 до 90 дней (по умолчанию 14) | | `geolocation_consecutive_mismatch_count` | off | от 2 до 10 | ### Пресеты Параметр `geolocation_preset` задает значение по умолчанию для каждого действия, которое вы не настроили явно. Пресет `licensing` отклоняет верификацию при нахождении вне разрешенных зон, внутри заблокированной зоны, при использовании VPN, Tor или эмулятора, и отправляет кейс на проверку при обнаружении прокси. Пресет `fraud_screening` использует те же проверки, но отправляет на ручную проверку все случаи, которые `licensing` отклонил бы. Явно настроенное действие всегда имеет приоритет над пресетом. ## Геозоны Включите `is_geolocation_geofencing_enabled` и перечислите геозоны в `geolocation_areas`. Зоной может быть страна целиком, регионы (ISO 3166-2) одной страны, окружность (радиусом от 1 до 500 км) или многоугольник (от 3 до 200 точек). Проверку проходят только координаты внутри разрешенной зоны; при этом заблокированная зона всегда имеет приоритет над разрешенной. Список может содержать до 50 зон и должен включать как минимум одну разрешенную зону. Didit оценивает весь круг погрешности координат, а не только его центр: * Круг, полностью находящийся за пределами всех разрешенных зон, получает статус `LOCATION_OUTSIDE_GEOFENCE`. * Круг, пересекающий границу, от которой зависит решение, получает статус `LOCATION_GEOFENCE_UNDETERMINED`, но никогда не считается находящимся «снаружи». * Круг, полностью находящийся внутри заблокированной зоны, получает статус `LOCATION_IN_BLOCKED_AREA`, который выставляется в дополнение к вердикту по разрешенной зоне. Граница страны или региона заканчивается там, где начинается другая суша, а не по береговой линии. Пользователю отображается информация о том, где доступен сервис, но никогда не показываются заблокированные зоны. Правила геозон также работают для шага с параметром `ip_only`, где оценка производится по локации по IP. Устаревший параметр `geolocation_geofencing_by_country` продолжает поддерживаться, но его нельзя использовать одновременно с `geolocation_areas`. ## Проверки расстояния | Проверка | Измеряется между | Настройка | | - | - | - | | Расстояние по IP | Позицией устройства и геолокацией по IP после вычитания обоих радиусов неопределенности (0 означает, что они пересекаются). | `geolocation_ip_distance_km`, `geolocation_ip_distance_action` | | Расстояние до документа | Позицией и адресом, геокодированным приблизительно, поэтому это слабый сигнал. | `geolocation_document_distance_km`, `geolocation_document_distance_basis`, `geolocation_document_distance_action` | | Серия несовпадений | Предыдущими проверками пользователя (с тем же `vendor_data`), которые находились за пределами разрешенной зоны, в заблокированной зоне или слишком далеко от адреса. | `geolocation_consecutive_mismatch_count` | Параметр `geolocation_document_distance_basis` выбирает адрес: `document` (документ, удостоверяющий личность, затем подтверждение адреса), `proof_of_address` или `declared` (`expected_details.address` при создании сессии). При включенном `geolocation_travel_tolerance_enabled` пользователь, зафиксированный рядом со своим адресом за последние `geolocation_travel_max_days` дней, не отмечается предупреждением за то, что сейчас находится далеко от него. Допуск на поездки никогда не освобождает от проверки использования VPN, спуфинга геопозиции, нахождения в заблокированной зоне или позиции за пределами разрешенных зон. ## Сигналы спуфинга и целостности * **Фиктивные провайдеры**: Android и iOS сообщают, когда позиция симулируется, а не измеряется. * **Аттестация устройства**: нативные SDK могут прикреплять аттестацию устройства. Неудачная аттестация всегда приводит к отклонению. Отсутствующая аттестация фиксируется и по умолчанию не вызывает действий. Браузеры не поддерживают аттестацию и регистрируются со статусом `unsupported`, а не как ошибка. * **VPN, прокси и Tor**: обнаруживаются в соединении, через которое передавалась геолокация. Если ваше действие для одного из них отличается от `NO_ACTION`, пользователю предлагается отключить его и повторить проверку, пока остаются попытки. * **Эмуляторы**: регистрируются только нативными приложениями. Наличие эмулятора завершает шаг на этой попытке, поскольку повторная попытка не изменит устройство. * **Повторное воспроизведение**: проверка, предъявленная в другой сессии, всегда отклоняется. ## Результаты Принятая попытка шага имеет один `outcome`: | Результат | Значение | | - | - | | `verified` | Позиция, соответствующая всем правилам. | | `low_accuracy` / `accuracy_undetermined` | Радиус превысил лимит или устройство не передало данные о точности. | | `stale` | Позиция устарела относительно `geolocation_max_age_seconds`. | | `approximate` | Была предоставлена только приблизительная позиция, тогда как требовалась точная. | | `denied` / `restricted` | Пользователь отказал в доступе или система блокирует геолокацию. | | `unavailable` / `timeout` | Устройство не определило позицию или не успело вовремя. | | `mock_detected` | Система сообщила, что позиция симулируется. | | `outside_geofence` / `in_blocked_area` | Позиция находится за пределами всех разрешенных зон или в заблокированной зоне. | | `anonymizer_detected` | Обнаружен VPN, прокси, выходной узел Tor или эмулятор, и ваш сценарий настроен реагировать на это. | | `skipped` | Пользователь продолжил без передачи геолокации. | | `replay_rejected` | Проверка принадлежала другой сессии. | | `unsupported_client` | Приложение или SDK слишком старые для отображения шага. | Пока остаются попытки, в случае слишком широкого радиуса, устаревших или приблизительных данных, отказа или несоответствия зоны пользователю предлагается повторить попытку, и только последняя попытка генерирует предупреждения. Симулированная позиция или эмулятор, на который реагирует ваш сценарий, завершают шаг на той попытке, где они были зафиксированы. ## Взаимодействие с пользователем ### Согласие и разрешения Никакие данные не считываются до того, как пользователь примет уведомление и ответит на системный запрос. В уведомлении указано, что местоположение считывается один раз для данной верификации и не является записью перемещений. В случае отказа пользователя дальнейшие действия определяются параметром `geolocation_refusal_path`: * `retry_then_handoff` запрашивает разрешение снова, пока остаются попытки, а затем предлагает продолжить на телефоне. * `continue_without_location` предлагает продолжить без передачи местоположения и записывает отказ в качестве результата. * `end_session` завершает шаг и сессию при первом же отказе. Для этого требуется, чтобы параметр `geolocation_permission_denied_action` имел значение `REVIEW` или `DECLINE`, при этом сессия никогда не одобряется. При включенном параметре `geolocation_allow_skip` пользователь может продолжить без передачи местоположения в любой момент, а шаг оценивается в соответствии с `geolocation_unavailable_action`. ### Браузер Размещенный сценарий запрашивает позицию у браузера и отображает пошаговые подсказки для Chrome и Safari, если геолокация для сайта отключена. Браузер не может отличить точное разрешение от приблизительного, поэтому результаты в вебе никогда не вызывают `LOCATION_APPROXIMATE_ONLY`, а также никогда не сообщают о фиктивных провайдерах, эмуляторе или аттестации. Компьютер не может передать точную позицию, поэтому сценарий предлагает QR-код для продолжения той же верификации на телефоне пользователя (`geolocation_allow_qr_handoff`, включено по умолчанию), и компьютер автоматически переходит к следующему шагу, когда телефон завершает процесс. Если вы встраиваете сценарий в iframe, добавьте `geolocation` в атрибут `allow`, см. [iframe в контексте](https://docs.didit.me/ru/integration/web-sdks/incontext-iframe.md). Страница, блокирующая политику разрешений геолокации, расценивается как решение сайта, а не как отказ пользователя. ### Нативные SDK SDK для iOS и Android запрашивают разрешение у операционной системы и могут прикреплять аттестацию устройства и флаги фиктивной геолокации. В iOS добавьте `NSLocationWhenInUseUsageDescription` в `Info.plist`, а на Android SDK объявляет `ACCESS_FINE_LOCATION` и `ACCESS_COARSE_LOCATION` и запрашивает разрешение во время выполнения только в том случае, если в сценарии есть этот шаг. См. [нативные SDK](https://docs.didit.me/ru/integration/native-sdks/overview.md). Предоставление только приблизительного разрешения на iOS или Android вызывает предупреждение `LOCATION_APPROXIMATE_ONLY`, если только `geolocation_accuracy_mode` не установлен в `approximate_allowed`. Сборка приложения или SDK, созданная до появления этого шага, завершается со статусом `unsupported_client`, предотвращая зависание сессии. ## Что возвращает решение [Решение по сессии](https://docs.didit.me/ru/sessions-api/retrieve-session.md) и webhook `status.updated` содержат два списка: * `geolocation_checks[]`: по одному элементу на каждый шаг Location, содержащий принятую попытку этого шага вместе с ее `warnings`. * `geolocation_attempts[]`: каждая попытка каждого шага Location, начиная с самых старых. Ознакомьтесь с [отчётом о верификации местоположения](https://docs.didit.me/ru/core-technology/location-verification/report-location-verification.md), чтобы узнать обо всех полях. Координаты, точность, город и страна являются персональными данными конечного пользователя, поэтому атрибуты ответа в сценарии позволяют ограничить, какие поля `geolocation_checks` возвращает ваше решение. ## Цены Верификация местоположения стоит **\$0.05 за проверку** и не входит в бесплатный тариф. Didit списывает средства один раз за каждый шаг Location в сессии независимо от его результата, поскольку проверка была выполнена и вернула ответ. Повторные попытки внутри одного и того же шага бесплатны. Повторная отправка данных, заново завершающая шаг, тарифицируется повторно. ## Песочница Сессии в песочнице выполняют тот же шаг в том же размещенном сценарии, и устройство или браузер по-прежнему передают реальное местоположение. Сессии в песочнице никогда не обращаются к сервису поиска по IP, поэтому сравнение IP использует только те данные, которые уже есть в сессии. Использование фиксируется по цене 0, поэтому за сессию в песочнице плата не взимается. Специальных тестовых входных данных для этого шага нет. ## Связанные материалы * [Отчёт о верификации местоположения](https://docs.didit.me/ru/core-technology/location-verification/report-location-verification.md) - все поля `geolocation_checks[]` и `geolocation_attempts[]`. * [Предупреждения верификации местоположения](https://docs.didit.me/ru/core-technology/location-verification/warnings-location-verification.md) - каждый код `LOCATION_*` и соответствующее действие. * [Конфигурация функций сценария](https://docs.didit.me/ru/management-api/workflows/feature-configs.md#верификация-местоположения) - каждый ключ `geolocation_*`. * [Анализ устройства и IP](https://docs.didit.me/ru/core-technology/ip-analysis/overview.md) - геолокация по IP и проверки VPN для сессии. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.