发送投资者文件

简介

本资源用于上传构成投资者注册分析的文件。必要文件因投资者的 person_type 和 investor_sub_type 以及其类别（零售、合格、专业）而异。

注意

此端点需为每个必要文件调用一次
注册分析必须处于 pending_registry_data 状态。处于其他状态时，调用会被拒绝并返回 IVR000026
同一 type 只接受一次成功发送：见重发与重复

Input / Output

输入为 base64 编码的文件内容、文件类型和扩展名。

输出将返回已创建文件的表示（以 investor_analysis_document_key 标识），以及其所属注册分析的完整表示。

Request

ENDPOINT

/investor_registry/v2/investor/{investor_key}/investor_analysis/{investor_analysis_key}/document

MÉTODO

POST

STATUS

201

Query params

字段	类型	描述	必填
`force`	boolean	若为 `true`，即使预校验失败也强制发送。该文件必定进入人工分析。	否

Request body

示例：CNH（自然人）

请求体
{
    "type": "cnh",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf",
    "document_data": {
        "document_type": "CNH",
        "issuer_entity": "DETRAN"
    }
}

示例：RG（正面和背面）

请求体 — 正面
{
    "type": "rg_front",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "jpeg",
    "document_data": {
        "document_type": "RG",
        "issuer_entity": "SSP",
        "document_number": "20.932.206-8"
    }
}

请求体 — 背面
{
    "type": "rg_back",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "jpeg"
}

示例：CNPJ 卡（法人）

请求体
{
    "type": "cnpj_card",
    "document_b64": "base64_encoded_document_content",
    "file_extension": "pdf"
}

Body params

字段	类型	描述	字符数	必填
`type`	string	Document Type 枚举值	-	是
`document_b64`	string	base64 编码的文件内容	-	是
`file_extension`	string	文件扩展名。可接受的值：`pdf`、`jpeg`	-	是
`document_data`	object	文件的自由元数据（例如号码、签发机构）	-	否
`observation`	string	关于该文件的自由备注	最多 500	否

Document Type

自然人身份证明及证明文件

枚举值	描述	扩展名
`cnh`	CNH	`pdf`, `jpeg`
`rg_front`	RG — 正面	`pdf`, `jpeg`
`rg_back`	RG — 背面	`pdf`, `jpeg`
`passport`	护照（外国人身份证明）	`pdf`, `jpeg`
`foreign_id`	外国身份证件（例如 RNE）	`pdf`, `jpeg`
`proof_of_residence`	居住证明	`pdf`, `jpeg`
`billing_statement`	账单 / 对账单	`pdf`, `jpeg`

法人公司文件

枚举值	描述	扩展名
`cnpj_card`	CNPJ 卡	`pdf`, `jpeg`
`social_contract`	公司合同	`pdf`, `jpeg`
`company_statute`	公司章程	`pdf`, `jpeg`
`board_election_record`	章程选举会议记录	`pdf`, `jpeg`
`financial_statements`	财务报表	`pdf`, `jpeg`
`organizational_chart`	股权架构图	`pdf`, `jpeg`

代表、资格认定及合同

枚举值	描述	扩展名
`power_of_attorney`	授权委托书	`pdf`, `jpeg`
`investor_qualification_proof`	资格 / 类别认定证明	`pdf`, `jpeg`
`wallet_manager_contract`	托管投资组合 / 中介合同	`pdf`, `jpeg`
`extra_document`	无特定类型的单独文件	`pdf`, `jpeg`

非居民投资者

枚举值	描述	扩展名
`custody_contract`	托管合同	`pdf`, `jpeg`
`representation_contract`	代表合同	`pdf`, `jpeg`
`simplified_declaration`	简化声明	`pdf`, `jpeg`
`final_departure_tax_return`	永久离境最终税务申报	`pdf`, `jpeg`

由 QI Tech 生成的类型

类型 qualified_investor_term、professional_investor_term、natural_person_registry_form、legal_person_registry_form、investor_suitability_form 和 adhesion_term 会出现在投资者查询结果中，但它们由 QI Tech 生成供签署——不应通过此端点发送。

必要文件

