Rascunho de Conta Livre Movimentação - Pessoa Jurídica

O fluxo Draft Checking Legal Person permite criar uma solicitação de abertura de conta em duas etapas:

1. POST: Cria um draft (rascunho) com flexibilidade máxima - aceita desde dados mínimos até dados completos
2. PATCH: Submete o draft para processamento, validando completude de todos os campos obrigatórios

Importante: Este fluxo está sendo preparado para integração com Monte Bravo. A divisão de campos entre POST e PATCH será ajustada após alinhamento com Monte Bravo sobre quais dados estarão disponíveis em cada momento do processo.

Criar Draft de Conta PJ

Request

ENDPOINT

/v2/account_request/draft_checking_legal_person

MÉTODO

POST

Descrição

Este endpoint cria um draft de abertura de conta para Pessoa Jurídica (Legal Person). O POST aceita desde dados mínimos até dados completos, oferecendo máxima flexibilidade.

Estratégia de Flexibilidade

• Dados mínimos: CNPJ + Nome + Tipo de pessoa
• Dados parciais: Adicione campos conforme disponíveis
• Dados completos: Envie tudo de uma vez (menos comum)

Exemplo 1: Payload MÍNIMO (apenas obrigatórios)

Request Body

{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal"
  }
}

{
  "request_control_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal"
  }
}

Comportamento: Se o mesmo request_control_key for usado novamente, retorna erro 409 (Conflict) ao invés de criar um novo draft.

Exemplo 2: Payload COMPLETO (todos os dados de uma vez)

Request Body

{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal",
    "email": "empresa@exemplo.com.br",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "999999999"
    },
    "trading_name": "Empresa Exemplo",
    "company_type": "LTDA",
    "foundation_date": "2010-01-15",
    "cnae_code": "6209-1/00",
    "company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
    "monthly_revenue": 150000.00,
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Conjunto 102"
    },
    "company_representatives": [
      {
        "name": "João Carlos da Silva",
        "email": "joao.silva@exemplo.com.br",
        "birth_date": "1985-03-20",
        "individual_document_number": "12345678901",
        "is_pep": false,
        "mother_name": "Maria da Silva",
        "nationality": "brasileira",
        "person_type": "natural",
        "phone": {
          "country_code": "055",
          "area_code": "11",
          "number": "988888888"
        },
        "address": {
          "street": "Rua das Flores",
          "state": "SP",
          "city": "São Paulo",
          "neighborhood": "Jardins",
          "number": "123",
          "postal_code": "01310100",
          "complement": "Apto 45"
        },
        "representative_relationship": "ceo",
        "gender": "male",
        "marital_status": "married",
        "documents": {
          "cnh": {
            "ocr_key": "7a73be1a-0b66-4c0a-932a-1d1d02efdc4c"
          }
        }
      }
    ]
  }
}

Response

STATUS

201

Response Body

{
  "account_request_key": "abc123-def456-...",
  "account_request_status": "draft",
  "account_info": {
    "account_number": "1638634",
    "account_digit": "3",
    "account_branch": "0001"
  }
}

Atenção

O campo account_request_key deve ser armazenado e será utilizado para submeter o draft via PATCH.

Request Body Params

Campo	Tipo	Descrição	Caracteres
request_control_key	string	UUID para garantir idempotência (36 caracteres)	36
reserved_account_key	string	UUID de conta reservada previamente (36 caracteres)	36
account_owner *	object	Informações do titular da conta (Pessoa Jurídica)	Objeto account_owner

Objeto account_owner (POST)

Campo	Tipo	Descrição	Caracteres
company_document_number *	string	CNPJ da empresa (14 dígitos, apenas números)	14
name *	string	Razão social da empresa	100
person_type *	enum	Tipo de pessoa (sempre "legal")	Enumeradores person_type
email	string	Email da empresa (formato email válido)	254
phone	object	Telefone da empresa	Objeto phone
trading_name	string	Nome fantasia	200
company_type	enum	Tipo societário	Enumeradores company_type
foundation_date	string	Data de fundação (formato: YYYY-MM-DD)	10
cnae_code	string	Código CNAE da atividade	9
company_statute	string	UUID do estatuto social (formato UUID)	36
monthly_revenue	number	Faturamento mensal	-
address	object	Endereço completo da empresa	Objeto address
company_representatives	array	Lista de representantes legais (mínimo 1 item se enviado)	Objeto company_representatives

