投资人基本登记

此端点允许登记投资人的基本信息。**法人（PJ）和自然人（PF）**投资人均使用同一端点 —— 请求体的内容依据 person_type 字段而有所不同。

Request

ENDPOINT

/investor_management/investor

MÉTODO

POST

Request Body

案例 01：法人（PJ）

{
  "name": "Empresa Exemplo S.A.",
  "document_number": "12.345.678/0001-95",
  "trading_name": "Exemplo Comércio",
  "cnae_code": "62.02-3-00",
  "company_type": "sa",
  "foundation_date": "2000-01-01",
  "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
  }
}

案例 02：自然人（PF）

{
  "person_type": "natural",
  "name": "Maria Exemplo da Silva",
  "document_number": "123.456.789-00",
  "document_identification_number": "12.345.678-9",
  "marital_status": "single",
  "property_system": null,
  "birthdate": "1990-05-14",
  "nationality": "BRA",
  "mother_name": "Joana Exemplo da Silva",
  "father_name": "José Exemplo da Silva",
  "occupation": "软件工程师",
  "is_pep": false,
  "email": "maria.exemplo@example.com",
  "phone_number": "+5511999999999",
  "investor_category": "retail",
  "investment_suitability": "moderate",
  "address": {
      "street": "Rua Exemplo",
      "neighborhood": "Centro",
      "number": "45",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Apto 12"
  }
}

注意

如果省略 person_type 字段，登记将被视为法人（legal）。要登记自然人投资人，请发送 person_type: "natural"。

Request Body Params — 法人（PJ）

字段	类型	描述	最大字符数
`person_type`	string	可选。如果省略，登记将被视为法人（`legal`）。	person_type 枚举
`name` *	string	公司全名。	255
`document_number` *	string	公司 CNPJ（格式："XX.XXX.XXX/XXXX-XX"）。	14
`trading_name`*	string	公司商业名称。	1023
`cnae_code`*	string	公司 CNAE 代码（格式："XXXXX-XXX"）。	7
`company_type`*	string	公司类型。	company_type 枚举
`foundation_date`*	string	公司成立日期（格式："YYYY-MM-DD"）。	-
`address` *	object	地址引用对象。	address 对象

Request Body Params — 自然人（PF）

字段	类型	描述	最大字符数
`person_type` *	string	必须发送为 `"natural"`。	person_type 枚举
`name` *	string	投资人全名。	255
`document_number` *	string	投资人的 CPF（格式："XXX.XXX.XXX-XX"）。	14
`document_identification_number`*	string	投资人的身份证明文件号码（RG、CNH 或护照）。	255
`marital_status`*	string	投资人的婚姻状况。	marital_status 枚举
`property_system`	string	财产制度。仅当 `marital_status` 要求财产制度时为必填。	property_system 枚举
`birthdate`*	string	投资人的出生日期（格式："YYYY-MM-DD"）。	-
`nationality`*	string	投资人的国籍。	nationality 枚举
`mother_name`*	string	投资人母亲的姓名。	1023
`father_name`*	string	投资人父亲的姓名。	1023
`occupation`*	string	投资人的职业。	255
`is_pep`*	boolean	表示投资人是否为政治公开人物（PEP）。	-
`email`*	string	投资人的联系邮箱。	1023
`phone_number`*	string	投资人的联系电话。	20
`investor_category`	string	投资人自我声明的类别。可选。	investor_category 枚举
`investment_suitability`	string	投资人自我声明的适当性档案。可选。	investment_suitability 枚举
`address` *	object	地址引用对象。	address 对象

Address 对象

字段	类型	描述	最大字符数
`street` *	string	地址街道名称。	500
`neighborhood` *	string	地址区域名称。	100
`number` *	string	地址门牌号。	10
`postal_code` *	string	邮政编码（格式"XXXXX-XXX"）。	8
`city` *	string	地址城市名称。	255
`state` *	string	州缩写（2个字符）。	2
`complement`	string	地址补充信息（如适用）。	100

company_type 枚举

枚举值	描述
`ltda`	有限责任公司
`sa`	股份公司
`cop`	合作社

marital_status 枚举

枚举值	描述
`single`	未婚
`married`	已婚
`divorced`	离婚
`widowed`	丧偶
`separated`	分居

property_system 枚举

枚举值	描述
`total_communion_of_goods`	一般共同财产制
`partial_communion_of_goods`	部分共同财产制
`total_separation_of_goods`	完全分别财产制
`final_participation_of_acquisitions`	最终参与所得财产制
`compulsory_separation_of_goods`	强制分别财产制

nationality 枚举

完整的 ISO 3166-1 alpha-3 代码列表（例如：巴西为 BRA，美国为 USA）。

investor_category 枚举

枚举值	描述
`not_applicable`	不适用
`retail`	零售
`qualified`	合格投资人
`professional`	专业投资人

investment_suitability 枚举

