创建关联方
简介
本资源旨在识别与法人投资者相关的最终受益人（自然人）和控制人，例如合伙人、董事、管理人员等，或自然人的代理人。
- 此端点需多次调用，每个关联方调用一次
- 当关联方为法人时，
related_party_type必须为parent_company（fund_class除外） - 数量、法定代表人和最低持股比例的要求因投资者类型而异——参见下文按投资者类型的要求
- 如需更正或停用已创建的关联方，请使用更新关联方和更新关联方状态。状态为
inactive的关联方在提交分析的所有验证中均不再计入
按投资者类型的要求
以下验证在提交分析（submit）时执行，而不是在创建关联方时执行。各规则按顺序评估，因此一次拒绝可能掩盖下一个待处理项。
| 投资者 | 关联方 | 法定代表人 | 合计持股比例 |
|---|---|---|---|
自然人（natural_person） | 可选——仅在有代理人时发送 | 不要求 | 不验证 |
法人（legal_person / default、financial_institution） | 至少一个有效关联方，否则 IVR000134 | 至少一个 legal_representative: true，否则 IVR000136 | ≥ 80% 且不得超过 100%，否则 IVR000166 / IVR000169 |
非专属基金（fund_class） | 无——可跳过此步骤 | 不要求 | 不验证 |
专属基金（fund_class） | 至少一个，且必须为 exclusive_investor 类型，否则 IVR000134 | 禁止——exclusive_investor 不能作为法定代表人（IVR000165） | 恰好 100%，否则 IVR000170 |
在基金中，代表由 investor owners（管理机构和管理人）承担——无需将法定代表人作为关联方发送。fund_class 唯一接受的 related_party_type 是 exclusive_investor；其他任何值都将以 IVR000172 拒绝。
基金的专属属性（exclusive_fund_class）在创建投资者时根据 CVM 类别自动得出。如果 CNPJ 不在 CVM 数据库中，该字段将保持未定义，submit 会以 IVR000068 被拒绝——请使用确实在 CVM 登记的基金 CNPJ。
最终受益人是指最终对公司拥有控制地位或重大影响的自然人，尤其是直接或间接持股 15% 或以上、担任管理职务或在法律上代表公司的人。
请提供直接或间接持股 15% 或以上的自然人以及管理人员的数据。如果没有任何合伙人/股东单独持股达到或超过 15%，请提供持股比例最高的 3 名控制人的信息。
15% 规则与 80% 最低比例的协调。 两条规则同时适用：15% 规则决定谁需要被登记，80% 规则决定股权链中多少比例需要被申报。法人股东（parent_company）同样计入合计——在股权分散的情况下，申报控股母公司通常是达到最低比例的方法。建议合计发送至少 85%，以免受四舍五入影响。
代理人（attorney）虽不持股，但处于控制地位，因此被视为最终受益人。发送时请使用 participation_percentage: 0。
当自然人最终受益人无法完整登记时，登记控股公司可能即可满足要求——但可能会通过反馈要求补充说明。
Input / Output:
作为输入，需发送关联方数据。
作为输出，将返回 external_related_party_key 以及所创建关联方的详细信息。
| 角色 | 主机 |
|---|---|
| 分销商 | distributor-api |
各主机的 Base URL：环境（主机）。
Request
/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_partyPOST201Request body
示例：自然人合伙人
{
"name": "João Silva",
"document_number": "969.698.790-03",
"person_type": "natural_person",
"related_party_type": "partner",
"resident": true,
"legal_representative": true,
"direct_beneficiary": true,
"address": {
"postal_code": "01000-000",
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"city": "São Paulo",
"uf": "SP",
"country": "BRA",
"complement": "Apto 101"
},
"participation_percentage": 0.5,
"monthly_income": 50000.00,
"email": "joao.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
}
}
示例：控股公司（法人）
{
"name": "Empresa Controladora Ltda",
"document_number": "66.777.888/0001-81",
"person_type": "legal_person",
"related_party_type": "parent_company",
"resident": true,
"legal_representative": false,
"direct_beneficiary": true,
"address": {
"postal_code": "02000-000",
"street": "Avenida Principal",
"number": "456",
"neighborhood": "Jardim",
"city": "São Paulo",
"uf": "SP",
"country": "BRA"
},
"participation_percentage": 0.8,
"email": "contato@controladora.com.br",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "123456789"
}
}
Body params
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---|---|---|---|---|
name | string | 关联方名称 | 1 - 255 | 是 |
person_type | string | Person Type 枚举值 | - | 是 |
related_party_type | string | Related Party Type 枚举值 | - | 是 |
resident | boolean | 是否为巴西居民 | - | 是 |
legal_representative | boolean | 是否为法定代表人 | - | 是 |
direct_beneficiary | boolean | 是否为最终受益人 | - | 是 |
participation_percentage | number | 持股比例，以 0 到 1 的小数表示（例如：0.5 = 50%） | - | 是 |
document_number | string | CPF 或 CNPJ。resident: true 时必填 | 1 - 18 | 视情况 |
address | object | Address 对象。当 person_type 为 legal_person 或 direct_beneficiary: true 时必填 | - | 视情况 |
monthly_income | number | 月收入。当 person_type 为 natural_person 且 direct_beneficiary: true 时必填 | - | 视情况 |
nationality | string | 国籍，3 位大写字母 ISO 代码（例如：BRA）。自然人默认 BRA。legal_person 不接受此字段 | 3 | 否 |
email | string | 电子邮箱 | 1 - 100 | 否 |
phone | object | Phone 对象 | - | 否 |
expiration_date | string | 到期日期（格式：YYYY-MM-DD） | 10 | 否 |
当满足上述条件而未发送 address 或 monthly_income 时，将以 IVR000068 拒绝——即使它们在其他情况下是可选的。由于 API 一次只验证一个字段，对于 direct_beneficiary: true 的关联方，请在第一次尝试时就同时发送这两个字段。
为 legal_person 关联方发送 nationality 将以 IVR000238 拒绝。
Person Type（Related Party）
| 枚举值 | 描述 |
|---|---|
natural_person | 自然人 |
legal_person | 法人 |
Related Party Type
| 枚举值 | 描述 |
|---|---|
president | 总裁 |
partner | 合伙人 |
administrator | 管理人员 |
director | 董事 |
manager | 经理 |
attorney | 代理人 |
parent_company | 控股公司（仅适用于法人） |
asset_custodian | 资产托管人 |
exclusive_investor | 专属投资者 |
Address
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---|---|---|---|---|
postal_code | string | 邮政编码。巴西地址使用 XXXXX-XXX 格式的 CEP；境外地址请按所在国家格式发送当地邮政编码 | 1 - 20 | 是 |
street | string | 街道 | 1 - 255 | 否 |
number | string | 门牌号 | 1 - 10 | 否 |
neighborhood | string | 街区 | 1 - 255 | 否 |
city | string | 城市 | 1 - 255 | 否 |
uf | string | 联邦州（例如：SP）。境外地址使用 EX | 1 - 20 | 否 |
country | string | 国家，3 位字母 ISO 代码（例如：BRA） | 3 | 否 |
complement | string | 地址补充信息 | 1 - 255 | 否 |
postal_code 和 uf 不做格式校验——接受任何国家的格式。要求的一致性在于 resident 与 country 之间：resident: true 的关联方必须为 country: "BRA"（否则 IVR000227），resident: false 的关联方不能为 country: "BRA"（否则 IVR000226）。
Phone
| 字段 | 类型 | 描述 | 字符数 | 必填 |
|---|---|---|---|---|
international_dial_code | string | 国际区号 | 1 - 3 | 是 |
area_code | string | 地区区号 | 2 | 是 |
number | string | 电话号码 | 8 - 9 | 是 |
Response
{
"related_party_key": "UUID",
"external_related_party_key": "UUID",
"name": "João Silva",
"document_number": "969.698.790-03",
"person_type": "natural_person",
"related_party_type": "partner",
"status": "active",
"resident": true,
"legal_representative": true,
"direct_beneficiary": true,
"address": {
"postal_code": "01000-000",
"street": "Rua das Flores",
"number": "123",
"neighborhood": "Centro",
"city": "São Paulo",
"uf": "SP",
"country": "BRA",
"complement": "Apto 101"
},
"participation_percentage": 0.5,
"monthly_income": 50000.00,
"email": "joao.silva@example.com",
"phone": {
"international_dial_code": "55",
"area_code": "11",
"number": "987654321"
}
}
错误
| 状态 | 代码 | 发生情形 |
|---|---|---|
| 400 | IVR000096 | 分析已不处于 pending_registry_data 状态 |
| 400 | IVR000004 | CPF/CNPJ 校验位无效 |
| 400 | IVR000068 | 缺少该关联方 person_type 所需的必填字段 |
| 400 | IVR000169 | 合计持股比例将超过 100% |
| 409 | IVR000130 | 本分析中已存在相同证件号的关联方 |
| 400 | QIT000011 | 通过管理人（manager-api）调用时：该投资者不是与其关联的基金类别 |
认证、权限和主机相关错误：参见 API 错误。