该接口用于在企业KYB流程中添加新的代表人（Representative）信息。通过提交代表人的个人基本信息、联系方式、地址信息以及相关证明文件，完成企业关键人员（如董事、高管、实际控制人等）的身份信息采集。
所有证明文件必须提前通过 /app/kyc/entity/file 上传，并在本接口的对应文档字段中传入返回的 file_hash 值。
注意：最多只能添加两个代表，否则返回：
{
"request_id": "a8eef6529f82bce68ed8b1853c6927e1",
"status": "fail",
"code": "910002",
"message": "data failed, please try again.",
"data": [],
"metadata": {}
}
首先调用 file 接口上传二进制文件，响应会返回如下文件信息：
| 字段名 | 类型 | 说明 |
|---|
| file_hash | string | 文件哈希，用作唯一标识与校验 |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| uid | string | 是 | 用户ID，用于标识当前操作的企业用户 |
| uuid | string | 否 | 如果传表示修改，为空表示新增 |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| first_name | string | 是 | 名 |
| middle_name | string | 否 | 中间名 |
| last_name | string | 是 | 姓 |
| aliases | string | 否 | 别名/曾用名 |
| position | string | 是 | 职位名称，如：Chief Executive Officer（首席执行官） |
| date_of_birth | string | 是 | 出生日期，格式：YYYY-MM-DD |
| place_of_birth | string | 是 | 出生地点 |
| nationality | array | 是 | 国籍列表，使用ISO 3166-1 alpha-2国家代码 |
| email | string | 是 | 电子邮箱 |
| is_critical_role | string | 是 | 是否为关键职位，可选值：Yes/No |
| related_officer | string | 是 | 是否关联高管，可选值：Yes/No |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| phone | object | 是 | 电话号码对象 |
phone对象结构：
| 字段名 | 类型 | 必填 | 说明 |
|---|
| phone_country_code | string | 是 | 电话国家代码（带+号），如：+1 |
| phone_country_code_short | string | 是 | 电话国家代码（短格式），如：US |
| phone_number | string | 是 | 电话号码 |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| country | string | 是 | 国家代码，如：US |
| state | string | 是 | 州/省，如：CA（加利福尼亚州） |
| city | string | 是 | 城市，如：San Francisco |
| zipcode | string | 是 | 邮政编码，如：94102 |
| address_1 | string | 是 | 地址第一行（详细街道地址） |
| address_2 | string | 否 | 地址第二行（补充信息，如公寓号、楼层等） |
重要：id_file、selfie_file、proof_of_residence_file 字段不接受原始文件上传。所有证明文件必须先通过 /app/kyc/entity/file 上传，并把返回的 file_hash 填入对应字段。
| 字段名 | 类型 | 必填 | 说明 |
|---|
| file_hash | string | 是 | 文件唯一标识ID |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| file_hash | string | 是 | 文件唯一标识ID |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| file_hash | string | 是 | 文件唯一标识ID |
| file_category | string | 是 | 证明类型，包含枚举：'utility_bill', 'bank_statement', 'credit_card_statement', 'lease_or_rental_agreement', 'mortgage_statement', 'mobile_bill' |
调用本接口前，请先通过 /app/kyc/entity/file 上传各文件，并在下表对应字段中填入返回的 file_hash。
/app/kyc/entity/rep 中的字段 | 通过 /app/kyc/entity/file 上传时的 file_type |
|---|
id_file | institution_rep_passport、institution_rep_dl_front、institution_rep_dl_back、institution_rep_id_card_front、institution_rep_id_card_back、institution_rep_residence_permit_front、institution_rep_residence_permit_back |
selfie_file | institution_rep_selfie |
proof_of_residence_file | institution_rep_residence |
{
"uid": "1123456",
//"uuid": "dfeqpBk3xaEWlYwZlm96XM1noRQLON2K", //传入则更新已有代表人记录，不传则新建
"first_name": "Tom",
"middle_name": "Michael",
"last_name": "Smith",
"aliases": "Johnny",
"position": "Chief Executive Officer",
"date_of_birth": "1985-06-15",
"place_of_birth": "US",
"nationality": ["US", "JP"],
"email": "[email protected]",
"phone": {
"phone_country_code": "+1",
"phone_country_code_short": "US",
"phone_number": "4155550101"
},
"country": "US",
"state": "CA",
"city": "San Francisco",
"zipcode": "94102",
"address_1": "123 Main Street, Apartment 5B",
"address_2": "Building A",
"is_critical_role": "Yes",
"related_officer": "No",
"id_file": [
{
"file_hash": "76fbf2b81341e4fd3bd9ce9a395fa54f"
}
],
"selfie_file": [
{
"file_hash": "70580af1292c0d4c43bbc408798c4a36"
}
],
"proof_of_residence_file": [
{
"file_hash": "70580af1292c0d4c43bbc408798c4a36",
"file_category":"utility_bill"
}
]
}
- 数据完整性：建议在提交前对必填字段进行验证，确保信息完整
- 文件上传：文件需先通过
/app/kyc/entity/file 上传接口获取 file_hash，再在本接口的对应字段中传入
- 关键角色标识：is_critical_role为"Yes"表示该人员为企业关键人员（如董事、实际控制人），可能需要额外的合规审查
