概述
选择合约
合约的选择取决于生物特征采集发生的位置，而非独立决策。请参考下表进行选择。
| 合约 | 使用场景 | 采集方 | 流程 |
|---|---|---|---|
| Web & SDK | 采集流程由 Unico 托管（Web iFrame、重定向或原生 SDK） | Unico 控制 | 在采集前创建流程 → 用户完成流程 → 结果通过回调或轮询返回 |
| API | 您的应用控制采集（使用或不使用 Unico SDK），并在请求中直接发送图像 | 客户端控制 | 图像与流程创建同时发送 → 结果同步返回 |
主机与环境
| 合约 | 沙箱主机 | 生产主机 |
|---|---|---|
| Web & SDK | https://api.idcloud.uat.unico.app | https://api.idcloud.unico.app |
| API | https://api.id.uat.unico.app | https://api.id.unico.app |
| OAuth2 / Token | https://identityhomolog.acesso.io | https://identity.acesso.io |
详细信息请参阅环境。
认证
所有 Unico 合约均使用通过 OAuth2（urn:ietf:params:oauth:grant-type:jwt-bearer）获取的 Bearer token（JWT）。
详细信息请参阅认证。
各合约间的请求体差异
同一概念操作（"创建身份验证流程"）在各合约中的表现形式不同。在不同集成之间迁移时，可将下表作为快速参考。
流程创建
| 方面 | Web & SDK | API |
|---|---|---|
| 端点 | POST /client/v1/process | POST /processes/v1 |
| 认证 | Authorization: Bearer <jwt> | Authorization: Bearer <jwt> + APIKEY |
| 图像 | 不发送（由 Unico 的流程采集） | 以 imageBase64 形式发送 |
| 用户标识 | person.duiType + person.duiValue | subject.code（CPF / CURP） |
| 证件类型 | CPF、CURP、SSN、NIN、DNI、NIK | 仅 CPF、CURP |
| 流程定义 | flow（枚举，30+ 个值） | 隐含在 APIKEY 中（能力） |
| 回调 | callbackUri（用户重定向） | 无（同步） |
| Webhook | Webhook v1（最终结果） | Webhook v1（可选） |
| 返回跳转 URL | 是（userRedirectUrl） | 否 |
| 结果 | 异步（GET 轮询或 webhook） | 同步（在响应中） |
| SDK token | 是（token、webAppToken） | 否 |
结果获取
| 方面 | Web & SDK | API |
|---|---|---|
| 端点 | GET /client/v1/process/\{id\} | GET /processes/v1/\{id\}（也在创建响应中） |
| 状态 | state + result（带前缀的枚举） | status（1、3、5） |
| 结果结构 | 嵌套在 process.authenticationInfo.{capability}Result 下 | 扁平化：unicoId、liveness、government、identityFraudsters |
| 文件 | services[].documents[]（带 OCR 的 RG/CNH） | 单独端点（GET /processes/v1/\{id\}/document） |
下一步
- 认证 — OAuth2 流程与 JWT 生成
- 环境 — 沙箱与生产环境
- Postman Collection — 即用型集合
- Webhook 与事件 — 异步结果推送
- SDK 与工具 — Web SDK、Android、iOS、Flutter