Campos Obrigatórios no POST

Apenas 3 campos são obrigatórios no POST:

• company_document_number
• name
• person_type

Todos os demais campos são opcionais e podem ser enviados conforme disponibilidade.

Validação de Representantes

Se company_representatives for enviado no POST, deve ter pelo menos 1 item (minItems: 1). Cada representante deve ter todos os campos obrigatórios (ver seção PATCH). O campo documents dentro de cada representante é opcional no POST.

---

Submeter Draft de Conta PJ

Request

ENDPOINT

/v2/account_request/{account_request_key}/draft_checking_legal_person

MÉTODO

PATCH

Descrição

Este endpoint submete o draft para processamento. O PATCH valida completude - todos os campos obrigatórios devem estar presentes no payload do PATCH.

⚠️ IMPORTANTE: O PATCH sobrescreve completamente os dados do account_owner com o payload enviado. Isso significa que:

• Você deve enviar TODOS os campos obrigatórios no payload do PATCH, mesmo que já tenham sido enviados no POST
• Dados enviados apenas no POST serão perdidos se não forem reenviados no PATCH
• O comportamento é de substituição completa, não de merge/atualização parcial
• O campo documents dentro de cada company_representative é obrigatório e deve conter pelo menos um tipo de documento válido (RG, CNH, RNE, CRNM, Passaporte ou CIN Digital)

Após a submissão bem-sucedida, o status muda de draft para pending_bacen_validation e inicia a validação do Bacen Protege+.

Request Body

Request Body

{
  "account_owner": {
    "company_document_number": "46073462000130",
    "name": "EMPRESA EXEMPLO TECNOLOGIA LTDA",
    "person_type": "legal",
    "email": "empresa@exemplo.com.br",
    "phone": {
      "country_code": "055",
      "area_code": "11",
      "number": "999999999"
    },
    "trading_name": "Empresa Exemplo",
    "company_type": "LTDA",
    "foundation_date": "2010-01-15",
    "cnae_code": "6209-1/00",
    "company_statute": "92c93e9e-b249-46b7-8c2e-95d4955a3c39",
    "monthly_revenue": 150000.00,
    "address": {
      "street": "Av. Brigadeiro Faria Lima",
      "state": "SP",
      "city": "São Paulo",
      "neighborhood": "Jardim Paulistano",
      "number": "2391",
      "postal_code": "01452905",
      "complement": "Conjunto 102"
    },
    "company_representatives": [
      {
        "name": "João Carlos da Silva",
        "email": "joao.silva@exemplo.com.br",
        "birth_date": "1985-03-20",
        "individual_document_number": "12345678901",
        "is_pep": false,
        "mother_name": "Maria da Silva",
        "nationality": "brasileira",
        "person_type": "natural",
        "phone": {
          "country_code": "055",
          "area_code": "11",
          "number": "988888888"
        },
        "address": {
          "street": "Rua das Flores",
          "state": "SP",
          "city": "São Paulo",
          "neighborhood": "Jardins",
          "number": "123",
          "postal_code": "01310100",
          "complement": "Apto 45"
        },
        "representative_relationship": "ceo",
        "gender": "male",
        "marital_status": "married",
        "documents": {
          "rg": {
            "ocr_front_key": "0aa8a4ca-5873-49bd-851c-1f2c71a1cc28",
            "ocr_back_key": "29f6e346-7fae-4dcb-9ea1-2a3e4ef593ea"
          },
          "cnh": {
            "ocr_key": "7479c8e4-2a5d-4b4d-b2eb-4b841ec9390d"
          }
        },
        "face": "68da08f1-6cf4-4dce-a297-7b2f09311784"
      }
    ]
  },
  "additional_documents": [
    "61f2a65e-0ddf-4932-874f-9231794963da"
  ]
}

Response

STATUS

200

Response Body

