创建文档流程

此端点处理两种共享相同路径但请求体参数不同的文档流程：

• 新采集 — 以 base64 格式提交文档图像进行处理（需要 document.files）。
• 复用 — 通过引用之前采集的文档跳过采集步骤（需要 document.documentId）。

实际执行哪种流程取决于请求体中是否提供了 document.documentId。

在创建文档流程之前，请使用获取可复用文档检查用户是否已有可供复用的文档。

完整集成流程请参阅 API 概览。

端点

环境	URL
生产环境	POST https://api.id.unico.app/processes/v1
沙盒环境	POST https://api.id.uat.unico.app/processes/v1

请求

请求头

请求头	值
Authorization	Bearer <access_token>（参见身份验证）
APIKEY	已启用文档采集与复用功能的 API 密钥。
Content-Type	application/json

请求体参数

新采集

字段	类型	必填	描述
subject.duiType	string	是	标识符类型。可能的值：DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN、DUI_TYPE_NG_NIN、DUI_TYPE_AR_DNI、DUI_TYPE_ID_NIK。
subject.code	string	是	由 subject.duiType 定义的用户标识符值。不含点号或破折号。
subject.name	string	否	全名。
subject.gender	string	否	M 或 F。
subject.birthDate	string (ISO 8601)	否	出生日期（YYYY-MM-DD）。
subject.email	string	否	电子邮件地址。
subject.phone	string	否	E.164 格式电话号码。
document.purpose	string	是	业务目的。可选值：creditprocess、carpurchase、paybypaycheck、onboarding、fgts。
document.authProcessId	string	是	与此文档采集关联的生物特征流程 ID。
document.files	array	是	base64 格式的文档图像（正面和/或背面）。
document.files[].data	string	是	base64 格式的文档图像（PNG、JPEG 或 WebP，最大 800 KB）。
subsidiaryId	string	否	分支机构 ID — 仅在存在多个分支机构时需要。

复用

字段	类型	必填	描述
subject.duiType	string	是	标识符类型。可能的值：DUI_TYPE_BR_CPF、DUI_TYPE_MX_CURP、DUI_TYPE_US_SSN、DUI_TYPE_NG_NIN、DUI_TYPE_AR_DNI、DUI_TYPE_ID_NIK。
subject.code	string	是	由 subject.duiType 定义的用户标识符值。不含点号或破折号。
subject.name	string	否	全名。
subject.gender	string	否	M 或 F。
subject.birthDate	string (ISO 8601)	否	出生日期（YYYY-MM-DD）。
subject.email	string	否	电子邮件地址。
subject.phone	string	否	E.164 格式电话号码。
document.purpose	string	是	业务目的。可选值：creditprocess、carpurchase、paybypaycheck、onboarding、fgts。
document.authProcessId	string	是	与此文档关联的生物特征流程 ID。
document.documentId	string	是	之前采集的文档 ID（从获取可复用文档获取）。提供此值时，document.files 可省略。
subsidiaryId	string	否	分支机构 ID — 仅在存在多个分支机构时需要。

示例

新采集 — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909",
      "name": "Luke Skywalker"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "files": [
        { "data": "/9j/4AAQSkZJR..." }
      ]
    }
  }'

新采集 — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909',
      name: 'Luke Skywalker'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      files: [{ data: documentImageBase64 }]
    }
  })
});

const result = await res.json();

复用 — cURL

curl -X POST https://api.id.unico.app/processes/v1 \
  -H "Authorization: Bearer $TOKEN" \
  -H "APIKEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": {
      "duiType": "DUI_TYPE_BR_CPF",
      "code": "12345678909"
    },
    "document": {
      "purpose": "onboarding",
      "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6",
      "documentId": "doc-abc-123"
    }
  }'

复用 — Node.js

import fetch from 'node-fetch';

