> ## 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 风险分析 API（面向 KYC）

> Didit 设备与 IP 分析可在 KYC 验证期间检测重复设备、欺诈团伙、VPN、代理、Tor、位置不匹配及可疑设备指纹。

Didit 的设备与 IP 分析将设备指纹、重复设备恢复、IP 情报和地理位置核验整合到验证流程中。即使用户更换会话、清除浏览器存储、打开无痕窗口或切换网络信息，它也能帮助检测同一台物理设备是否正尝试访问多个账户。

设备与 IP 分析集成提示词
        将提示词复制到剪贴板



      
      

\<pre>

\````# Goal
Integrate Didit Device & IP Analysis (device fingerprinting + IP intelligence + geolocation) into your app.

\# Delivery mode
IP Analysis is **session-only**. The Web/Mobile SDK collects the device fingerprint and IP during the hosted flow — there is no standalone /v3/ip-analysis/ endpoint. It runs automatically on every session and does not require a workflow feature toggle for the basic signal set.

\# Steps
1\. (Optional) In the Business Console enable strict-mode rules for IP / device — e.g. "decline on VPN", "review on duplicate device", "decline on country mismatch with document".
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user — the SDK collects fingerprint + IP in-band.
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

curl (create session):
\```bash
curl -X POST 'https://verification.didit.me/v3/session/' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"workflow_id": "YOUR_WORKFLOW_ID",
"vendor_data": "user-123",
"callback": "https://yourapp.com/post-kyc"
}'
\```

\# Decision surface
The result lands under `ip_analyses[]` on the decision payload (one entry per IP/device collection point in the workflow). Each entry carries the resolved geo, ASN, VPN / proxy / Tor flags, device fingerprint id, duplicate-device matches, and the warnings array.

\# Status enum (per ip_analyses[].status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.LOCATION)
Heads-up: IP Analysis emits warnings under the **LOCATION** bucket (not "IP_ANALYSIS"). Risk codes include:
VPN_DETECTED, PROXY_DETECTED, TOR_DETECTED, DATACENTER_IP, HIGH_RISK_COUNTRY, LOCATION_MISMATCH_WITH_DOCUMENT, DUPLICATED_DEVICE, POSSIBLE_DUPLICATED_DEVICE, IMPOSSIBLE_TRAVEL, DEVICE_FINGERPRINT_BLOCKLISTED, DEVICE_LINKED_TO_LIVENESS_ATTACK, DEVICE_MODEL_INCONSISTENT.
Full catalogue: /core-technology/ip-analysis/warnings-ip-analysis.

\# Failure modes to handle
\- ip_analyses[] empty — the user blocked the SDK fingerprinting script (privacy extensions, content blockers). Decide whether to fail-closed or fall back to soft signals.
\- VPN_DETECTED / PROXY_DETECTED / TOR_DETECTED — treat per your fraud policy (decline, manual review, additional liveness step).
\- DUPLICATED_DEVICE — same device previously enrolled under a different vendor_data; merge accounts or block per policy.
\- LOCATION_MISMATCH_WITH_DOCUMENT — the IP country does not match the document's issuing country; route to review.

\# See also
\- Canonical schema: /reference/data-models#ip-analysis
\- Per-feature report: /core-technology/ip-analysis/report-ip-analysis
\- Risk catalogue: /core-technology/ip-analysis/warnings-ip-analysis
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

粘贴到

该功能专为对误报成本极其敏感的反欺诈决策而设计。完全相同的重复设备匹配使用稳定的持久化标识符。恢复设备匹配则采用 v2 指纹信号向量和高置信度门槛，使 Didit 能够在标记可疑复用行为的同时，避免过度激进地将无关用户合并。在关于解读验证结果的学院课程中，9:49 章节详细讲解了设备与 IP 分析信号。[Device and IP analysis — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=589\&rel=0\&playsinline=1)![Didit 设备与 IP 分析概览，显示地理位置、设备指纹、设备情报和 VPN 检测](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=a2fbbbdd3d6fed3d759e54f362bf4762)![Didit 设备与 IP 分析架构图，交叉核对 IP、设备指纹和声明位置](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis-how-it-works.jpg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=3519ad9ad50091a00db5e09d5197fdfe)## 工作原理设备与 IP 分析在验证会话期间自动运行，并将设备、网络和身份上下文关联为统一的风险面。**1. 设备指纹采集**验证客户端发送包含 Web 或移动设备信号的保护隐私的 v2 指纹 payload：| 数据点 | 说明 |
| - | - |
| **持久化设备 ID** | 第一方标识符，在存储数据仍保留时用于精确的同一设备检测。 |
| **复合哈希** | 稳定的分组信号哈希，用于确定性重复核验并配备冲突防护机制。 |
| **信号向量** | 向量化的设备和浏览器/应用属性，用于高置信度恢复。 |
| **平台上下文** | 浏览器、操作系统、应用、硬件、WebGL/canvas、媒体、语言区域、时区以及可用的移动端完整性信号。 |**2. IP 与连接分析**Didit 使用网络风险信息丰富观测到的连接数据：- 按国家/地区、省份/大区、城市和坐标划分的 IP 地理位置
- VPN、代理、Tor、数据中心和私有网络检测
- 当您为会话提供允许的 IP 时进行预期 IP 核验
- 在您的应用中配置的 IP 黑名单核验**3. 重复与恢复匹配**Didit 核验当前会话是否匹配来自其他 `vendor_data` 的历史会话：| 核验项 | 目的 |
| - | - |
| **重复 IP** | 检测不同用户之间是否存在相同的地址。 |
| **重复设备指纹** | 检测相同持久化设备身份的完全复用。 |
| **恢复设备** | 当持久化 ID 发生变化时，检测高置信度的 v2 指纹恢复。 |
| **冲突防护** | 抑制低质量共享池哈希，而非将不相关的设备合并。 |**4. 位置交叉核验**设备与 IP 分析将位置上下文与可信参考点进行比对：- 证件签发国家/地区与地址坐标
- 预期的会话 IP 地址
- IP 所在国家/地区及城市
- 地址与 IP 位置之间的距离和方位**5. 操作与报告**您可以单独配置每个风险类别，并在 Didit 的各类输出中获取结果：| 渠道 | 说明 |
| - | - |
| **工作流操作** | 针对 VPN/代理、位置不匹配、重复 IP、完全重复设备和恢复设备执行批准、审核或拒绝。 |
| **仪表板** | 在 Didit 控制台中查看警告、匹配会话、设备信息和网络详情。 |
| **Webhook 和 API** | 在决策 payload 中接收结构化的警告和匹配项。 |
| **报告** | 在验证 PDF 中导出设备与 IP 分析详情。 |## 匹配模型设备与 IP 分析将完全匹配与恢复匹配区分开来，以便您安全地调整欺诈响应策略：| 层级 | 检测内容 | 误报倾向 |
| - | - | - |
| **精确持久化 ID** | 相同的第一方设备身份出现在另一用户的会话中。 | 最强信号。用于 `DUPLICATED_DEVICE_FINGERPRINT`。 |
| **复合哈希** | 相同的确定性设备哈希出现在另一用户的会话中。 | 受冲突检测保护，因此常见的 WebView/浏览器池会被抑制。 |
| **v2 恢复设备** | 持久化 ID 已更改，但丰富的设备信号以高置信度匹配先前的设备。 | 保守。仅在通过硬性门槛后用于 `DEVICE_RECOVERED_HIGH_CONFIDENCE`。 |
| **IP 复用** | 相同的地址出现在不同用户之间。 | 视上下文而定。对欺诈团伙有用，但共享办公室、家庭和移动运营商也可能是合法场景。 |恢复设备匹配使用专用的向量恢复索引。如果该索引不可用，Didit 将继续进行完全重复核验，不会输出模糊的恢复候选项。在 **Networks** 中，当相同的非数据中心 IP 情报跨多个不同用户或企业出现时，Didit 还会突出显示住宅代理复用情况。图谱会显示聚合风险信号、主体数量、连接类型、ISP 和 ASN 上下文；它不会暴露原始地址或其他组织的画像数据。## 检测到的欺诈模式设备与 IP 分析有助于识别并减少：- 多账号操作与重复创建账号
- 跨不同身份使用同一设备尝试绕过 KYC
- 欺诈团伙利用共享设备或基础设施协调控制大量账号
- 奖励滥用、邀请滥用、促销滥用和免费试用滥用
- 利用重复设备入驻合成身份
- 资金骡子入驻模式
- 陌生或高风险设备带来的账号劫持风险
- 凭据撞库与自动化注册尝试
- 利用重复设备/网络模式进行的测卡、拒付滥用和退款滥用
- 利用 VPN、代理、Tor、数据中心和住宅代理进行规避
- 设备篡改、模拟器使用、越狱/Root 风险，以及移动信号可用时的应用多开克隆
- 位置欺骗攻击，以及证件、IP、时区、运营商和设备上下文之间的不匹配
- 使用无头浏览器或脚本客户端的自动化机器人验证尝试## 核心功能#### 设备指纹识别与恢复- **完全相同设备检测**：跨具有不同 `vendor_data` 值的会话检测出相同的设备身份。
- **高置信度恢复**：在存储发生变化或无痕/隐私浏览改变持久 ID 时，恢复可能属于同一设备的关系。
- **冲突防护**：当某个设备哈希在许多不同的持久 ID 之间显得过于通用时，避免合并无关用户。
- **移动端与 Web 端覆盖**：利用 Web 浏览器信号和原生移动端信号，并在可用时包含完整性相关字段。#### IP 与网络情报- **VPN 与代理检测**：识别经过掩蔽或匿名化的连接。
- **Tor 与数据中心检测**：标记高风险基础设施。
- **住宅代理重复使用**：在不向“网络”图谱暴露原始 IP 值的情况下，检测在不同主体之间重复使用相同住宅类网络的情况。
- **IP 黑名单**：当 IP 出现在您的应用黑名单中时自动拒绝。
- **预期 IP 强制执行**：将检测到的 IP 与会话创建期间提供的预期 IP 进行比对。#### 地理位置与证件比对- **国家/地区不匹配检测**：比对证件国家/地区与 IP 所在国家/地区。
- **地理围栏**：根据 IP 地理位置，仅接受来自允许国家/地区的会话——对于美国等国家/地区支持按州/地区进行单独覆盖。
- **地址距离核查**：比对证件地址坐标与 IP 地理位置。
- **会话匹配上下文**：返回包含设备和位置详情的匹配会话，供人员审核。## 配置操作使用工作流设置来为每种风险选择操作。较为审慎的客户通常会先将 `recovered_device_action` 设置为 `REVIEW`，观察恢复设备警告数周，仅在确认本地误报情况后再调整为 `DECLINE`。| 设置 | 建议初始操作 | 原因 |
| - | - | - |
| `vpn_detection_action` | `REVIEW` 或 `DECLINE` | 取决于您的产品是否允许使用 VPN。 |
| `ip_mismatch_action` | `REVIEW` | 位置不匹配是重要的上下文信息，但也可能是合法行为。 |
| `duplicated_ip_action` | `REVIEW` | 共享网络可能会产生误报。 |
| `duplicated_device_action` | `REVIEW` 或 `DECLINE` | 跨用户完全重复使用同一设备是强欺诈信号。 |
| `recovered_device_action` | `REVIEW` | 高置信度恢复设计上偏保守，但在自动拒绝前应先进行监控。 |
| `ip_geofencing_action` | `DECLINE` | 地理围栏通常体现严格的司法管辖规则；如果您更倾向于对受限位置进行人工分流，请使用 `REVIEW`。 |请参阅[设备与 IP 分析警告](https://docs.didit.me/zh/core-technology/ip-analysis/warnings-ip-analysis.md)了解所有风险标签，并参阅[工作流功能配置](https://docs.didit.me/zh/management-api/workflows/feature-configs.md#设备与-ip-分析)了解 API 字段。


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