{
  "account_request_key": "abc123-def456-...",
  "account_request_status": "pending_bacen_validation",
  "account_info": {
    "account_number": "1638634",
    "account_digit": "3",
    "account_branch": "0001"
  }
}

Fluxo Bacen Protege+

Após a submissão bem-sucedida, o status muda para pending_bacen_validation. O sistema realiza uma validação prévia junto ao Bacen Protege+ antes de prosseguir com a análise de KYC. Após aprovação do Bacen, o status será atualizado para pending_kyc_analysis automaticamente.

Request Body Params

Campo	Tipo	Descrição	Caracteres
additional_documents	array	Lista de UUIDs de documentos adicionais (array de UUIDs)	-
account_owner *	object	Informações completas do titular da conta (Pessoa Jurídica)	Objeto account_owner (PATCH)

Objeto account_owner (PATCH)

Campo	Tipo	Descrição	Caracteres
company_document_number *	string	CNPJ (14 dígitos, apenas números, padrão: ^[0-9]{14}$)	14
name *	string	Razão social	100
person_type *	enum	Sempre "legal"	Enumeradores person_type
email *	string	Email da empresa (formato email válido)	254
phone *	object	Telefone da empresa	Objeto phone
trading_name *	string	Nome fantasia	200
company_type *	enum	Tipo societário	Enumeradores company_type
foundation_date *	string	Data de fundação (formato: YYYY-MM-DD)	10
cnae_code *	string	Código CNAE da atividade	9
company_statute *	string	UUID do estatuto social (formato UUID)	36
monthly_revenue *	number	Faturamento mensal	-
address *	object	Endereço completo da empresa	Objeto address
company_representatives *	array	Lista de representantes legais (mínimo 1 item obrigatório)	Objeto company_representatives

Campos Obrigatórios no PATCH

TODOS os campos marcados com * são obrigatórios no PATCH. O schema JSON valida a completude de todos os campos antes de processar a submissão.

Objeto phone

Campo	Tipo	Descrição	Caracteres
country_code *	string	Código do país (1-3 dígitos, padrão: ^[0-9]{1,3}$)	1-3
area_code *	string	DDD (1-3 dígitos, padrão: ^[0-9]{1,3}$)	1-3
number *	string	Número do telefone (1-10 dígitos, padrão: ^[0-9]{1,10}$)	1-10
type	enum	Tipo de telefone (opcional: "residential", "commercial", "mobile", "fax")	-

Objeto address

Campo	Tipo	Descrição	Caracteres
street *	string	Rua/Logradouro	1-500
neighborhood *	string	Bairro	0-100
number *	string	Número	1-10
postal_code *	string	CEP (8 dígitos, apenas números, padrão: ^\d{8}$)	8
city *	string	Cidade	1-100
state *	enum	Estado (2 caracteres maiúsculos)	Enumeradores state
complement	string	Complemento (opcional, máximo 500 caracteres)	0-500

Objeto company_representatives

