创建文档流程

MarkdownChatGPTClaude

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

• 新采集 — 以 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	integer	是	文档类型标识符。请参阅下方的 duiType 值。
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 值。
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 — 仅在存在多个分支机构时需要。

duiType 值

国家	代码	描述
AR	6	阿根廷护照
AR	7	阿根廷 DNI
AR	49	阿根廷驾驶证（Licencia Nacional de Conducir）
AT	34	奥地利税号（STNR）
BE	36	比利时国家号码（NN）
BR	1	巴西 CPF
BR	5	巴西护照
BR	14	巴西 CNPJ
CA	28	加拿大 SIN
CH	33	瑞士 AHV/AVS 号码
CL	9	智利 RUN
CL	52	智利护照
CL	57	智利驾驶证（Licencia de Conducir）
CO	26	哥伦比亚 NIT
CO	53	哥伦比亚护照
CO	55	哥伦比亚驾驶证（Licencia de Conducción）
CO	56	哥伦比亚公民身份证（Cédula de Ciudadanía）
DE	41	德国税务识别号码（IdNr）
DK	29	丹麦 CPR
EC	10	厄瓜多尔 NI
ES	50	西班牙外国人身份号码（NIE）
ES	51	西班牙国民身份证（DNI）
FI	35	芬兰个人身份代码（HETU）
FR	46	法国税务参考号码（SPI）
GB	30	英国国民保险号码（NINO）
GT	12	危地马拉 CUI
ID	16	印度尼西亚 NIK
IE	47	爱尔兰个人公共服务号码（PPSN）
IT	37	意大利税务代码（CF）
LU	48	卢森堡国民身份号码（Matricule）
MX	2	墨西哥 CURP
MX	25	墨西哥 RFC（自然人）
MX	58	墨西哥驾驶证（Licencia de Conducir）
NG	8	尼日利亚 NIN
NG	20	尼日利亚银行验证号码（BVN）
NG	43	尼日利亚 BVN 令牌（哈希）
NG	44	尼日利亚 NIN 令牌（哈希）
NL	42	荷兰公民服务号码（BSN）
NO	39	挪威国民身份号码（Fødselsnummer）
PE	27	秘鲁 RUC
PE	40	秘鲁 DNI
PE	54	秘鲁护照
PL	31	波兰 PESEL
PT	45	葡萄牙税务识别号码（NIF）
SE	32	瑞典个人号码（PNR）
SE	38	瑞典协调号码（Samordningsnummer）
TR	24	土耳其身份证号码（TCKN）
US	4	美国 SSN
US	11	美国护照
US	18	美国驾驶执照
US	21	美国护照卡
US	22	美国聚碳酸酯护照
US	23	美国身份证
UY	13	乌拉圭 CI
ZZ	15	电子邮件地址
ZZ	17	电话号码
—	0	未指定
—	3	Unico 内部标识符

示例

新采集 — 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": 1,
      "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: 1,
      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": 1,
      "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: 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.cpfMatch	boolean	若从文档中提取的标识符与 subject.code 匹配，则为 true。
document.faceMatch	boolean	若文档人脸与 document.authProcessId 中的生物特征自拍匹配，则为 true。
document.content	object	通过 OCR 提取的字段。结构因文档类型而异 — 点击此处查看字段详情。
document.fileUrls	array	用于下载文档图像的临时 URL（有效期 10 分钟）。

document.content 中仅包含成功提取的字段；OCR 无法读取的内容会被省略，而不是返回为空。

document.type 值

统一架构

所有使用统一架构的文档类型（即字段参考中的 unified_schema）在 document.type 中均以 unico.moja.dictionary.<country>.generic.v1.<DocumentType> 的形式返回，其中 <country> 是小写的 ISO 3166-1 alpha-2 代码，<DocumentType> 是识别到的类型。例如：

• unico.moja.dictionary.ar.generic.v1.IdCard: 阿根廷身份证
• unico.moja.dictionary.us.generic.v1.PolycarbonatePassport: 美国聚碳酸酯护照

专用架构

使用各自专用字段架构的文档类型（列于字段参考的 specific_document_schemas 之下）如下表所示：

国家/地区	值	文档
BR	unico.moja.dictionary.br.rg.v2.Rg	RG
BR	unico.moja.dictionary.br.cnh.v2.Cnh	CNH（驾照）
BR	unico.moja.dictionary.br.cin.v1.Cin	CIN
BR	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 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

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

代码	消息	描述
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 必需），请参阅创建流程。