创建投资者

简介

本资源用于向我们提供启动投资者注册所需的基本数据。

创建投资者时，会同时开启一份与之关联的首个注册分析。因此，此调用结束时会返回两个键：investor_key（标识投资者）和 investor_analysis_key（标识进行中的注册分析）。

投资者主要有 3 种类型，由字段 person_type 定义：自然人（natural_person）、法人（legal_person）和 PCO（'nominee'）。对于法人，字段 investor_sub_type 用于区分子类型，例如投资基金（fund_class），这些子类型在注册流程中遵循其专属规则。

注意

对于以代理账户方式分销的投资者（PCO | nominee），不存在注册流程，因此只需调用创建 POST，即可使其在整个系统中可用。

Sandbox 中的审批规则

在 Sandbox 中，分析结果取决于 CPF/CNPJ 的首位数字：以 1 开头 → 自动拒绝；以 8 开头 → 人工分析；其余自动批准。

Input / Output

输入为投资者的基本数据。必填字段因 person_type 和 investor_sub_type 而异。

输出将返回 investor_key 和 investor_analysis_key。investor_key 标识投资者；investor_analysis_key 标识随创建一同开启的注册分析。同一投资者在不同时间可以拥有多份注册分析（续期、更新）。

适用范围

角色	主机
分销商	`distributor-api`

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

Request

ENDPOINT

/investor_registry/v2/investor

MÉTODO

POST

STATUS

201

Request body

案例 01：自然人

请求体
{
    "name": "João da Silva",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "email": "joao.silva@example.com",
    "phone": {
        "international_dial_code": "55",
        "area_code": "11",
        "number": "987654321"
    }
}

案例 02：法人

请求体
{
    "name": "Empresa XPTO Ltda",
    "document_number": "22.333.444/0001-81",
    "person_type": "legal_person",
    "investor_sub_type": "default",
    "registry_user": {
        "name": "José da Silva",
        "document_number": "969.698.790-03",
        "email": "jose.silva@example.com",
        "phone": {
            "international_dial_code": "55",
            "area_code": "11",
            "number": "987654321"
        }
    }
}

案例 03：法人 — 投资基金（fund_class）

请求体
{
    "name": "Fundo XPTO Multimercado",
    "document_number": "22.333.444/0001-81",
    "person_type": "legal_person",
    "investor_sub_type": "fund_class"
}

案例 04：Nominee（PCO）

请求体
{
    "name": "Nominee XPTO",
    "person_type": "nominee",
    "external_distribution_key": "ID-DISTRIBUICAO-001"
}

各 person_type 的必填字段

必填字段随 person_type 变化。缺少其中任何一个都会被拒绝并返回 IVR000009，其消息会列出所需字段的完整清单。

natural_person：name、document_number、person_type
legal_person：name、document_number、person_type
nominee：name、person_type、external_distribution_key

investor_sub_type 为可选。 若省略，自然人为 default；对于居民法人，子类型根据 CNPJ 识别（financial_institution、fund_class 或 default）。对于分销商，email 和 phone 为可选但建议填写：没有 email 时，不会为投资者创建访问用户。

关于 registry_user

registry_user 表示负责填写投资者注册数据的用户（自然人）。对于自然人，该用户通常就是投资者本人，此字段可省略。对于法人，则是负责填写的代表人。

发送该对象时，必须包含 name、document_number 和 email。如果自然人省略此字段，用户将根据投资者本人的 email 生成——若投资者也没有 email，则不会创建任何用户。

不接受分销商发送 investor_owner_type

当投资者由分销商集成以 person_type natural_person 或 legal_person 创建时，字段 investor_owner_type 会被拒绝并返回 IVR000010。托管投资组合和基金的关联关系通过注册分析中的 Criar Investor Owner 端点建立。

非居民投资者

居民身份在创建投资者时确定，之后不可更改。它由字段 resident 控制。

请求体 — 非居民自然人
{
    "name": "Maria Fernandes",
    "document_number": "969.698.790-03",
    "person_type": "natural_person",
    "investor_sub_type": "default",
    "resident": false,
    "non_resident_type": "third_party_representation",
    "investor_owners": [
        {
            "type": "non_resident_representative",
            "name": "Representante Legal Brasil Ltda",
            "document_number": "22.333.444/0001-81"
        }
    ]
}

字段	类型	描述	必填
`resident`	boolean	定义注册分析的居民身份。默认 `true`	否
`non_resident_type`	string	`self_representation` 或 `third_party_representation`。`resident: false` 时必填（`IVR000222`）	条件必填
`investor_owners`	array	在巴西居住的法定代表人，`type: "non_resident_representative"`	否

代表类型

non_resident_type 声明非居民投资者在巴西如何被代表。这一选择决定了您需要注册哪些实体，以及提交分析时需要哪些文件。

枚举值	账户类型	含义
`third_party_representation`	4373 账户	非居民投资者通过第三方运作：有一名托管人负责保管资产，另有一名巴西法定代表人负责在巴西代表其行事。实际上两者通常为同一实体。
`self_representation`	CNR 账户（自托管 / 税务代表）	投资者本人即为托管人和代表人。不存在第三方托管人或代表人。

