Didit OCR 与证件防伪接入说明

原始资料：D:/WorkSpace/divs-orch/docs/didit/DIDIT_OCR_DOCUMENT_AUTHENTICITY_INTEGRATION.md

LLM 速览

Didit 的证件 OCR 与证件防伪能力采用 后端创建 Session + App SDK 采集 + Webhook / Decision 查询取结果 的模式。App 不直接拿 API Key，也不直接查询最终结果；完整 OCR 字段、防伪 warnings、图片链接和最终决策应由后端从 V3 Decision 获取并保存。

关键结论：

集成模式：异步 session-based。
创建会话：POST /v3/session/。
查询权威结果：GET /v3/session/{sessionId}/decision/。
App 侧：Didit Android SDK 使用 session_token 完成证件采集。
OCR 节点：id_verifications[]。
防伪原因：id_verifications[].warnings[].risk。
决策影响：warnings[].log_type，可能是 error、warning、information。
不要用 short_description / long_description 做程序分支。

1. 生产主链路

text

后端 POST /v3/session/
  -> 返回 session_id、session_token
  -> App 用 session_token 启动 Didit SDK
  -> 用户完成证件采集
  -> Didit Webhook 通知状态变化
  -> 后端 GET /v3/session/{sessionId}/decision/
  -> 保存 OCR 字段、防伪 warnings、原始 Decision
  -> App 查询我方后端结果

2. 接口清单

阶段	调用方	接口 / 回调	用途
创建会话	我方后端	`POST /v3/session/`	获取 `session_id` 与短期 `session_token`
启动采集	App	`DiditSdk.startVerification(token=...)`	证件拍摄和上传
状态通知	Didit -> 我方后端	`status.updated` Webhook	通知 Session 状态变化
获取权威结果	我方后端	`GET /v3/session/{sessionId}/decision/`	获取完整 OCR、防伪、状态和原因
人工审核轨迹	我方后端 / 管理台	`GET /v3/sessions/{session_id}/reviews/`	获取审核轨迹和 comment

3. OCR 字段

OCR 结果位于 id_verifications[]。工作流可能包含多个 OCR 节点，建议遍历整个数组并按 node_id 识别节点，不要只读取第一条。

建议保存的核心字段：

text

node_id
status
document_type
document_subtype
document_number
personal_number
first_name
last_name
full_name
date_of_birth
expiration_date
date_of_issue
issuing_state
nationality
gender
address
formatted_address
parsed_address
mrz
extra_fields

不同国家、证件版本和证件类型不保证全部字段存在，解析字段必须允许 null 或缺失。

4. 证件防伪

当前重点关注三个防伪风险码：

risk	含义	处理建议
`SCREEN_CAPTURE_DETECTED`	疑似从屏幕采集	按 `log_type` 路由，不暴露具体模型规则
`PRINTED_COPY_DETECTED`	疑似打印件 / 复印件	提示使用证件原件
`PORTRAIT_MANIPULATION_DETECTED`	疑似替换或篡改证件头像	通常作为强风险处理

Didit V3 Decision 不返回底层模型原始分、内部阈值或模型版本，因此我方不要自行另设防伪模型阈值。

5. 判断优先级

程序判断建议按以下顺序：

id_verifications[].status：OCR 节点最终结果。
warnings[].log_type：该风险在当前 workflow 下是拒绝、审核还是信息提示。
warnings[].risk：稳定机器原因码。
warnings[].additional_data：特定风险的补充结构。
short_description / long_description：只用于后台展示和排障。

6. 前端引导

情况	建议动作
SDK `Cancelled`	允许重新开始
SDK `NetworkError`	提示检查网络后重试
SDK `CameraAccessDenied`	引导打开相机权限
Session `In Progress`	继续等待或轮询，不重复创建 Session
Session `In Review`	显示审核中
Session `Declined`	读取失败节点和 warnings 决定重拍、更换证件或联系客服
Session `Expired` / `Abandoned`	创建新 Session

7. 安全与留痕

API Key 只能放服务端 Secret。
Webhook 必须验签并做幂等处理。
保存原始 Webhook 与最终 Decision，便于审计和供应商 schema 变化后的重放。
证件图片、视频、短期签名 URL、OCR 原文和证件号不得进入 App 日志、Crash 平台或分析埋点。
只在合法、必要且有明确留存期限时下载证件媒体至受控存储。

Didit OCR 与证件防伪接入说明 ​

LLM 速览 ​

1. 生产主链路 ​

2. 接口清单 ​

3. OCR 字段 ​

4. 证件防伪 ​

5. 判断优先级 ​

6. 前端引导 ​

7. 安全与留痕 ​