--- title: 创建文档流程 description: 采集新文档，或复用与生物特征流程关联的已采集文档。 canonical: https://developer.unico.io/zh-CN/dual-api/developers/api-reference/api/post-processes-document locale: zh-CN generated_by: markdown-export --- - [/zh-CN/](/zh-CN/) - [API 参考](/zh-CN/dual-api/developers/api-reference/) - [API](/zh-CN/dual-api/developers/api-reference/api/) - 创建文档流程 **本页内容# 创建文档流程 此端点处理两种共享相同路径但请求体参数不同的文档流程： **新采集** — 以 base64 格式提交文档图像进行处理（需要 `document.files`）。 **复用** — 通过引用之前采集的文档跳过采集步骤（需要 `document.documentId`）。 实际执行哪种流程取决于请求体中是否提供了 `document.documentId`。 在创建文档流程之前，请使用[获取可复用文档](/zh-CN/dual-api/developers/api-reference/api/get-document)检查用户是否已有可供复用的文档。 完整集成流程请参阅 [API 概览](/zh-CN/dual-api/developers/api-reference/api/)。 ### 端点​ 环境URL**生产环境**`POST https://api.id.unico.app/processes/v1`**沙盒环境**`POST https://api.id.uat.unico.app/processes/v1` ### 请求​ 请求头 请求头值`Authorization``Bearer `（参见[身份验证](/zh-CN/dual-api/developers/api-reference/authentication)）`APIKEY`已启用文档采集与复用功能的 API 密钥。`Content-Type``application/json` 请求体参数 新采集复用字段类型必填描述`subject.duiType`integer是文档类型标识符。请参阅下方的 [`duiType` 值](#duitype-values)。`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`integer是文档类型标识符。请参阅下方的 [`duiType` 值](#duitype-values)。`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（从[获取可复用文档](/zh-CN/dual-api/developers/api-reference/api/get-document)获取）。提供此值时，`document.files` 可省略。`subsidiaryId`string否分支机构 ID — 仅在存在多个分支机构时需要。 **`duiType` 值**国家代码描述AR6阿根廷护照AR7阿根廷 DNIAR49阿根廷驾驶证（Licencia Nacional de Conducir）AT34奥地利税号（STNR）BE36比利时国家号码（NN）BR1巴西 CPFBR5巴西护照BR14巴西 CNPJCA28加拿大 SINCH33瑞士 AHV/AVS 号码CL9智利 RUNCL52智利护照CL57智利驾驶证（Licencia de Conducir）CO26哥伦比亚 NITCO53哥伦比亚护照CO55哥伦比亚驾驶证（Licencia de Conducción）CO56哥伦比亚公民身份证（Cédula de Ciudadanía）DE41德国税务识别号码（IdNr）DK29丹麦 CPREC10厄瓜多尔 NIES50西班牙外国人身份号码（NIE）ES51西班牙国民身份证（DNI）FI35芬兰个人身份代码（HETU）FR46法国税务参考号码（SPI）GB30英国国民保险号码（NINO）GT12危地马拉 CUIID16印度尼西亚 NIKIE47爱尔兰个人公共服务号码（PPSN）IT37意大利税务代码（CF）LU48卢森堡国民身份号码（Matricule）MX2墨西哥 CURPMX25墨西哥 RFC（自然人）MX58墨西哥驾驶证（Licencia de Conducir）NG8尼日利亚 NINNG20尼日利亚银行验证号码（BVN）NG43尼日利亚 BVN 令牌（哈希）NG44尼日利亚 NIN 令牌（哈希）NL42荷兰公民服务号码（BSN）NO39挪威国民身份号码（Fødselsnummer）PE27秘鲁 RUCPE40秘鲁 DNIPE54秘鲁护照PL31波兰 PESELPT45葡萄牙税务识别号码（NIF）SE32瑞典个人号码（PNR）SE38瑞典协调号码（Samordningsnummer）TR24土耳其身份证号码（TCKN）US4美国 SSNUS11美国护照US18美国驾驶执照US21美国护照卡US22美国聚碳酸酯护照US23美国身份证UY13乌拉圭 CIZZ15电子邮件地址ZZ17电话号码—0未指定—3Unico 内部标识符 ### 示例​ 新采集 — cURL新采集 — Node.js复用 — cURL复用 — Node.js``` 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": 1, "code": "12345678909", "name": "Luke Skywalker" }, "document": { "purpose": "onboarding", "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6", "files": [ { "data": "/9j/4AAQSkZJR..." } ] } }' ``` ``` 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: 1, code: '12345678909', name: 'Luke Skywalker' }, document: { purpose: 'onboarding', authProcessId: '80371b2a-3ac7-432e-866d-57fe37896ac6', files: [{ data: documentImageBase64 }] } })});const result = await res.json(); ``` ``` 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": 1, "code": "12345678909" }, "document": { "purpose": "onboarding", "authProcessId": "80371b2a-3ac7-432e-866d-57fe37896ac6", "documentId": "doc-abc-123" } }' ``` ``` 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: 1, 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识别到的文档类型，以完全限定的字典名称表示。请参阅下方的 [`document.type` 值](#document-type-values)。`document.cpfMatch`boolean若从文档中提取的标识符与 `subject.code` 匹配，则为 `true`。`document.faceMatch`boolean若文档人脸与 `document.authProcessId` 中的生物特征自拍匹配，则为 `true`。`document.content`object通过 OCR 提取的字段。结构因文档类型而异 — [点击此处查看字段详情](/zh-CN/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)。`document.fileUrls`array用于下载文档图像的临时 URL（有效期 10 分钟）。 `document.content` 中仅包含成功提取的字段；OCR 无法读取的内容会被省略，而不是返回为空。 **`document.type` 值**统一架构所有使用统一架构的文档类型（即[字段参考](/zh-CN/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)中的 `unified_schema`）在 `document.type` 中均以 `unico.moja.dictionary..generic.v1.` 的形式返回，其中 `` 是小写的 ISO 3166-1 alpha-2 代码，`` 是识别到的类型。例如： `unico.moja.dictionary.ar.generic.v1.IdCard`: 阿根廷身份证 `unico.moja.dictionary.us.generic.v1.PolycarbonatePassport`: 美国聚碳酸酯护照 专用架构使用各自专用字段架构的文档类型（列于[字段参考](/zh-CN/assets/files/document-content-fields-0e4663f2ade946e901bbc7523c21f032.json)的 `specific_document_schemas` 之下）如下表所示：国家/地区值文档BR`unico.moja.dictionary.br.rg.v2.Rg`RGBR`unico.moja.dictionary.br.cnh.v2.Cnh`CNH（驾照）BR`unico.moja.dictionary.br.cin.v1.Cin`CINBR`unico.moja.dictionary.br.passaporte.v1.Passaporte`护照MX`unico.moja.dictionary.mx.ine.v1.Ine`INE 选民证MX`unico.moja.dictionary.mx.lpc.v1.Lpc`Licencia para conducir（驾照）MX`unico.moja.dictionary.mx.pasaporte.v1.Pasaporte`护照—`unico.moja.dictionary.other.unknown.v1.Unknown`无法识别类型 — `document.content` 为空当 `document.type` 为 `unico.moja.dictionary.other.unknown.v1.Unknown` 时，不执行 OCR 提取，也不返回任何字段。 ### 错误代码​ 400 Bad Request403 Forbidden409 Conflict500 Internal Server Error代码消息描述`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。Bearer 令牌或 `APIKEY` 缺失、已过期或无效。参见[身份验证](/zh-CN/dual-api/developers/api-reference/authentication)。代码消息描述`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 无效或不存在。代码消息描述`20073`The processID already exists.提供的 `processId` 在此租户中已存在。代码消息描述`99999`Internal failure! Try again later发生内部错误。 ### 下一步​ 在调用此端点之前检查文档是否已可用，请参阅[获取可复用文档](/zh-CN/dual-api/developers/api-reference/api/get-document)。 有关生物特征流程创建（`document.authProcessId` 必需），请参阅[创建流程](/zh-CN/dual-api/developers/api-reference/api/post-processes)。 最后更新 于 2026年10月8日**