SmileID SmartSelfie Compare 接入说明

官方文档：https://docs.usesmileid.com/products/for-individuals-kyc/smartselfie-tm-compare

LLM 速览

SmartSelfie Compare 是 SmileID 的一次性人脸比对能力，用于把用户当前自拍和活体图，与一张已存在的参考照片进行比对。它适合开户链接里“当前人脸 vs 证件照 / 存档照片 / 主管部门照片”的 KYC 场景。

关键结论：

集成方式：REST API。
请求格式：multipart/form-data。
调用方：建议由第三层身份核验整合系统在后台调用，不建议 App 直连。
图片要求：selfie_image 1 张，comparison_image 1 张，liveness_images 至少 4 张、最多 8 张。
返回方式：同步返回结果，也可以配置 callback_url 接收传统格式回调。
通过码：0840 表示 Face Match。
不通过码：0841 表示 No Face Match，0941 表示图片同源或自拍无清晰人脸等问题。

1. 适用场景

场景	是否适合	说明
当前自拍和 NIDA / 证件照做一次性比对	是	传入 `comparison_image_type = ID_PHOTO` 更贴近该场景
当前自拍和存档头像做一次性比对	是	参考图可按来源选择 `ID_PHOTO` 或 `PORTRAIT`
用户首次注册人脸，后续反复刷脸认证	否	应考虑 SmartSelfie Enrollment / Authentication
只用 SDK 采集自拍图和活体图	部分适合	SDK 可采集图片，最终 Compare 建议由后台提交

2. 接口地址

环境	Method	Endpoint
Sandbox	`POST`	`https://testapi.smileidentity.com/v2/smart-selfie-compare`
Production	`POST`	`https://api.smileidentity.com/v2/smart-selfie-compare`

Content-Type：

http

multipart/form-data

如果 HTTP 客户端会自动生成 boundary，不要手动拼完整 Content-Type。

3. 请求认证

SmartSelfie Compare 使用 header-based authentication。请求头需要携带：

Header	是否必填	说明
`SmileID-Timestamp`	是	生成签名时使用的 ISO 8601 时间戳
`SmileID-Partner-ID`	是	SmileID Partner ID
`SmileID-Request-Signature`	是	按官方签名规则生成的请求签名

时间戳要求：

text

2025-05-23T11:40:07.809Z

注意：

时间戳要带 3 位毫秒。
时间戳必须和签名计算时使用的值一致。
每次请求都应重新生成时间戳和签名。
Sandbox 与 Production 的 Partner ID、API Key、签名不能混用。

4. 请求参数

请求体使用 multipart/form-data。

字段	类型	是否必填	说明
`user_id`	string	是	业务侧用户唯一标识
`selfie_image`	file	是	用户自拍图
`comparison_image`	file	是	用于比对的参考图片
`comparison_image_type`	string	是	参考图片类型
`liveness_images`	file	是	活体图，至少 4 张、最多 8 张，建议 8 张
`partner_params`	object	是	合作方透传参数对象
`callback_url`	string	是	SmileID 回调结果接收地址

4.1 comparison_image_type

值	适用图片
`ID_PHOTO`	证件照、权威机构照片、主管部门返回照片
`PORTRAIT`	普通人像照片或历史头像
`DOCUMENT`	证件文档照片

传音银行开户注册场景里，如果参考图来自 NIDA / 证件照，优先按 ID_PHOTO 处理。

4.2 partner_params

partner_params 是 JSON object，官方列出的核心字段包括：

字段	是否必填	说明
`job_id`	是	你方生成的唯一任务 ID
`user_id`	是	你方生成的唯一用户 ID
`allow_new_enroll`	否	是否允许同一 `user_id` 重新 enroll，默认 `false`

可以额外放入开户申请号、渠道、业务线等透传字段，SmileID 会在响应或回调中返回。

4.3 liveness_images

liveness_images 需要一张一张作为同名 form-data 字段提交，不要打包成数组字段。

text

liveness_images=@live1.jpg
liveness_images=@live2.jpg
liveness_images=@live3.jpg
liveness_images=@live4.jpg

5. 示例请求

bash

