> ## 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 分析报告：字段与匹配

> 解析 Didit 设备与 IP 分析报告：涵盖地理定位、设备指纹、VPN/Tor/代理标记、证件与 IP 距离以及重复设备匹配等详细字段。

## 概述

设备与 IP 分析通过 IP 地理位置、设备指纹、浏览器/操作系统以及网络类型对每个会话进行画像分析。
地理位置、网络风险数据扩充、设备匹配以及远程设备完整性检查在用户完成验证的过程中异步执行。
在分析处理期间，设备和 IP 观测数据保持可用；在结果返回前或地址非公开时，地理位置字段可能为空。
如果您的工作流使用这些检查来确定结果或选择后续步骤，会话将保持为 `In Progress`，直至所需的结果就绪。
如果在设定的重试次数后所需分析仍不可用，会话将转为 `In Review` 以供人工决策。
可选的数据扩充失败不会阻碍完成，且人工决策始终具有决定性。
它提供：

* 由公网 IP 推导出的 **IP 地理位置**区块（国家/地区、州/省、城市、纬度/经度、时区）。
* **网络风险标记** — `is_vpn_or_tor` 和 `is_data_center` — 用于检测伪装行为（VPN、Tor 出口节点、托管服务提供商、匿名代理）。
* **跨证件距离计算** — IP 位置、身份证件位置以及地址证明文件位置之间的直线距离（公里）。
* **跨会话匹配** — 当相同的 IP 地址或设备标识出现在属于不同用户的会话中时（按 `vendor_data` 分组）。
* **设备指纹恢复** — 一种高置信度的恢复信号，即使用户清除了存储、切换至无痕模式或重新安装了应用，仍能将各个会话关联起来。

![Didit 设备与 IP 分析报告截图，显示地理位置、设备指纹和风险标记](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=5d4877664a7c89384ee32d4a5cb6949b)

## 在 API 响应中的位置

决策 endpoint 在 `GET /v3/session/{sessionId}/decision/` 中以复数数组 **`ip_analyses[]`** 的形式返回设备与 IP 分析。其中的条目是以 (`node_id`, `ip_address`, `device_fingerprint`) 为键的去重 `Location` 观测记录 — 当用户的 IP 或设备在会话中途发生变化时，单个节点可以产生多个条目。

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "ip_analyses": [ { status, node_id, ip_address, ip, id_document, poa_document, warnings, matches, … }, … ] }
```

下方的数据结构对应规范 schema — 参见[数据模型](https://docs.didit.me/zh/reference/data-models.md#ip-分析)。

## 数据结构

有关规范 schema，请参阅[数据模型参考中的设备与 IP 分析](https://docs.didit.me/zh/reference/data-models.md#ip-分析)。

```typescript theme={null}
interface IPAnalysisV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review' | 'Resub Requested';
  node_id: string | null;

  // Device
  device_brand: string | null;
  device_model: string | null;
  browser_family: string | null;
  os_family: string | null;
  platform: 'mobile' | 'tablet' | 'desktop' | null;
  device_fingerprint: string | null;

  // IP geolocation
  ip_country: string | null;
  ip_country_code: string | null;           // ISO 3166-1 alpha-2
  ip_state: string | null;
  ip_city: string | null;
  latitude: number | null;
  longitude: number | null;
  ip_address: string;
  isp: string | null;
  organization: string | null;
  is_vpn_or_tor: boolean;
  is_data_center: boolean;
  time_zone: string | null;
  time_zone_offset: string | null;

  // Distance blocks — each carries its own location + distances to the other two
  ip: {
    location: { latitude: number; longitude: number } | null;
    distance_from_id_document: number | null;   // km
    distance_from_poa_document: number | null;  // km
  };
  id_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_poa_document: number | null;
  };
  poa_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_id_document: number | null;
  };

  warnings: Warning[];          // see Data Models — Warning object

  // Cross-session matches — up to 5 IP matches + 5 device matches
  matches: IPAnalysisMatch[];
}

interface IPAnalysisMatch {
  session_id: string;                       // matching session UUID
  session_number: number;
  vendor_data: string | null;
  verification_date: string | null;         // "YYYY-MM-DDTHH:MM:SSZ"
  match_type: 'ip_address' | 'device_fingerprint';
  match_source: 'ip_address' | 'persistent_id' | 'legacy_fp' | 'recovered_high';
  matched_value: string | null;             // shared IP, device identifier, or recovered device UUID
  status: string;                           // lifecycle status of the matching session
  is_blocklisted: boolean;                  // currently always false
  api_service: string | null;               // standalone API service; null for workflow sessions
  source: 'session';
  device_info: {
    device_brand: string | null;
    device_model: string | null;
    browser_family: string | null;
    os_family: string | null;
    platform: string | null;
    device_fingerprint: string | null;
  };
  location_info: {
    ip_address: string | null;
    ip_country: string | null;
    ip_country_code: string | null;
    ip_state: string | null;
    ip_city: string | null;
    is_vpn_or_tor: boolean;
    is_data_center: boolean;
  };
  confidence: number;                       // 0–1, = 1 - P(false positive)
  match_mode: 'deterministic' | 'probabilistic' | 'co_occurrence';

