该接口用于在企业KYB流程中添加新的实际受益人（Beneficial Owner）信息。实际受益人是指直接或间接持有企业一定比例股份或拥有最终控制权的自然人。通过提交受益人的个人信息、持股比例、联系方式、地址信息以及相关证明文件，完成企业实际控制人的身份信息采集，满足反洗钱（AML）和了解你的客户（KYC）合规要求。
首先调用 file 接口上传二进制文件，响应会返回如下文件信息：
| 字段名 | 类型 | 说明 |
|---|
| file_hash | string | 文件哈希，用作唯一标识与校验 |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| uid | string | 是 | 用户ID，用于标识当前操作的企业用户 |
| uuid | string | 否 | 受益人唯一编号，如传递，表示修改，否则新增 |
| 字段名 | 类型 | 必填 | 说明 |
|---|
| first_name | string | 是 | 名 |
| middle_name | string | 否 | 中间名 |
| last_name | string | 是 | 姓 |
| aliases | string | 否 | 别名/曾用名 |
| share_percentage | number | 是 | 持股比例，浮点数，如：35.5（表示35.5%） |
| position | string | 是 | 职位名称，如：Chief Financial 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 | 是 | 州/省，如：MA（马萨诸塞州） |
| city | string | 是 | 城市，如：Boston |
| zipcode | string | 是 | 邮政编码，如：02110 |
| 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 |
{
"uid": "123456",
//"uuid": "rjGqpBk3xaEWlYwZlm96XM1noRQLON2K",//如传递，表示要修改
"first_name": "Tom",
"middle_name": "Green",
"last_name": "White",
"aliases": "J. Doe",
"share_percentage": 35.5,
"position": "Chief Financial Officer",
"date_of_birth": "1980-03-22",
"place_of_birth": "US",
"nationality": ["US"],
"email": "[email protected]",
"phone": {
"phone_country_code": "+1",
"phone_country_code_short": "US",
"phone_number": "4155550202"
},
"country": "US",
"state": "MA",
"city": "Boston",
"zipcode": "02110",
"address_1": "456 Park Avenue, Floor 20, Manhattan",
"address_2": "Suite 2001",
"is_critical_role": "Yes",
"related_officer": "Yes",
"id_file": [
{
"file_hash": "cf6802c1439966693b1d5db205f5b7fc"
}
],
"selfie_file": [
{
"file_hash": "cf6802c1439966693b1d5db205f5b7fc"
}
],
"proof_of_residence_file": [
{
"file_hash": "cf6802c1439966693b1d5db205f5b7fc"
}
]
}
