> ## 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 在内存缓存（存活时间为 24 小时）中查找该 IP 地址。
3. 如果未命中缓存，则检查共享的 IP 信息富化表（数据新鲜度约为 30 天）。
4. 如果数据已过期或不存在，则通过 Didit 的信息富化流水线解析该 IP 地址，并使用多供应商故障切换。
5. 富化字段写回交易记录，并可供规则使用。

信息富化是**内联**执行的，会在规则运行之前完成，但**失败时不阻塞**。如果无法完成信息富化，交易仍会继续处理，该 IP 地址只是不带富化数据。

## 富化字段

| 字段 | 说明 |
| - | - |
| `ip_country` | 国家/地区名称 |
| `ip_country_code` | 由 Didit 解析时为 ISO 3166-1 alpha-2 代码（您提交的值会按原样保留）；规则条件会对两种形式进行标准化处理 |
| `ip_state` | 行政区划（州、省、地区） |
| `ip_city` | 城市名称 |
| `latitude`, `longitude` | 地理坐标 |
| `isp` | 互联网服务提供商名称 |
| `organization` | 注册组织名称 |
| `is_vpn_or_tor` | 布尔值，表示该 IP 地址是已知的 VPN 或 Tor 出口节点 |
| `is_data_center` | 布尔值，表示该 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/zh/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'])
```

## 缓存层级

| 层级 | 存活时间 | 用途 |
| - | - | - |
| 内存缓存 | 24 小时 | 对高频 IP 地址实现亚毫秒级查找 |
| 共享 IP 信息富化表 | 约 30 天 | 在各实例间共享；比重新解析成本更低 |
| 信息富化流水线 | 不适用 | 当其他层级都没有数据时提供最新数据 |

前两层的命中不会产生额外费用。新的解析可能会按量计费，请参阅您的账单控制台。

## 失败行为

* 交易创建**绝不会**因信息富化失败而失败。
* 缺失的富化字段只会与引用它们的规则条件不匹配。
* 有关信息富化停滞的警报会通过内部监控告知您的运维团队，不会对客户产生影响。

## 有效性过滤

不可路由的 IP 地址会在信息富化之前被跳过：

* 私有地址（10/8、172.16/12、192.168/16）
* 环回地址（127/8）
* 链路本地地址（169.254/16）
* 组播地址、未指定地址

这些过滤可节省供应商配额，并避免产生无意义的富化数据。

## 查看交易的富化结果

**通过 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/zh/transaction-monitoring/response-schema.md#device)。

**在控制台中。** 交易详情页在 **IP与设备** 标签页中显示 IP 信息富化结果，并带有地理地图标记。

## 隐私注意事项

* 原始 IP 地址会与交易一同存储。
* 富化数据保存在以 IP 为键的共享表中，而不是按用户存储。
* 根据被遗忘权请求执行删除时，会从交易中移除 IP 地址；共享缓存条目会保留（其中不包含可识别个人身份的信息）。

## 后续步骤

> [card] [规则](https://docs.didit.me/zh/transaction-monitoring/rules.md)
>
> 在条件中使用富化字段。

> [card] [规则库](https://docs.didit.me/zh/transaction-monitoring/rules-library.md)
>
> 预设的基于 IP 的规则。

> [card] [响应结构](https://docs.didit.me/zh/transaction-monitoring/response-schema.md)
>
> IP 信息富化出现的位置。


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