创建投资者

---

简介

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

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

字段 person_type 定义投资者是自然人（natural_person）还是法人（legal_person）。在法人中，字段 investor_sub_type 用于区分普通企业（default）和投资基金类别（fund_class），后者在整个流程中遵循其专属规则。

Sandbox 中的审批规则

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

投资者访问用户

默认情况下，创建投资者时还会在平台上创建该投资者的访问用户（query param create_investor_user，默认 true）。如果投资者不会自行填写注册信息，请发送 ?create_investor_user=false。

Input / Output

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

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

适用范围

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

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

Request

ENDPOINT

/investor_registry/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"
}

必填字段

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

• natural_person：name、document_number、person_type、email 和 phone
• legal_person：name、document_number、person_type。对于 fund_class，不要发送 registry_user——代表由 investor owners（管理机构和管理人）承担

investor_sub_type 为可选。 若省略，自然人为 default；对于居民法人，子类型根据 CNPJ 识别：已登记的金融机构为 financial_institution，在 CVM 登记的类别为 fund_class，其余情况为 default。如果您填写了子类型，它必须与 CNPJ 相符（见错误）。

基金类别：谁可以注册

通过管理人（manager-api）创建 fund_class 投资者时，仅当管理人的 CNPJ 在 CVM 登记为该类别的管理人或管理机构时才会被接受；否则返回 IVR000260。该类别的管理机构和管理人（以 CVM 为准）也必须已在 QI Tech 注册为投资者。详细说明见 简介。

仅限运作中的类别

只有在 CVM 处于运营中的类别才能注册。预运营、已终止、已注销或已被合并的类别会在分析中被拒绝。如果 CNPJ 不在 CVM 数据库中，submit 会被拒绝并返回 IVR000068。

CVM 为您填写的内容

对于 fund_class，部分注册数据会在提交分析时根据 CVM 公开数据库自动填写——包括公司名称、成立日期、净资产，以及与管理机构、管理人和（如适用）专属投资者的关联关系。

因此，该子类型不发送地址、净资产、适配度、签署人组和投资者文件。请参阅 各类型适用的步骤。

关于 registry_user

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

Body params

字段	类型	描述	字符数	必填
name	string	投资者姓名（或公司名称）	1 - 255	是
person_type	string	Person Type 枚举值	-	是
document_number	string	CPF（XXX.XXX.XXX-XX）或 CNPJ（XX.XXX.XXX/XXXX-XX）。对于 fund_class，为在 CVM 登记的类别 CNPJ	14 或 18	是*
investor_sub_type	string	Investor Sub Type 枚举值。若省略则自动推断（见上文）	-	否
email	string	投资者邮箱。natural_person 必填	1 - 255	条件必填
phone	object	Phone 对象。natural_person 必填	-	条件必填
registry_user	object	Registry User 对象	-	否
resident	boolean	投资者是否为巴西居民。默认 true	-	否
non_resident_type	string	self_representation 或 third_party_representation。resident: false 时必填	-	条件必填

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	法人

Investor Sub Type

枚举值	描述
default	普通投资者，自然人或法人
financial_institution	金融机构（仅限 legal_person）
fund_class	投资基金类别（仅限 legal_person）——会触发基于 CVM 公开数据的自动补全，并在步骤、关联方和 investor owners 方面遵循专属规则

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

Response

响应体

{
    "investor_key": "UUID",
    "investor_analysis_key": "UUID",
    "resident": true
}

响应中还会包含 distributor 对象；对于非居民投资者，还会包含 non_resident_type。

已存在的投资者

如果其他代理方已使用相同证件注册了投资者，则不会创建新的投资者：该投资者会与您关联，且响应仅返回 investor_key。

错误

状态	代码	发生情形
400	IVR000004	CPF/CNPJ 校验位无效，或 CPF 搭配 legal_person 发送（反之亦然）
400	IVR000009	缺少该 person_type 的必填字段——例如自然人缺少 email 或 phone
400	IVR000222	resident: false 但未提供 non_resident_type
400	IVR000064	investor_sub_type 为 fund_class 或 financial_institution 却搭配 natural_person 发送
400	IVR000255	investor_sub_type: non_resident。请使用 resident: false 和 non_resident_type
400	IVR000256 / IVR000257	声明的子类型与 CNPJ 不符：financial_institution 但无已登记机构，或 fund_class 但 CVM 中无该类别
400	IVR000258 / IVR000259	对属于已登记金融机构或 CVM 类别的 CNPJ 声明了子类型 default
403	IVR000260	管理人试图注册其既非管理人也非管理机构的基金类别
409	IVR000007	您已使用此证件注册过投资者

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