两者的区别：

	`third_party_representation`	`self_representation`
托管人	类型为 `asset_custodian` 的关联方	不存在
代表人	类型为 `non_resident_representative` 的 investor owner——始终为居民，持有 CPF/CNPJ	不存在
代表文件	`custody_contract`（在托管人上）和 `representation_contract`（在代表人上）——或在分析中提交一份 `simplified_declaration`	无

文件要求如何校验

在 third_party_representation 中，custody_contract 仅在发送至类型为 asset_custodian 的有效关联方时才会被识别，representation_contract 仅在发送至类型为 non_resident_representative 的有效 investor owner 时才会被识别。将两份合同作为注册分析文件发送并不满足该规则。

如果在 submit 时未找到该组合，响应为 IVR000029。

适用于两种类型的规则：

发送注册数据时 nif_number 为必填（IVR000224）；
没有 CPF/CNPJ 的外国关联方需要 passport 或 foreign_id；
在巴西出生的自然人（natural_person.place_of_birth.country: "BRA"）需要 final_departure_tax_return。

non_resident_type 不可更改

该值在创建投资者时确定。您可以在注册数据中再次发送，但只能是相同的值——值不一致，或在居民注册中发送，都会返回 IVR000225。

居民身份与地址必须一致

当 resident: true（默认）时，第 3 步发送的地址必须为 country: "BRA"，否则返回 IVR000227。当 resident: false 时，country 不能为 BRA，否则返回 IVR000226。

postal_code 和 uf 没有格式校验，因此外国邮政编码会按原样接受。境外地址的 uf 请填写 EX。

fund_class 投资者

对于投资基金（investor_sub_type: "fund_class"），部分注册数据会在提交分析时根据 CVM 数据库自动填写——包括公司名称、成立日期、净资产，以及与管理机构、管理人和（如适用）专属投资者的关联关系。注册其他所有权关系，请参阅 Criar Investor Owner 文档。

Body params

字段	类型	描述	字符数	必填
`name`	string	投资者姓名（或公司名称）	1 - 255	是
`person_type`	string	Person Type 枚举值	-	是
`investor_sub_type`	string	Investor Sub Type 枚举值。若省略则自动推断（见上文）	-	否
`document_number`	string	CPF（`XXX.XXX.XXX-XX`）或 CNPJ（`XX.XXX.XXX/XXXX-XX`）	14 或 18	是*
`external_distribution_key`	string	分销的外部标识（`nominee` 必填）	1 - 100	是*
`resident`	boolean	注册分析的居民身份。默认 `true`。见非居民投资者	-	否
`non_resident_type`	string	`self_representation` 或 `third_party_representation`。`resident: false` 时必填	-	条件必填
`investor_owners`	array	非居民投资者的居民法定代表人	-	否
`email`	string	投资者邮箱	1 - 255	否
`phone`	object	Phone 对象	-	否
`registry_user`	object	Registry User 对象	-	否
`external_id`	string	投资者在您系统中的标识	1 - 50	否

* person_type: nominee 不应发送 document_number。external_distribution_key 仅 nominee 必填。

Phone

字段	类型	描述	字符数	必填
`international_dial_code`	string	国际区号（例如 `55`）	1 - 3	是
`area_code`	string	地区区号（DDD）	2	是
`number`	string	电话号码	8 - 9	是

Registry User

字段	类型	描述	字符数	必填
`name`	string	注册用户姓名	1 - 255	是
`document_number`	string	用户 CPF（格式 `XXX.XXX.XXX-XX`）	14	是
`email`	string	用户邮箱	1 - 255	是
`phone`	object	Phone 对象	-	否

Person Type

枚举值	描述
`natural_person`	自然人
`legal_person`	法人
`nominee`	Nominee / PCO（无需证件）

Investor Sub Type

枚举值	描述
`default`	普通投资者，自然人或法人
`fund_class`	投资基金——触发基于 CVM 公开数据的自动补全
`financial_institution`	金融机构。遵循与 `default` 相同的规则

值 non_resident 会被拒绝并返回 IVR000255：居民身份通过字段 resident 和 non_resident_type 声明，而不是通过子类型。

Response

响应体
{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID"
}

错误

状态	代码	发生情形
400	`IVR000004`	CPF/CNPJ 校验位无效，或 CPF 搭配 `legal_person` 发送（反之亦然）
400	`IVR000009`	缺少该 `person_type` 的必填字段
400	`IVR000010`	`investor_owner_type` 搭配 `natural_person` 或 `legal_person` 发送
400	`IVR000222`	`resident: false` 但未提供 `non_resident_type`
400	`IVR000255`	`investor_sub_type: non_resident`
409	`IVR000007`	您已使用此证件注册过投资者

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

简介​

Input / Output​

Request​

Request body​

非居民投资者​

代表类型​

Body params​

Phone​

Registry User​

Person Type​

Investor Sub Type​

Response​

错误​

简介