const res = await fetch('https://api.id.unico.app/processes/v1', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.UNICO_ACCESS_TOKEN}`,
    'APIKEY': process.env.UNICO_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    subject: {
      duiType: 'DUI_TYPE_BR_CPF',
      code: '12345678909'
    },
    document: {
      purpose: 'onboarding',
      authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6',
      documentId: 'doc-abc-123'
    }
  })
});

const result = await res.json();

响应

200 OK

{
  "id": "80371b2a-3ac7-432e-866d-57fe37896ac6",
  "status": 3,
  "document": {
    "id": "doc-abc-123",
    "type": "unico.moja.dictionary.br.cnh.v2.Cnh",
    "cpfMatch": true,
    "faceMatch": true,
    "content": {
      "numero": "12345678",
      "nomeCivil": "Luke Skywalker",
      "dataNascimento": "2000-05-20T00:00:00Z",
      "categoria": "B",
      "dataExpiracao": "2030-05-20T00:00:00Z"
    },
    "fileUrls": [
      "https://storage.unico.app/documents/doc-abc-123/front.jpg"
    ]
  }
}

字段	类型	描述
id	string (UUID)	流程标识符。
status	integer	3（成功完成），5（失败完成）。
document.id	string	采集的文档标识符。可在后续请求的 document.documentId 中使用此值进行复用。
document.type	string	识别到的文档类型。可能的值：unico.moja.dictionary.br.rg.v2.Rg、unico.moja.dictionary.br.cnh.v2.Cnh、unico.moja.dictionary.br.cin.v1.Cin、unico.moja.dictionary.br.passaporte.v1.Passaporte。
document.cpfMatch	boolean	若从文档中提取的标识符与 subject.code 匹配，则为 true。
document.faceMatch	boolean	若文档人脸与 document.authProcessId 中的生物特征自拍匹配，则为 true。
document.content	object	通过 OCR 提取的字段。结构因文档类型而异 — 见下文。
document.fileUrls	array	用于下载文档图像的临时 URL（有效期 10 分钟）。

400 Bad Request

请求体格式错误、图像无效或缺少必填字段。参见下方错误代码。

403 Forbidden

Bearer 令牌或 APIKEY 缺失、已过期或无效。参见身份验证。

409 Conflict

提供的 processId 在此租户中已存在。参见下方错误代码。

错误代码

400 Bad Request

代码	消息	描述
99989	The document is invalid.	document 对象结构无效。
99988	The document is empty.	请求体中缺少 document 对象。
20900	O base64 informado não é válido.	base64 参数无效。可能原因：不是图像或存在注入攻击。
20807	A imagem precisa estar no padrão HD ou possuir uma resolução superior a 640 x 480.	上传的图像分辨率过低。
20509	The subject.name field is invalid.	subject.name 包含无效字符。
20508	The subject.gender field is invalid.	subject.gender 必须为 M 或 F。
20507	O parâmetro subject.code é inválido.	标识符值格式非标准或不存在。
20506	O base64 informado é muito grande. O tamanho máximo suportado é até 800kb.	图像大小超过 800 KB；请压缩为 JPEG92。
20505	O base64 informado não é suportado. Os formatos aceitos são png, jpeg e webp.	base64 格式无效或不受支持。
20068	The document.documentId or document.files parameter must be present.	document.documentId 和 document.files 均未提供。
20067	The document.purpose parameter is invalid.	document.purpose 中的值无法识别。
20066	The document.authProcessId parameter is invalid.	document.authProcessId 中的值无效。
20062	The useCase field is invalid.	useCase 字段中的值无法识别。
20021	The subject.phone field is invalid.	subject.phone 格式无效（国际区号 + 区号 + 号码，共 13 位字符）。
20019	The subject.birthDate field is invalid.	subject.birthDate 不符合 ISO 8601 格式（YYYY-MM-DD）。
20009	O parâmetro imagebase64 não foi informado.	缺少文档图像参数。
20008	The subject.email field is invalid.	subject.email 中的邮箱格式无效。
20005	O parâmetro subject.code não foi informado.	缺少 subject.code 参数。
20004	O parâmetro subject não foi informado.	缺少 subject 参数。
20003	The request body is missing or invalid.	负载为空或无效。
20002	O parâmetro APIKey não foi informado.	请求头中缺少 APIKEY 参数。
20001	O parâmetro authtoken não foi informado.	请求头中缺少集成令牌参数。
10508	The JWT with the captured face has already been used.	JWT 只能使用一次。
10507	The JWT with the captured face is expired.	JWT 已过期；必须在 10 分钟内发送。
10506	The imageBase64 field is not a valid JWT from SDK.	imageBase64 不是 SDK 生成的有效 JWT。

403 Forbidden

代码	消息	描述
30017	User does not have permission to perform this action.	JWT 格式错误或用户无权执行此操作。
10502	O token informado está expirado.	access-token 已过期。
10501	O token informado é inválido.	身份验证令牌无效。
10201	O AppKey informado é inválido.	APIKEY 无效或不存在。

409 Conflict

代码	消息	描述
20073	The processID already exists.	提供的 processId 在此租户中已存在。

500 Internal Server Error

代码	消息	描述
99999	Internal failure! Try again later	发生内部错误。

下一步

• 在调用此端点之前检查文档是否已可用，请参阅获取可复用文档。
• 有关生物特征流程创建（document.authProcessId 必需），请参阅创建流程。