跳到主要内容

创建关联方

简介​

本资源旨在识别与法人投资者相关的最终受益人（自然人）和控制人，例如合伙人、董事、管理人员等，或自然人的代理人。

注意
  • 此端点需多次调用，每个关联方调用一次
  • 当关联方为法人时，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 以及所创建关联方的详细信息。

适用范围
角色主机所需权限
管理人manager-api写入
顾问consultant-api由集成团队开通

各主机的 Base URL：环境（主机）。

Request​

ENDPOINT
/investor_registry/investor/{investor_key}/investor_analysis/{investor_analysis_key}/related_party
MÉTODO
POST
STATUS
201

Request 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​

字段类型描述字符数必填
namestring关联方名称1 - 255是
person_typestringPerson Type 枚举值-是
related_party_typestringRelated Party Type 枚举值-是
residentboolean是否为巴西居民-是
legal_representativeboolean是否为法定代表人-是
direct_beneficiaryboolean是否为最终受益人-是
participation_percentagenumber持股比例，以 0 到 1 的小数表示（例如：0.5 = 50%）-是
document_numberstringCPF 或 CNPJ。resident: true 时必填1 - 18视情况
addressobjectAddress 对象。当 person_type 为 legal_person 或 direct_beneficiary: true 时必填-视情况
monthly_incomenumber月收入。当 person_type 为 natural_person 且 direct_beneficiary: true 时必填-视情况
nationalitystring国籍，3 位大写字母 ISO 代码（例如：BRA）。自然人默认 BRA。legal_person 不接受此字段3否
emailstring电子邮箱1 - 100否
phoneobjectPhone 对象-否
expiration_datestring到期日期（格式：YYYY-MM-DD）10否
条件字段

当满足上述条件而未发送 address 或 monthly_income 时，将以 IVR000068 拒绝——即使它们在其他情况下是可选的。由于 API 一次只验证一个字段，对于 direct_beneficiary: true 的关联方，请在第一次尝试时就同时发送这两个字段。

为 legal_person 关联方发送 nationality 将以 IVR000238 拒绝。

枚举值描述
natural_person自然人
legal_person法人
枚举值描述
president总裁
partner合伙人
administrator管理人员
director董事
manager经理
attorney代理人
parent_company控股公司（仅适用于法人）
asset_custodian资产托管人
exclusive_investor专属投资者

Address​

字段类型描述字符数必填
postal_codestring邮政编码。巴西地址使用 XXXXX-XXX 格式的 CEP；境外地址请按所在国家格式发送当地邮政编码1 - 20是
streetstring街道1 - 255否
numberstring门牌号1 - 10否
neighborhoodstring街区1 - 255否
citystring城市1 - 255否
ufstring联邦州（例如：SP）。境外地址使用 EX1 - 20否
countrystring国家，3 位字母 ISO 代码（例如：BRA）3否
complementstring地址补充信息1 - 255否
境外地址

postal_code 和 uf 不做格式校验——接受任何国家的格式。要求的一致性在于 resident 与 country 之间：resident: true 的关联方必须为 country: "BRA"（否则 IVR000227），resident: false 的关联方不能为 country: "BRA"（否则 IVR000226）。

Phone​

字段类型描述字符数必填
international_dial_codestring国际区号1 - 3是
area_codestring地区区号2是
numberstring电话号码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"
    }
}

错误​

状态代码发生情形
400IVR000096分析已不处于 pending_registry_data 状态
400IVR000004CPF/CNPJ 校验位无效
400IVR000068缺少该关联方 person_type 所需的必填字段
400IVR000169合计持股比例将超过 100%
409IVR000130本分析中已存在相同证件号的关联方
400QIT000011通过管理人（manager-api）调用时：该投资者不是与其关联的基金类别

认证、权限和主机相关错误：参见 API 错误。