开发者文档
官网控制台

提交 KYB

POST
/openapi/v1/customers/provider-kyc

向渠道提交或重新提交客户的企业 KYC。首次提交时在渠道建档。

请求为 multipart/form-data：data 部分是 JSON 资料，其余每个部分是一个文件，部分名等于 documents[].clientFileId。文件部分与 clientFileId 必须一一对应。

  • 渠道已受理（SUBMITTED 或 APPROVED）时，返回当前状态，不写资料，不带 submittedAt。
  • Idempotency-Key 必填，用于审计关联。超时后用同一份资料和原键重试。
  • 耗时视文件数量，可能超过 30 秒。客户端超时建议不低于 60 秒。
  • 本地只做组装和安全所需的最小校验：必需字段非空、data 无未知字段、personId 与 clientFileId 不重复、文件对应关系、单文件不超过 2 MB、文件头为 PDF、PNG 或 JPEG。
  • 字段格式、取值、人员角色数量、必备文件等规则由渠道判定，不符合时返回 openapi.channel.rejected。

字段说明里的长度和取值是渠道规则，由渠道校验。完整示例见 渠道 KYC 与开户。

鉴权

bearerAuth
header鉴权Bearer <令牌>

通过 POST /oauth2/token 获取的 access_token。请求头格式为 Authorization: Bearer {accessToken}。

Header 参数

X-Channel-Provider*string

渠道提供商标识。渠道侧 KYC 当前只支持 LEGEND。

Idempotency-Key*string

唯一请求标识，最长 128 字符。重试同一次提交时复用原键。缺失返回 error.idempotent.key.missing。

请求体

multipart/form-data
  1. body

data 部分加文件部分。每个文件部分的部分名等于一个 documents[].clientFileId。

data*

提交 KYB 的资料，作为 multipart 的 data 部分。未知字段会被拒绝。

[key: string]?unknown

文件内容。部分名为 clientFileId。单个文件不超过 2 MB，类型限 PDF、PNG、JPEG。

响应体

返回提交结果。审核结果另由查询接口或 provider.kyc.* Webhook 获取。

application/json
  1. response
code?integer

业务状态码

message?string
traceId?string

请求追踪 ID。联系技术支持时请提供

data?

提交结果。

请求示例
curl -X POST 'https://api.test.stabofx.com/openapi/v1/customers/provider-kyc' \  -H 'X-Channel-Provider: LEGEND' \  -H 'Idempotency-Key: 5f0c7b2e-1d3a-4c8e-9b6f-2a4d6e8f0a1c' \  -F 'data={  "customerUid": "cust_example_001",  "company": {    "phone": {},    "registeredAddress": {},    "businessAddress": {}  },  "business": {},  "questionnaire": {},  "persons": [    {      "personId": "p1",      "roles": [        "REPRESENTATIVE"      ],      "phone": {},      "residentialAddress": {}    }  ],  "documents": [    {      "clientFileId": "business-address",      "type": "INCORPORATION"    }  ]}' \  -F 'property1=null' \  -F 'property2=null'
响应示例
{  "code": 200,  "message": "OK",  "traceId": "trace-uuid-string",  "data": {    "customerUid": "cust_example_001",    "status": "SUBMITTED",    "submittedAt": "2026-11-09T17:36:21.687+08:00"  }}