curl --request POST 'https://testapi.smileidentity.com/v2/smart-selfie-compare' \
  --header 'SmileID-Timestamp: 2025-05-23T11:40:07.809Z' \
  --header 'SmileID-Partner-ID: 0000' \
  --header 'SmileID-Request-Signature: xxxx' \
  --form 'user_id="user-123"' \
  --form 'selfie_image=@"/path/selfie.jpg"' \
  --form 'comparison_image=@"/path/comparison.jpg"' \
  --form 'comparison_image_type="ID_PHOTO"' \
  --form 'liveness_images=@"/path/live1.jpg"' \
  --form 'liveness_images=@"/path/live2.jpg"' \
  --form 'liveness_images=@"/path/live3.jpg"' \
  --form 'liveness_images=@"/path/live4.jpg"' \
  --form 'callback_url="https://your-domain.com/smileid/callback"' \
  --form 'partner_params={"job_id":"job-001","user_id":"user-123","channel":"app"}'

6. 响应字段

常见字段：

字段	说明
`code`	结果码，例如 `0840` / `0841`
`message`	结果文本，例如 `Match` / `No Match`
`job_id`	任务 ID
`user_id`	用户 ID
`partner_id`	Partner ID
`job_type`	Job 类型
`partner_params`	你方透传参数
`created_at`	创建时间
`updated_at`	更新时间
`status`	状态，例如 `approved` / `rejected`
`SmileJobID`	SmileID 内部 job 标识

结果码：

结果码	含义	业务结论
`0840`	Face Match	通过
`0841`	No Face Match	不通过
`0941`	图片同源或自拍无清晰人脸等情况	不通过

常见错误码：

结果码	含义
`2204`	请求参数类型错误
`2205`	签名错误或未授权
`2209`	同一用户已注册，且不允许重新 enroll
`2214`	产品未激活
`2215`	`job_id` 已存在
`2220`	生产环境未启用
`2413`	必填输入不正确，例如活体图或比对图有问题

7. 示例响应

比对成功：

json

{
  "code": "0840",
  "message": "Match",
  "job_id": "job-001",
  "user_id": "user-123",
  "partner_id": "0000",
  "partner_params": {
    "job_id": "job-001",
    "user_id": "user-123",
    "channel": "app"
  },
  "status": "approved",
  "created_at": "2025-05-23T11:40:07.809Z",
  "updated_at": "2025-05-23T11:40:08.120Z"
}

比对不通过：

json

{
  "code": "0841",
  "message": "No Match",
  "job_id": "job-001",
  "user_id": "user-123",
  "status": "rejected"
}

8. 推荐接入流程

text

App 采集自拍图和活体图
  -> App 上传图片到第三层身份核验整合系统
  -> 第三层系统取得证件照 / NIDA 参考图
  -> 第三层系统生成 user_id、job_id、timestamp、signature
  -> 第三层系统 POST SmartSelfie Compare
  -> 第三层系统解析同步结果并保存原始响应
  -> SmileID callback_url 回调结果作为兜底和归档
  -> 第三层系统返回 KYC 判断给 App / 客户信息域

9. 接入注意事项

job_id 每次请求必须唯一。
user_id 建议使用业务系统内稳定用户标识。
liveness_images 要按多条同名 form-data 字段传入。
comparison_image_type 要按真实参考图来源选择；证件照通常用 ID_PHOTO。
不要在 App 端保存或暴露 SmileID API Key。
同步响应和 callback_url 建议都入库，便于审计、补偿和问题排查。
官方说明该接口没有人工审核阶段，因此不应按 PENDING / PROVISIONAL 人工复核态设计主流程。

SmileID SmartSelfie Compare 接入说明 ​

LLM 速览 ​

1. 适用场景 ​

2. 接口地址 ​

3. 请求认证 ​

4. 请求参数 ​

4.1 comparison_image_type ​

4.2 partner_params ​

4.3 liveness_images ​

5. 示例请求 ​

6. 响应字段 ​

7. 示例响应 ​

8. 推荐接入流程 ​

9. 接入注意事项 ​

SmileID SmartSelfie Compare 接入说明

LLM 速览

1. 适用场景

2. 接口地址

3. 请求认证

4. 请求参数

4.1 comparison_image_type

4.2 partner_params

4.3 liveness_images

5. 示例请求

6. 响应字段

7. 示例响应

8. 推荐接入流程

9. 接入注意事项