以下组合为可替代的文件集：每个列表只需满足其中一个选项。校验在提交分析（submit）时执行，不满足时以 IVR000029 拒绝，并在消息中返回所缺的具体组合。

自然人（`natural_person`）

以下选项之一：

选项	文件
1	`cnh` + `proof_of_residence`
2	`rg_front` + `rg_back` + `proof_of_residence`

法人（`legal_person` / `investor_sub_type: default`、`financial_institution`）

以下选项之一——始终需要至少一份公司文件以及财务报表：

选项	文件
1	`board_election_record` + `financial_statements`
2	`company_statute` + `financial_statements`
3	`social_contract` + `financial_statements`

所需的公司文件取决于企业的法律类型——因此有三个选项。不能只发送 financial_statements。

必要文件

虽然这些文件是提交分析的最低要求，但如果仅凭 company_statute 不足以确定份额持有人的签字人及权限，分析可能会被拒绝，并要求同时提供 board_election_record。

法人 — 投资基金（`investor_sub_type: fund_class`）

无需任何文件。 基金数据通过 CVM 数据库补全获取，代表由 investor owners（管理机构和管理人）承担。

重发与重复

只要该分析中存在一份状态为 valid 或 in_manual_analysis 的该类型文件，该文件类型即视为已满足。此后，同一类型的新发送会被拒绝：

HTTP 409
{
  "title": "Already exists valid document for investor analysis.",
  "code": "IVR000023"
}

只要某一类型的所有文件均为 invalid，该类型的新发送仍会被接受——这正是更正无法辨认文件的方式。

extra_document 类型是唯一的例外：始终接受多次发送。

自动校验与文件 `status`

类型为 cnh、rg_front、rg_back 和 proof_of_residence 的文件会经过自动校验（OCR），并返回以下状态之一。其余类型直接进入 in_manual_analysis。

状态	含义
`valid`	已自动校验通过
`in_manual_analysis`	已转交人工核查
`invalid`	自动校验未通过——请重新发送，或使用 `force=true`

force=true 会跳过自动拒绝的效果：文件登记为 in_manual_analysis，并满足该类型的要求。

关于 investor_qualification_proof

该文件不属于必要文件组合，缺少它也绝不会阻止 submit。它在之后发挥作用：如果申报的 total_financial_applications 低于所填类别的下限——qualified 为 R$ 1.000.000，professional 为 R$ 10.000.000——则使用该文件进行校验。fund_class 投资者免于此项校验。

Response

响应体
{
    "investor_analysis_document_key": "UUID",
    "type": "cnh",
    "status": "in_manual_analysis",
    "observation": "Documento emitido em 2019, legibilidade reduzida no verso.",
    "data": {
        "type": "cnh",
        "file_extension": "pdf",
        "document_data": {
            "document_type": "CNH",
            "issuer_entity": "DETRAN"
        }
    },
    "investor_analysis": { }
}

字段	类型	描述
`investor_analysis_document_key`	string	文件标识。即其他文件相关端点所使用的键
`type`	string	Document Type 枚举值
`status`	string	`valid`、`invalid` 或 `in_manual_analysis`——见自动校验
`observation`	string	请求中发送的备注。未填写时为 `null`
`data`	object	回显发送的字段，不含 base64 内容
`investor_analysis`	object	注册分析的完整表示——格式与查询投资者注册分析信息相同

错误

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

简介​

Input / Output​

Request​

Query params​

Request body​

Body params​

Document Type​

自然人身份证明及证明文件​

法人公司文件​

代表、资格认定及合同​

非居民投资者​

必要文件​

自然人（natural_person）​

法人（legal_person / investor_sub_type: default、financial_institution）​

法人 — 投资基金（investor_sub_type: fund_class）​

重发与重复​

自动校验与文件 status​

Response​

错误​

简介

Input / Output

Request

Query params

Request body

Body params

Document Type

自然人身份证明及证明文件

法人公司文件

代表、资格认定及合同

非居民投资者

必要文件

自然人（`natural_person`）

法人（`legal_person` / `investor_sub_type: default`、`financial_institution`）

法人 — 投资基金（`investor_sub_type: fund_class`）

重发与重复

自动校验与文件 `status`

Response

错误