枚举值	描述
`conservative`	保守型
`moderate`	稳健型
`bold`	进取型

Response

STATUS

201

案例 01：法人（PJ）

{
    "investor_key": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Empresa Exemplo S.A.",
    "document_number": "12.345.678/0001-95",
    "status": "in_filling",
    "person_type": "legal",
    "trading_name": "Exemplo Comércio",
    "cnae_code": "62.02-3-00",
    "company_type": "sa",
    "foundation_date": "2000-01-01",
    "address": {
      "street": "Rua das Empresas",
      "neighborhood": "Centro",
      "number": "123",
      "postal_code": "01001-000",
      "city": "São Paulo",
      "state": "SP",
      "complement": "Sala 101"
    },
    "registration_datetime": "2023-01-01T12:00:00Z",
    "expiration_date": "2024-01-01T12:00:00Z"
  }

案例 02：自然人（PF）

{
  "investor_key": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
  "name": "Maria Exemplo da Silva",
  "document_number": "123.456.789-00",
  "status": "in_filling",
  "person_type": "natural",
  "document_identification_number": "12.345.678-9",
  "marital_status": "single",
  "birthdate": "1990-05-14",
  "nationality": "BRA",
  "occupation": "软件工程师",
  "is_pep": false,
  "investor_category": "retail",
  "investment_suitability": "moderate",
  "address": {
    "street": "Rua Exemplo",
    "neighborhood": "Centro",
    "number": "45",
    "postal_code": "01001-000",
    "city": "São Paulo",
    "state": "SP",
    "complement": "Apto 12"
  },
  "registration_datetime": "2023-01-01T12:00:00Z",
  "expiration_date": "2024-01-01T12:00:00Z",
  "investor_contact_information_list": [
    {
      "investor_contact_information_key": "3f1e2d3c-4b5a-6978-8899-aabbccddeeff",
      "name": "Maria Exemplo da Silva",
      "document_number": "123.456.789-00",
      "email": "maria.exemplo@example.com",
      "phone_number": "+5511999999999",
      "is_default": true
    }
  ],
  "signer_group_list": [
    {
      "signer_group_key": "7a6b5c4d-3e2f-1a0b-9c8d-1234567890ab",
      "minimum_required_signers": 1,
      "signers": [
        {
          "name": "Maria Exemplo da Silva",
          "document_number": "123.456.789-00",
          "email": "maria.exemplo@example.com",
          "phone_number": "+5511999999999",
          "is_group_mandatory": true
        }
      ]
    }
  ]
}

信息

investor_contact_information_list 和 signer_group_list 仅在使用完整访问权限（data_access_type == full_access）登记时才会返回。

Response Body Params

字段	类型	人员	描述	最大字符数
`investor_key`	string	两者	投资人的唯一键（UUID）。	36
`name`	string	两者	全名（PF）或公司名称（PJ）。	255
`document_number`	string	两者	投资人的 CPF（PF）或 CNPJ（PJ）。	14
`status`	string	两者	投资人状态。	-
`person_type`	string	两者	人员类型。	person_type 枚举
`trading_name`	string	仅 PJ	投资人商业名称。	1023
`cnae_code`	string	仅 PJ	投资人的 CNAE 代码。	7
`company_type`	string	仅 PJ	公司类型。	company_type 枚举
`foundation_date`	string	仅 PJ	投资人成立日期。	-
`document_identification_number`	string	仅 PF	投资人的身份证明文件号码。	255
`marital_status`	string	仅 PF	投资人的婚姻状况。	marital_status 枚举
`birthdate`	string	仅 PF	投资人的出生日期。	-
`nationality`	string	仅 PF	投资人的国籍。	nationality 枚举
`occupation`	string	仅 PF	投资人的职业。	255
`is_pep`	boolean	仅 PF	表示投资人是否为 PEP。	-
`investor_category`	string	仅 PF	投资人自我声明的类别。	investor_category 枚举
`investment_suitability`	string	仅 PF	自我声明的适当性档案。	investment_suitability 枚举
`address`	object	两者	地址引用对象。	address 对象
`investor_contact_information_list`	array	仅 PF	投资人的联系信息列表。仅在 `data_access_type == full_access` 时返回。	-
`signer_group_list`	array	仅 PF	投资人的签署人组列表。仅在 `data_access_type == full_access` 时返回。	-
`registration_datetime`	string	两者	投资人注册日期和时间。	-
`expiration_date`	string	两者	投资人到期日期。	-

person_type 枚举

枚举值	描述
`legal`	法人
`natural`	自然人

Request​

Request Body​

Request Body Params — 法人（PJ）​

Request Body Params — 自然人（PF）​

Address 对象​

company_type 枚举​

marital_status 枚举​

property_system 枚举​

nationality 枚举​

investor_category 枚举​

investment_suitability 枚举​

Response​

Response Body Params​

person_type 枚举​