上传 KYC 图片
POST/openapi/v1/users/uploadKycImage| 项 | 内容 |
|---|---|
| 请求方法 | POST |
| 请求路径 | /openapi/v1/users/uploadKycImage |
| 请求类型 | multipart/form-data |
请求参数
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
file | file | 是 | 每次上传一个文件,最大 6MB;允许格式由用途和辅助证明类型决定,见下表。 |
purpose | string | 否 | 文件用途:DOCUMENT_FRONT、DOCUMENT_BACK、SELFIE 或 SUPPORTING_DOCUMENT。不传时按主证件图片规则校验。 |
supportingDocumentType | string | 条件 | 辅助证明材料类型,不是主证件类型。purpose=SUPPORTING_DOCUMENT 时必填,取值见下表;其他用途不传。 |
签名时 RAW_BODY 使用空字符串,规则见鉴权与签名。
文件用途 purpose
| 值 | 用途 | 允许格式 | supportingDocumentType |
|---|---|---|---|
| 不传 | 沿用主证件图片校验规则 | JPG、JPEG、PNG | 不传 |
DOCUMENT_FRONT | 主证件正面 | JPG、JPEG、PNG | 不传 |
DOCUMENT_BACK | 主证件背面 | JPG、JPEG、PNG | 不传 |
SELFIE | 自拍照片 | JPG、JPEG、PNG | 不传 |
SUPPORTING_DOCUMENT | 辅助证明材料 | 按下表确定 | 必填 |
辅助证明类型 supportingDocumentType
按实际材料选择,没有默认值;枚举值区分大小写,须使用表中的大写值。
| 材料 | 值 | 允许格式 |
|---|---|---|
| 有效香港工作签证 | WORK_VISA | 仅 PDF |
| 雇佣合同 | EMPLOYMENT_CONTRACT | 仅 PDF |
| 工资单 | SALARY_PAYSLIP | 仅 PDF |
| 租赁协议 | TENANCY_AGREEMENT | 仅 PDF |
| 住址证明 | ADDRESS_PROOF | 仅 PDF |
| 银行对账单 | BANK_STATEMENT | 仅 PDF |
| 访港证明 | PROOF_OF_VISIT | 仅 PDF |
| 香港入境许可 | IMMIGRATION_ENDORSEMENT | JPG、JPEG、PNG、PDF |
| 通行证正面 | TRAVEL_PERMIT_FRONT | JPG、JPEG、PNG、PDF |
| 通行证背面 | TRAVEL_PERMIT_BACK | JPG、JPEG、PNG、PDF |
UTILITY_BILL 不在当前上传接口支持范围内。文件扩展名、声明的 MIME 类型与实际内容须一致;未声明 MIME 或声明为 application/octet-stream 时,仍会检查扩展名与文件内容。仅修改扩展名不能将图片转换为 PDF。
请求示例
以下展示 multipart/form-data 表单字段;file 须选择实际文件,不是发送文件路径字符串。请求仍须携带鉴权 Header。
上传主证件正面,不传 supportingDocumentType:
text
file: front.jpg(文件,image/jpeg)
purpose: DOCUMENT_FRONT上传银行对账单 PDF:
text
file: statement.pdf(文件,application/pdf)
purpose: SUPPORTING_DOCUMENT
supportingDocumentType: BANK_STATEMENT上传后,在提交用户 KYC中使用返回的 url,不要使用 previewUrl。辅助证明的 documentType 应与上传时的 supportingDocumentType 保持一致,例如以下 KYC 请求片段:
json
{
"supportingDocuments": [
{
"documentType": "BANK_STATEMENT",
"fileUrl": "上传接口返回的 url"
}
]
}通行证正反面分别上传,正式提交 KYC 时须在 supportingDocuments 中成对提供 TRAVEL_PERMIT_FRONT 和 TRAVEL_PERMIT_BACK。上传成功仅代表文件通过上传校验,不代表 KYC 审核通过。
响应 data
| 字段 | 类型 | 说明 |
|---|---|---|
success | boolean | 是否处理成功。 |
code | string | 平台响应码。 |
message | string | 平台响应说明。 |
file | string/null | 历史兼容字段,当前平台上传流程不填充。 |
path | string/null | 历史兼容字段,当前平台上传流程不填充。 |
url | string | 稳定文件地址,用于保存和提交 KYC。私有文件不能通过此地址匿名预览。 |
previewUrl | string | 预览地址;私有桶返回有效期 120 秒的临时 GET 签名地址。仅用于预览,不用于提交 KYC。 |
previewExpiresAt | string / null | 预览签名的 UTC 过期时间,ISO 8601 格式,例如 2026-10-12T02:02:00Z;未生成签名时为空。 |
contentType | string | 文件 MIME 类型。 |
size | integer | 文件大小,单位字节。 |
originalName | string | 原始文件名。 |
previewUrl 和过期时间来自同一次签名。公开存储配置的预览地址与 url 相同,previewExpiresAt 为空。签名过期后无法继续发起读取;本接口不提供签名刷新功能。
