> ## 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.

# Обогащение IP-данных транзакций: страна, ASN, VPN

> Didit обогащает каждую транзакцию IP-данными: страна, ASN, VPN, Tor, дата-центр, оператор связи. 1,000 в месяц включено, затем $0.001 за каждую.

Каждая транзакция, содержащая IP-адрес устройства, обогащается на стороне сервера в реальном времени до того, как правила её проверят. Обогащение добавляет страну, город, флаги VPN/Tor/дата-центра, ASN и оператора связи; всё это доступно как условия правил.

## Когда запускается обогащение

Встроенное обогащение при создании транзакции:

1. Вы отправляете `POST /v3/transactions/` с `subject.device_context.network_context.ip_address` (или IP-адресом устройства любой стороны).
2. Didit ищет IP-адрес в кеше в памяти (TTL 24 часа).
3. Если адреса нет в кеше, проверяется общая таблица обогащения IP-адресов (актуальность около 30 дней).
4. Если данные устарели или отсутствуют, IP-адрес определяется через конвейер обогащения Didit с переключением на резервных провайдеров.
5. Обогащённые поля записываются в запись транзакции и становятся доступны правилам.

Обогащение выполняется **встроенно**: оно завершается до запуска правил, но **не блокирует транзакцию при сбое**. Если обогащение не может завершиться, транзакция всё равно проходит, а IP-адрес отображается без данных обогащения.

## Обогащённые поля

| Поле | Описание |
| - | - |
| `ip_country` | Название страны |
| `ip_country_code` | ISO 3166-1 alpha-2, если код определён Didit (значение, которое вы передали, сохраняется в исходном виде); условия правил приводят обе формы к единому виду |
| `ip_state` | Административная единица (штат, регион) |
| `ip_city` | Название города |
| `latitude`, `longitude` | Географические координаты |
| `isp` | Название интернет-провайдера |
| `organization` | Название организации, на которую зарегистрирован IP-адрес |
| `is_vpn_or_tor` | Логическое значение (boolean): IP-адрес известен как выходной узел VPN или Tor |
| `is_data_center` | Логическое значение (boolean): IP-адрес принадлежит диапазону хостинга или дата-центра |
| `time_zone` | Часовой пояс IANA (например, `America/New_York`) |
| `time_zone_offset` | Смещение относительно UTC |
| `asn_number` | Номер автономной системы (ASN) |
| `asn_organization` | Организация, зарегистрировавшая ASN |
| `connection_type` | `mobile`, `broadband`, `dialup`, `corporate`, ... |
| `carrier` | Оператор мобильной связи (для мобильных IP-адресов) |
| `proxy_type` | `VPN`, `TOR`, `PUBLIC_PROXY` или null |

## Использование обогащённых полей в правилах

Любое из обогащённых полей может быть [условием правила](https://docs.didit.me/ru/transaction-monitoring/rules.md). Типовые примеры:

**Юрисдикция повышенного риска по IP-адресу**

```
condition: applicant.ip_country_code IN ['IRN', 'PRK', 'SYR']
action: add_score(35), add_tags(['high_risk_ip_country'])
```

**Использование VPN / Tor**

```
condition: applicant.is_vpn_or_tor == true
action: change_status('IN_REVIEW'), add_tags(['anonymization'])
```

**Дата-центр / происхождение не из жилой сети**

```
condition: applicant.is_data_center == true AND amount > 10000
action: add_score(30)
```

**Страна IP-адреса ≠ страна KYC**

```
condition: applicant.ip_country_code != applicant.country_code
action: add_score(15), add_tags(['geo_mismatch'])
```

## Уровни кеширования

| Уровень | TTL | Назначение |
| - | - | - |
| Кеш в памяти | 24 часа | Поиск менее чем за миллисекунду для часто запрашиваемых IP-адресов |
| Общая таблица обогащения IP-адресов | около 30 дней | Общая для всех экземпляров; дешевле повторного определения |
| Конвейер обогащения | н/д | Свежие данные, если их нет ни в одном из предыдущих уровней |

Обращения к первым двум уровням не тарифицируются дополнительно. Новые запросы к провайдерам могут тарифицироваться: см. консоль биллинга.

## Поведение при сбоях

* Создание транзакции **никогда не завершается ошибкой** из-за сбоя обогащения.
* Отсутствующие поля обогащения просто не совпадают с теми условиями правил, которые на них ссылаются.
* Оповещения о зависшем обогащении передаются вашей команде эксплуатации через внутренний мониторинг; для конечных пользователей это не влияет.

## Фильтрация по валидности

Немаршрутизируемые IP-адреса исключаются до обогащения:

* Частные (10/8, 172.16/12, 192.168/16)
* Адреса обратной петли (loopback) (127/8)
* Адреса локального канала (link-local) (169.254/16)
* Многоадресные (multicast) и неуказанные (unspecified)

Это экономит квоту провайдера и исключает бессмысленные данные обогащения.

## Просмотр обогащения для транзакции

**Через API.** Отдельного блока обогащения нет. Обогащённые поля записываются в собственный объект `device.network_context` стороны, рядом с переданным вами `ip_address`, в соответствующем элементе массива `parties`:

```json theme={null}
"parties": [
  {
    "role": "APPLICANT",
    "vendor_data": "user-42",
    "device": {
      "network_context": {
        "ip_address": "203.0.113.5",
        "ip_country": "United States",
        "ip_country_code": "US",
        "ip_state": "California",
        "ip_city": "San Francisco",
        "is_vpn_or_tor": false,
        "is_data_center": false,
        "asn_number": 64496,
        "asn_organization": "Example ISP",
        "proxy_type": null
      }
    }
  }
]
```

Поля, которые вы передали в запросе, сохраняются; обогащение заполняет только ключи, которые вы не указали, а ключи, для которых резолвер вернул пустое значение, опускаются. Полную структуру `device` см. в [схеме ответа](https://docs.didit.me/ru/transaction-monitoring/response-schema.md#device).

**В консоли.** На странице деталей транзакции обогащение IP-адреса отображается во вкладке **IP и устройство** с меткой на карте.

## Конфиденциальность

* Исходные IP-адреса хранятся вместе с транзакцией.
* Данные обогащения хранятся в общей таблице, ключом в которой является IP-адрес, а не в привязке к пользователю.
* Удаление в соответствии с правом на забвение удаляет IP-адреса из транзакции; запись в общем кеше сохраняется, так как она не идентифицирует конкретное лицо.

## Следующие шаги

> [card] [Правила](https://docs.didit.me/ru/transaction-monitoring/rules.md)
>
> Используйте обогащённые поля в условиях.

> [card] [Библиотека правил](https://docs.didit.me/ru/transaction-monitoring/rules-library.md)
>
> Готовые правила на основе IP-адресов.

> [card] [Схема ответа](https://docs.didit.me/ru/transaction-monitoring/response-schema.md)
>
> Где отображается обогащение IP-адреса.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.