  // Present only when match_source = 'recovered_high'
  recovery_similarity?: number;             // cosine similarity, 4 decimals
  tls_ja4_corroborated?: boolean;           // TLS JA4 fingerprints of both observations agree
  recovery_gate_reason?: string;            // e.g. 'hardware_root_match'
}
```

### 匹配语义

`match_source` 指明了匹配的实现方式，而 `confidence` 则评估其*错误*的可能性（`confidence = 1 - P(false positive)`）：

| `match_source` | 含义 | `confidence` | `match_mode` |
| - | - | - | - |
| `ip_address` | 共享 IP — 表示网络共址，绝不表示设备身份相同。 | `0.0` | `co_occurrence` |
| `persistent_id` | 精确存储的持久设备标识符。 | `1.0` | `deterministic` |
| `legacy_fp` | 传统的 `didit-fp-*` 设备指纹哈希。 | `0.5` | `probabilistic` |
| `recovered_high` | 经过严格硬性门槛筛选后的高置信度模糊指纹恢复命中。 | 以硬件为根时为 `1.0`，否则 `< 1.0`，在 TLS JA4 和 IP 国家/地区独立一致时提升 | `deterministic` 或 `probabilistic` |

较低置信度的恢复候选仅作为风险警告呈现 — 绝不会出现在 `matches[]` 中。IP 匹配和设备匹配各上限为 5 项，因此该数组最多包含 10 个条目。

## 状态值

状态属于功能层级的 `FeatureStatusChoices` 值。触发的每个警告都会映射到在工作流节点上为其配置的操作；以最高优先级的操作为准。

| 值 | 含义 |
| - | - |
| `Not Finished` | 此会话的 IP 分析节点尚未完成（默认值）。 |
| `Approved` | 未触发任何警告，或所有触发的警告均配置为“无操作”。 |
| `In Review` | 至少有一个触发的警告配置为“审核”（参见[警告](https://docs.didit.me/zh/core-technology/ip-analysis/warnings-ip-analysis.md)）。 |
| `Declined` | 触发了黑名单警告（`IP_ADDRESS_IN_BLOCKLIST` 或 `DEVICE_FINGERPRINT_IN_BLOCKLIST` — 一律拒绝），或可配置警告针对您的工作流被设置为“拒绝”。 |
| `Resub Requested` | 审核员请求重新提交此步骤。 |

在 IP 分析节点上配置的自定义状态规则可以进一步调整最终生成的状态。

## VPN、代理与 Tor 检测

`is_vpn_or_tor` 和 `is_data_center` 是针对每个会话返回的独立布尔标记。当 `is_vpn_or_tor` 为 `true` 时，Didit 还会发出 `PRIVATE_NETWORK_DETECTED` 警告，以便您的团队可以通过工作流配置据此采取操作。仅数据中心流量（不含 VPN/Tor）会将 `is_data_center=true`，但不会自动发出警告 — 可在您自己的评分机制中将其用作补充信号。

## 示例

### Approved

```json theme={null}
{
  "ip_analyses": [
    {
      "status": "Approved",
      "node_id": "ip-1",
      "device_brand": "Apple",
      "device_model": "iPhone",
      "browser_family": "Mobile Safari",
      "os_family": "iOS",
      "platform": "mobile",
      "device_fingerprint": "didit-fp-8d2c7a91f4b3e042",
      "ip_country": "Spain",
      "ip_country_code": "ES",
      "ip_state": "Barcelona",
      "ip_city": "Barcelona",
      "latitude": 41.4022,
      "longitude": 2.1407,
      "ip_address": "83.50.226.71",
      "isp": "Telefonica",
      "organization": "Telefonica de Espana",
      "is_vpn_or_tor": false,
      "is_data_center": false,
      "time_zone": "Europe/Madrid",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 41.4022, "longitude": 2.1407 },
        "distance_from_id_document": 23.4,
        "distance_from_poa_document": 12.3
      },
      "id_document": {
        "location": { "latitude": 41.2706, "longitude": 1.9770 },
        "distance_from_ip": 23.4,
        "distance_from_poa_document": 18.7
      },
      "poa_document": {
        "location": { "latitude": 41.3128, "longitude": 2.0540 },
        "distance_from_ip": 12.3,
        "distance_from_id_document": 18.7
      },
      "warnings": [],
      "matches": []
    }
  ]
}
```

### Declined — 命中 IP 黑名单 + VPN + 重复设备

```json theme={null}
{
  "ip_analyses": [
    {
      "status": "Declined",
      "node_id": "ip-1",
      "device_brand": null,
      "device_model": null,
      "browser_family": "Chrome",
      "os_family": "Linux",
      "platform": "desktop",
      "device_fingerprint": "didit-fp-a13c0d22e8b94471",
      "ip_country": "Netherlands",
      "ip_country_code": "NL",
      "ip_state": "North Holland",
      "ip_city": "Amsterdam",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "ip_address": "45.61.20.5",
      "isp": "Example Hosting",
      "organization": "Example Hosting BV",
      "is_vpn_or_tor": true,
      "is_data_center": true,
      "time_zone": "Europe/Amsterdam",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 52.3676, "longitude": 4.9041 },
        "distance_from_id_document": 1834.2,
        "distance_from_poa_document": 1822.5
      },
      "id_document": {
        "location": { "latitude": 40.4168, "longitude": -3.7038 },
        "distance_from_ip": 1834.2,
        "distance_from_poa_document": 14.0
      },
      "poa_document": {
        "location": { "latitude": 40.5070, "longitude": -3.6720 },
        "distance_from_ip": 1822.5,
        "distance_from_id_document": 14.0
      },
      "warnings": [
        {
          "feature": "LOCATION",
          "risk": "IP_ADDRESS_IN_BLOCKLIST",
          "additional_data": { "ip_address": "45.61.20.5" },
          "log_type": "error",
          "short_description": "IP address in blocklist",
          "long_description": "The IP address used for this session was found in the application's IP blocklist, indicating a known suspicious or forbidden origin.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "PRIVATE_NETWORK_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Private network (VPN/Tor) detected",
          "long_description": "The system detected that the user tried to use a private network (VPN/TOR) to complete the verification process.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP",
          "additional_data": { "document_country_code": "ESP", "ip_country_code": "NLD" },
          "log_type": "warning",
          "short_description": "Document country does not match IP country",
          "long_description": "The country from the document does not match the country from the IP address, suggesting a potential mismatch between the document and the user's location.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "DUPLICATED_DEVICE_FINGERPRINT",
          "additional_data": {
            "duplicated_session_id": "11111111-2222-3333-4444-555555555555",
            "duplicated_session_number": 1042,
            "api_service": null,
            "match_source": "persistent_id"
          },
          "log_type": "warning",
          "short_description": "Duplicated device fingerprint from another session",
          "long_description": "The same device fingerprint was detected in another session with a different vendor_data, which may indicate multiple identities verified from the same device.",
          "node_id": "ip-1"
        }
      ],
      "matches": [
        {
          "session_id": "11111111-2222-3333-4444-555555555555",
          "session_number": 1042,
          "vendor_data": "user-other",
          "verification_date": "2026-05-28T14:03:21Z",
          "match_type": "device_fingerprint",
          "match_source": "persistent_id",
          "matched_value": "pid_9f1c2b7a8d3e4f50",
          "status": "Declined",
          "is_blocklisted": false,
          "api_service": null,
          "source": "session",
          "device_info": {
            "device_brand": null,
            "device_model": null,
            "browser_family": "Chrome",
            "os_family": "Linux",
            "platform": "desktop",
            "device_fingerprint": "didit-fp-a13c0d22e8b94471"
          },
          "location_info": {
            "ip_address": "45.61.23.99",
            "ip_country": "Netherlands",
            "ip_country_code": "NL",
            "ip_state": "North Holland",
            "ip_city": "Amsterdam",
            "is_vpn_or_tor": true,
            "is_data_center": true
          },
          "confidence": 1.0,
          "match_mode": "deterministic"
        }
      ]
    }
  ]
}
```

## 相关内容

* [设备与 IP 分析警告](https://docs.didit.me/zh/core-technology/ip-analysis/warnings-ip-analysis.md) — IP 分析可能发出的所有警告代码
* [设备与 IP 分析概述](https://docs.didit.me/zh/core-technology/ip-analysis/overview.md) — 各个模块衡量的指标
* [数据模型 — IP 分析](https://docs.didit.me/zh/reference/data-models.md#ip-分析) — 规范 schema
* [Webhooks](https://docs.didit.me/zh/integration/webhooks.md) — `status.updated` 携带相同的 IP 分析 payload


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