Campo	Tipo	Descrição	Caracteres
name *	string	Nome completo	100
address *	object	Endereço completo (mesma estrutura do address da empresa)	Objeto address
email *	string	Email (formato email válido)	5-200
birth_date *	string	Data de nascimento (formato: YYYY-MM-DD, padrão: `\d4-((0[1-9])	(1[0-2]))-((0[1-9])
individual_document_number *	string	CPF (11 dígitos, apenas números, padrão: ^[0-9]{11}$)	11
is_pep *	boolean	Se é Pessoa Politicamente Exposta	-
mother_name *	string	Nome da mãe	100
nationality *	string	Nacionalidade	50
person_type *	enum	Sempre "natural"	Enumeradores person_type
phone *	object	Telefone (mesma estrutura do phone da empresa)	Objeto phone
documents *	object	Documentos para antifraude (obrigatório no PATCH)	Objeto documents
face	string	UUID da foto facial (36 caracteres)	36
document_identification	string	UUID do documento de identificação (formato UUID)	36
document_identification_number	string	Número do documento de identificação	16
marital_status	enum	Estado civil	Enumeradores marital_status
gender	enum	Gênero	Enumeradores gender
representative_relationship	enum	Relação com a empresa	Enumeradores representative_relationship

Objeto documents

Campo	Tipo	Descrição	Caracteres
rg	object	Chaves OCR do upload da frente e verso do RG	Objeto rg
cnh	object	Chave OCR do upload da CNH	Objeto cnh
cnh_digital	object	Chave OCR do upload da CNH digital	Objeto cnh_digital
national_registry_of_foreigners	object	Chaves OCR do upload da frente e verso do RNE	Objeto national_registry_of_foreigners
national_migration_registry	object	Chaves OCR do upload da frente e verso do CRNM	Objeto national_migration_registry
passport	object	Chave OCR do upload do passaporte	Objeto passport
cin_digital	object	Chave OCR do upload da Cédula de Identidade Nacional digital	Objeto cin_digital

Objeto rg

Campo	Tipo	Descrição	Caracteres
ocr_front_key *	uuidv4	Chave OCR do upload da imagem da frente do RG	36
ocr_back_key *	uuidv4	Chave OCR do upload da imagem do verso do RG	36

OU

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem do RG	36

Objeto cnh

Campo	Tipo	Descrição	Caracteres
ocr_front_key *	uuidv4	Chave OCR do upload da imagem da frente da CNH	36
ocr_back_key *	uuidv4	Chave OCR do upload da imagem do verso da CNH	36

OU

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem da CNH	36

Objeto cnh_digital

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem da CNH digital	36

Objeto national_registry_of_foreigners

Campo	Tipo	Descrição	Caracteres
ocr_front_key *	uuidv4	Chave OCR do upload da imagem da frente do RNE	36
ocr_back_key *	uuidv4	Chave OCR do upload da imagem do verso do RNE	36

OU

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem do RNE	36

Objeto national_migration_registry

Campo	Tipo	Descrição	Caracteres
ocr_front_key *	uuidv4	Chave OCR do upload da imagem da frente do CRNM	36
ocr_back_key *	uuidv4	Chave OCR do upload da imagem do verso do CRNM	36

OU

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem do CRNM	36

Objeto passport

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem do passaporte	36

Objeto cin_digital

Campo	Tipo	Descrição	Caracteres
ocr_key *	uuidv4	Chave OCR do upload da imagem da Cédula de Identidade Nacional digital	36

Informação

As chaves OCR (ocr_key ou ocr_front_key e ocr_back_key) do upload das imagens dos documentos são fornecidas como resposta do upload das imagens no antifraude. A face_recognition_key é retornada na resposta do reconhecimento facial.

Response Body Params

Campo	Tipo	Descrição	Caracteres
account_request_key *	string	Chave de identificação da requisição de criação	-
account_request_status *	string	Status da requisição (muda para pending_bacen_validation após submissão)	-
account_info *	object	Objeto contendo as informações da conta	Objeto account_info

Objeto account_info

Campo	Tipo	Descrição	Caracteres
account_branch *	string	Número da Agência	4
account_digit *	string	Dígito verificador da conta	1
account_number *	string	Número da conta	-

Error Response

STATUS

4xx

Response Body: Error

{
  "title": "titulo",
  "description": "description in English",
  "translation": "descrição em portugues",
  "code": "codigo",
  "extra_fields": {}
}

Código HTTP status	Código QI code	Título title	Descrição (eng) description	Descrição(ptbr) translation
400	QIT000001	Bad Request	Schema Error	Erro de Schema
400	-	Bad Request	Invalid request body	Corpo da requisição inválido
404	QIT000404	Not Found	Resource could not be found	Recurso não encontrado
409	-	Conflict	Duplicate request_control_key	Chave de controle duplicada

---

Diferenças entre POST e PATCH

Aspecto	POST (Criar Draft)	PATCH (Submeter Draft)
Objetivo	Criar draft com flexibilidade	Validar completude e submeter ao Bacen
Campos Obrigatórios	Apenas CNPJ + Nome + Tipo	TODOS os campos + 1 representante completo com documents
documents	Opcional por representante	Obrigatório por representante (objeto com documentos OCR)
Representantes	Opcional	Obrigatório (mínimo 1)
Validação	Mínima (apenas 3 campos)	Completa (todos os campos obrigatórios)
Status Inicial	N/A	draft (deve estar neste status)
Status Final	draft	pending_bacen_validation
Validação Bacen	Não	Sim
Análise KYC	Não	Sim (após Bacen)
Idempotência	Sim (via request_control_key)	Não

---

Cenários de Uso

Cenário 1: Cliente tem apenas dados básicos inicialmente

POST → {CNPJ, nome, tipo}  [status: draft]
...cliente coleta mais dados...
PATCH → {todos os campos + documents por representante} [status: pending_bacen_validation]

Cenário 2: Cliente tem todos os dados de uma vez

POST → {todos os campos}  [status: draft]
PATCH → {todos os campos} [status: pending_bacen_validation]

Cenário 3: Cliente envia dados parciais gradualmente

POST → {CNPJ, nome, tipo, email}  [status: draft]
...cliente coleta mais dados...
PATCH → {todos os campos incluindo representantes com documents} [status: pending_bacen_validation]

---

Enumeradores

Enumeradores person_type

Enum	Descrição
natural	Pessoa física
legal	Pessoa jurídica

Enumeradores company_type

Enum	Descrição
ltda	Limitada
sa	Sociedade Anônima
micro_enterprise	Micro Empresa
freelancer	Freelancer
sa_opened	Sociedade Anônima de Capital Aberto
sa_closed	Sociedade Anônima de Capital Fechado
se_ltda	Sociedade Empresária Limitada
se_cn	Sociedade Empresária em Nome Coletivo
se_cs	Sociedade Empresária em Comandita Simples
se_ca	Sociedade Empresária em Comandita por Ações
scp	Sociedade em Conta de Participação
ei	Empresário Individual
ese	Estabelecimento, no Brasil, de Sociedade Estrangeira
eeab	Estabelecimento, no Brasil, de Empresa Binacional Argentino-Brasileira
ssp	Sociedade Simples Pura
ss_ltda	Sociedade Simples Limitada
ss_cn	Sociedade Simples em Nome Coletivo
ss_cs	Sociedade Simples em Comandita Simples
eireli_ne	Empresa Individual de Responsabilidade Limitada (de Natureza Empresária)
eireli_ns	Empresa Individual de Responsabilidade Limitada (de Natureza Simples)
eireli	Empresa de Responsabilidade Individual
mei	Micro Empreendedor Individual
me	Micro Empresa
cop	Cooperativa
private_association	Sociedade Privada

Enumeradores state

Enum	Descrição
AC	Acre
AL	Alagoas
AM	Amazonas
AP	Amapá
BA	Bahia
CE	Ceará
DF	Distrito Federal
ES	Espírito Santo
GO	Goiás
MA	Maranhão
MG	Minas Gerais
MS	Mato Grosso do Sul
MT	Mato Grosso
PA	Pará
PB	Paraíba
PE	Pernambuco
PI	Piauí
PR	Paraná
RJ	Rio de Janeiro
RN	Rio Grande do Norte
RO	Rondônia
RR	Roraima
RS	Rio Grande do Sul
SC	Santa Catarina
SE	Sergipe
SP	São Paulo
TO	Tocantins
EX	Exterior

Enumeradores marital_status

Enum	Descrição
single	Solteiro(a)
married	Casado(a)
widower	Viúvo(a)
divorced	Divorciado(a)
separated	Separado(a)

Enumeradores gender

Enum	Descrição
male	Masculino
female	Feminino

Enumeradores representative_relationship

Enum	Descrição
ceo	CEO / Diretor Presidente
analyst	Analista
partner	Sócio
director	Diretor
attorney	Procurador
signer	Assinante

---

Fluxo Completo

1. POST /v2/account_request/draft_checking_legal_person

   • Cria draft com dados disponíveis
   • Status: draft
   • Retorna: account_request_key

2. (Opcional) Coletar dados adicionais

3. PATCH /v2/account_request/{account_request_key}/draft_checking_legal_person

   • Valida completude de todos os campos
   • Envia para Bacen Protege+
   • Status: pending_bacen_validation

4. Bacen Protege+ valida (assíncrono)

   • Status: pending_kyc_analysis (se aprovado)

5. KYC analisa pessoa jurídica

   • Status: approved (se tudo OK)

6. Conta criada e pronta para uso

---