Cadastro Básico do Investidor

Este endpoint permite cadastrar as informações básicas de um investidor. O mesmo endpoint é utilizado tanto para investidores pessoa jurídica (PJ) quanto pessoa física (PF) — o corpo da requisição varia de acordo com o campo person_type.

Request

ENDPOINT

/investor_management/investor

MÉTODO

POST

Request Body

Caso 01: Pessoa Jurídica

{
  "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"
  }
}

Caso 02: Pessoa Física

{
  "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": "engenheira de software",
  "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"
  }
}

Atenção

Se o campo person_type for omitido, o cadastro é tratado como Pessoa Jurídica (legal). Para cadastrar um investidor Pessoa Física, envie person_type: "natural".

Request Body Params — Pessoa Jurídica

Campo	Tipo	Descrição	Caracteres Máx.
person_type	string	Opcional. Se omitido, o cadastro é tratado como Pessoa Jurídica (legal).	Enumeradores person_type
name *	string	Nome completo da empresa.	255
document_number *	string	CNPJ da empresa (formato "XX.XXX.XXX/XXXX-XX").	14
trading_name*	string	Nome fantasia da empresa.	1023
cnae_code*	string	Código CNAE da empresa (formato "XXXXX-XXX").	7
company_type*	string	Tipo da empresa.	Enumeradores company_type
foundation_date*	string	Data de fundação da empresa (formato "YYYY-MM-DD").	-
address *	object	Objeto referenciando o endereço	Objeto address

Request Body Params — Pessoa Física

Campo	Tipo	Descrição	Caracteres Máx.
person_type *	string	Deve ser enviado como "natural".	Enumeradores person_type
name *	string	Nome completo do investidor.	255
document_number *	string	CPF do investidor (formato "XXX.XXX.XXX-XX").	14
document_identification_number*	string	Número do documento de identidade do investidor (RG, CNH ou passaporte).	255
marital_status*	string	Estado civil do investidor.	Enumeradores marital_status
property_system	string	Regime de bens. Obrigatório apenas quando marital_status exigir regime de bens.	Enumeradores property_system
birthdate*	string	Data de nascimento do investidor (formato "YYYY-MM-DD").	-
nationality*	string	Nacionalidade do investidor.	Enumeradores nationality
mother_name*	string	Nome da mãe do investidor.	1023
father_name*	string	Nome do pai do investidor.	1023
occupation*	string	Ocupação/profissão do investidor.	255
is_pep*	boolean	Indica se o investidor é uma Pessoa Politicamente Exposta.	-
email*	string	E-mail de contato do investidor.	1023
phone_number*	string	Telefone de contato do investidor.	20
investor_category	string	Categoria autodeclarada do investidor. Opcional.	Enumeradores investor_category
investment_suitability	string	Perfil de suitability autodeclarado do investidor. Opcional.	Enumeradores investment_suitability
address *	object	Objeto referenciando o endereço	Objeto address

Objeto Address

Campo	Tipo	Descrição	Caracteres Máx.
street *	string	Nome da rua do endereço.	500
neighborhood *	string	Nome do bairro do endereço.	100
number *	string	Número do endereço.	10
postal_code *	string	CEP do endereço (formatação "XXXXX-XXX").	8
city *	string	Nome da cidade do endereço.	255
state *	string	Sigla do estado (2 caracteres).	2
complement	string	Complemento do endereço, se aplicável.	100

Enumeradores company_type

Enum	Description
ltda	Limitada
sa	Sociedade Anônima
cop	Cooperativa

Enumeradores marital_status

Enum	Description
single	Solteiro(a)
married	Casado(a)
divorced	Divorciado(a)
widowed	Viúvo(a)
separated	Separado(a)

Enumeradores property_system

Enum	Description
total_communion_of_goods	Comunhão universal de bens
partial_communion_of_goods	Comunhão parcial de bens
total_separation_of_goods	Separação total de bens
final_participation_of_acquisitions	Participação final nos aquestos
compulsory_separation_of_goods	Separação obrigatória de bens

Enumeradores nationality

Lista completa de códigos ISO 3166-1 alpha-3 (ex.: BRA para Brasil, USA para Estados Unidos).

Enumeradores investor_category

Enum	Description
not_applicable	Não aplicável
retail	Varejo
qualified	Qualificado
professional	Profissional

Enumeradores investment_suitability

Enum	Description
conservative	Conservador
moderate	Moderado
bold	Arrojado

Response

STATUS

201

Caso 01: Pessoa Jurídica

{
    "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"
  }

Caso 02: Pessoa Física

{
  "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": "engenheira de software",
  "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
        }
      ]
    }
  ]
}

Informação

investor_contact_information_list e signer_group_list só são retornados quando o cadastro é feito com acesso completo (data_access_type == full_access).

Response Body Params

Campo	Tipo	Pessoa	Descrição	Caracteres Máx.
investor_key	string	Ambos	Chave única do investidor (UUID).	36
name	string	Ambos	Nome completo (PF) ou razão social (PJ).	255
document_number	string	Ambos	CPF (PF) ou CNPJ (PJ) do investidor.	14
status	string	Ambos	Status do investidor.	-
person_type	string	Ambos	Tipo de pessoa	Enumeradores person_type
trading_name	string	Somente PJ	Nome fantasia do investidor.	1023
cnae_code	string	Somente PJ	Código CNAE do investidor.	7
company_type	string	Somente PJ	Tipo da empresa	Enumeradores company_type
foundation_date	string	Somente PJ	Data de fundação do investidor.	-
document_identification_number	string	Somente PF	Número do documento de identidade do investidor.	255
marital_status	string	Somente PF	Estado civil do investidor.	Enumeradores marital_status
birthdate	string	Somente PF	Data de nascimento do investidor.	-
nationality	string	Somente PF	Nacionalidade do investidor.	Enumeradores nationality
occupation	string	Somente PF	Ocupação/profissão do investidor.	255
is_pep	boolean	Somente PF	Indica se o investidor é PEP.	-
investor_category	string	Somente PF	Categoria autodeclarada do investidor.	Enumeradores investor_category
investment_suitability	string	Somente PF	Perfil de suitability autodeclarado.	Enumeradores investment_suitability
address	object	Ambos	Objeto referenciando o endereço	Objeto address
investor_contact_information_list	array	Somente PF	Lista de informações de contato do investidor. Apenas com data_access_type == full_access.	-
signer_group_list	array	Somente PF	Lista de grupos de assinantes do investidor. Apenas com data_access_type == full_access.	-
registration_datetime	string	Ambos	Data e hora de registro do investidor.	-
expiration_date	string	Ambos	Data de expiração do investidor.	-

Enumeradores person_type

Enum	Description
legal	Pessoa Jurídica
natural	Pessoa Física