自由活动账户草稿 - 法人

Draft Checking Legal Person 流程允许分两步创建账户开户申请：

POST：以最大灵活性创建草稿（draft）——从最少数据到完整数据均可接受
PATCH：将草稿提交处理，验证所有必填字段的完整性

重要：此流程正在为与 Monte Bravo 的集成做准备。POST 和 PATCH 之间的字段划分将在与 Monte Bravo 确认每个流程节点可用数据后进行调整。

创建法人账户草稿

Request

ENDPOINT

/v2/account_request/draft_checking_legal_person

MÉTODO

POST

描述

此端点为法人（Legal Person）创建账户开户草稿。POST 接受从最少数据到完整数据，提供最大灵活性。

灵活性策略

最少数据：CNPJ + 名称 + 人员类型
部分数据：根据可用情况添加字段
完整数据：一次性发送全部（较少见）

示例 1：最小载荷（仅必填项）

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

行为：如果再次使用相同的 request_control_key，将返回 409（Conflict）错误，而不是创建新草稿。

示例 2：完整载荷（一次性发送全部数据）

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,
        "final_beneficiary": true,
        "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"
  }
}

注意

account_request_key 字段必须保存，并将用于通过 PATCH 提交草稿。

请求体参数

字段	类型	描述	字符数
`request_control_key`	string	用于保证幂等性的 UUID（36 字符）	36
`reserved_account_key`	string	预留账户的 UUID（36 字符）	36
`account_owner` *	object	账户持有人信息（法人）	account_owner 对象（POST）

account_owner 对象（POST）

字段	类型	描述	字符数
`company_document_number` *	string	公司 CNPJ（14 位，仅数字）	14
`name` *	string	公司法定名称	100
`person_type` *	enum	人员类型（始终为 "legal"）	person_type 枚举值
`email`	string	公司电子邮箱（有效邮箱格式）	254
`phone`	object	公司电话	phone 对象
`trading_name`	string	公司商号	200
`company_type`	enum	公司组织形式	company_type 枚举值
`foundation_date`	string	成立日期（格式：YYYY-MM-DD）	10
`cnae_code`	string	CNAE 活动代码	9
`company_statute`	string	公司章程 UUID（UUID 格式）	36
`monthly_revenue`	number	月营业额	-
`address`	object	公司完整地址	address 对象
`company_representatives`	array	法定代表人列表（发送时至少 1 人）	company_representatives 对象

POST 中的必填字段

POST 中只有 3 个字段为必填：

company_document_number
name
person_type

其余所有字段均为可选，可根据可用情况发送。

代表人验证

如果在 POST 中发送 company_representatives，必须至少包含 1 个项目（minItems: 1）。每位代表必须填写所有必填字段（见 PATCH 部分）。每位代表内的 documents 字段在 POST 中为可选。

提交法人账户草稿

Request

ENDPOINT

/v2/account_request/{account_request_key}/draft_checking_legal_person

MÉTODO

PATCH

描述

此端点提交草稿进行处理。PATCH 验证完整性——所有必填字段必须存在于 PATCH 载荷中。

⚠️ 重要：PATCH 会用所发送的载荷完全覆盖 account_owner 的数据。这意味着：

您必须在 PATCH 载荷中发送所有必填字段，即使这些字段已在 POST 中发送过
仅在 POST 中发送的数据如果不在 PATCH 中重新发送将丢失
此行为是完全替换，不是合并/部分更新
每个 company_representative 中的 documents 字段为必填，必须至少包含一种有效证件类型（身份证、驾照、RNE、CRNM、护照或数字 CIN）

提交成功后，状态从 draft 变更为 pending_bacen_validation，并启动 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,
        "final_beneficiary": true,
        "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"
  }
}

Bacen Protege+ 流程

提交成功后，状态变更为 pending_bacen_validation。系统在进行 KYC 分析前会先向 Bacen Protege+ 进行预验证。Bacen 批准后，状态将自动更新为 pending_kyc_analysis。

请求体参数

字段	类型	描述	字符数
`additional_documents`	array	附加文件 UUID 列表（UUID 数组）	-
`account_owner` *	object	账户持有人完整信息（法人）	account_owner 对象（PATCH）

account_owner 对象（PATCH）

字段	类型	描述	字符数
`company_document_number` *	string	CNPJ（14 位，仅数字，格式：`^[0-9]{14}$`）	14
`name` *	string	公司法定名称	100
`person_type` *	enum	始终为 `"legal"`	person_type 枚举值
`email` *	string	公司电子邮箱（有效邮箱格式）	254
`phone` *	object	公司电话	phone 对象
`trading_name` *	string	公司商号	200
`company_type` *	enum	公司组织形式	company_type 枚举值
`foundation_date` *	string	成立日期（格式：YYYY-MM-DD）	10
`cnae_code` *	string	CNAE 活动代码	9
`company_statute` *	string	公司章程 UUID（UUID 格式）	36
`monthly_revenue` *	number	月营业额	-
`address` *	object	公司完整地址	address 对象
`company_representatives` *	array	法定代表人列表（至少 1 人为必填）	company_representatives 对象

PATCH 中的必填字段

所有标注 * 的字段在 PATCH 中均为必填。JSON schema 在处理提交之前会验证所有字段的完整性。

phone 对象

字段	类型	描述	字符数
`country_code` *	string	国家代码（1-3 位数字，格式：`^[0-9]{1,3}$`）	1-3
`area_code` *	string	DDD（1-3 位数字，格式：`^[0-9]{1,3}$`）	1-3
`number` *	string	电话号码（1-10 位数字，格式：`^[0-9]{1,10}$`）	1-10
`type`	enum	电话类型（可选：`"residential"`、`"commercial"`、`"mobile"`、`"fax"`）	-

address 对象

字段	类型	描述	字符数
`street` *	string	街道/地址	1-500
`neighborhood` *	string	社区/街区	0-100
`number` *	string	门牌号	1-10
`postal_code` *	string	CEP（8 位数字，格式：`^\d{8}$`）	8
`city` *	string	城市	1-100
`state` *	enum	州（两位大写字母）	state 枚举值
`complement`	string	补充说明（可选，最多 500 字符）	0-500

company_representatives 对象

字段	类型	描述	字符数
`name` *	string	全名	100
`address` *	object	完整地址（与公司 address 结构相同）	address 对象
`email` *	string	电子邮箱（有效邮箱格式）	5-200
`birth_date` *	string	出生日期（格式：YYYY-MM-DD）	10
`individual_document_number` *	string	CPF（11 位，仅数字，格式：`^[0-9]{11}$`）	11
`is_pep` *	boolean	是否为政治公众人物（PEP）	-
`final_beneficiary`	boolean	声明该人是否为公司的最终受益人。	-
`mother_name` *	string	母亲姓名	100
`nationality` *	string	国籍	50
`person_type` *	enum	始终为 `"natural"`	person_type 枚举值
`phone` *	object	电话（与公司 phone 结构相同）	phone 对象
`documents` *	object	反欺诈证件（PATCH 中为必填）	documents 对象
`face`	string	人脸照片 UUID（36 字符）	36
`document_identification`	string	身份证件 UUID（UUID 格式）	36
`document_identification_number`	string	身份证件号码	16
`marital_status`	enum	婚姻状况	marital_status 枚举值
`gender`	enum	性别	gender 枚举值
`representative_relationship`	enum	与公司的关系	representative_relationship 枚举值

documents 对象

字段	类型	描述	字符数
`rg`	object	身份证正反面 OCR 上传密钥	rg 对象
`cnh`	object	驾照 OCR 上传密钥	cnh 对象
`cnh_digital`	object	数字驾照 OCR 上传密钥	cnh_digital 对象
`national_registry_of_foreigners`	object	外国人登记（RNE）正反面 OCR 上传密钥	national_registry_of_foreigners 对象
`national_migration_registry`	object	外国人移民登记（CRNM）正反面 OCR 上传密钥	national_migration_registry 对象
`passport`	object	护照 OCR 上传密钥	passport 对象
`cin_digital`	object	数字国家身份证（CIN）OCR 上传密钥	cin_digital 对象

rg 对象

字段	类型	描述	字符数
`ocr_front_key` *	uuidv4	身份证正面图片 OCR 上传密钥	36
`ocr_back_key` *	uuidv4	身份证背面图片 OCR 上传密钥	36

或

字段	类型	描述	字符数
`ocr_key` *	uuidv4	身份证图片 OCR 上传密钥	36

cnh 对象

字段	类型	描述	字符数
`ocr_front_key` *	uuidv4	驾照正面图片 OCR 上传密钥	36
`ocr_back_key` *	uuidv4	驾照背面图片 OCR 上传密钥	36

或

字段	类型	描述	字符数
`ocr_key` *	uuidv4	驾照图片 OCR 上传密钥	36

cnh_digital 对象

字段	类型	描述	字符数
`ocr_key` *	uuidv4	数字驾照图片 OCR 上传密钥	36

national_registry_of_foreigners 对象

字段	类型	描述	字符数
`ocr_front_key` *	uuidv4	RNE 正面图片 OCR 上传密钥	36
`ocr_back_key` *	uuidv4	RNE 背面图片 OCR 上传密钥	36

或

字段	类型	描述	字符数
`ocr_key` *	uuidv4	RNE 图片 OCR 上传密钥	36

national_migration_registry 对象

字段	类型	描述	字符数
`ocr_front_key` *	uuidv4	CRNM 正面图片 OCR 上传密钥	36
`ocr_back_key` *	uuidv4	CRNM 背面图片 OCR 上传密钥	36

或

字段	类型	描述	字符数
`ocr_key` *	uuidv4	CRNM 图片 OCR 上传密钥	36

passport 对象

字段	类型	描述	字符数
`ocr_key` *	uuidv4	护照图片 OCR 上传密钥	36

cin_digital 对象

字段	类型	描述	字符数
`ocr_key` *	uuidv4	数字国家身份证图片 OCR 上传密钥	36

说明

证件图片上传的 OCR 密钥（ocr_key 或 ocr_front_key 和 ocr_back_key）由反欺诈图片上传的响应提供。face_recognition_key 在人脸识别响应中返回。

响应体参数

字段	类型	描述	字符数
`account_request_key` *	string	创建申请的识别密钥	-
`account_request_status` *	string	申请状态（提交后变更为 `pending_bacen_validation`）	-
`account_info` *	object	包含账户信息的对象	account_info 对象

account_info 对象

字段	类型	描述	字符数
`account_branch` *	string	分行号	4
`account_digit` *	string	账户验证位	1
`account_number` *	string	账户号码	-

错误响应

STATUS

4xx

Response Body: Error

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

HTTP 代码 `status`	QI 代码 `code`	标题 `title`	描述（英文） `description`	描述（葡文） `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

POST 和 PATCH 的区别

方面	POST（创建草稿）	PATCH（提交草稿）
目的	以灵活方式创建草稿	验证完整性并提交至 Bacen
必填字段	仅 CNPJ + 名称 + 类型	所有字段 + 1 位带 documents 的完整代表人
documents	每位代表人可选	每位代表人必填（含 OCR 证件对象）
代表人	可选	必填（至少 1 人）
验证	最低限度（仅 3 个字段）	完整（所有必填字段）
初始状态	N/A	`draft`（必须处于此状态）
最终状态	`draft`	`pending_bacen_validation`
Bacen 验证	否	是
KYC 分析	否	是（Bacen 之后）
幂等性	是（通过 `request_control_key`）	否

使用场景

场景 1：客户最初只有基本数据

POST → {CNPJ, 名称, 类型}  [状态：draft]
...客户收集更多数据...
PATCH → {所有字段 + 每位代表人的 documents} [状态：pending_bacen_validation]

场景 2：客户一次性拥有所有数据

POST → {所有字段}  [状态：draft]
PATCH → {所有字段} [状态：pending_bacen_validation]

场景 3：客户逐步发送部分数据

POST → {CNPJ, 名称, 类型, 邮箱}  [状态：draft]
...客户收集更多数据...
PATCH → {所有字段，包括带 documents 的代表人} [状态：pending_bacen_validation]

枚举值

person_type 枚举值

枚举值	描述
`natural`	个人
`legal`	法人

company_type 枚举值

枚举值	描述
`ltda`	有限责任公司
`sa`	股份公司
`micro_enterprise`	微型企业
`freelancer`	自由职业者
`sa_opened`	上市股份公司
`sa_closed`	非上市股份公司
`se_ltda`	有限责任企业公司
`se_cn`	普通合伙企业公司
`se_cs`	有限合伙企业公司
`se_ca`	股份有限合伙企业公司
`scp`	参与账户合伙公司
`ei`	个体工商户
`ese`	外国公司在巴西的分支机构
`eeab`	阿根廷-巴西双边公司在巴西的分支机构
`ssp`	简单合伙公司
`ss_ltda`	有限简单合伙公司
`ss_cn`	普通合伙简单公司
`ss_cs`	有限合伙简单公司
`eireli_ne`	个人有限责任公司（商业性质）
`eireli_ns`	个人有限责任公司（简单性质）
`eireli`	个人责任公司
`mei`	个体微型企业主
`me`	微型企业
`cop`	合作社
`private_association`	私人协会

state 枚举值

枚举值	描述
`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`	境外

marital_status 枚举值

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

gender 枚举值

枚举值	描述
`male`	男性
`female`	女性

representative_relationship 枚举值

枚举值	描述
`ceo`	CEO / 总裁
`analyst`	分析师
`partner`	合伙人
`director`	董事
`attorney`	代理人
`signer`	签署人

完整流程

POST /v2/account_request/draft_checking_legal_person
- 使用可用数据创建草稿
- 状态：draft
- 返回：account_request_key
（可选） 收集附加数据
PATCH /v2/account_request/{account_request_key}/draft_checking_legal_person
- 验证所有字段的完整性
- 提交至 Bacen Protege+
- 状态：pending_bacen_validation
Bacen Protege+ 验证（异步）
- 状态：pending_kyc_analysis（批准后）
KYC 分析法人
- 状态：approved（一切正常时）
账户创建完成并可使用

创建法人账户草稿​

Request​

描述​

灵活性策略​

示例 1：最小载荷（仅必填项）​

示例 2：完整载荷（一次性发送全部数据）​

Response​

请求体参数​

account_owner 对象（POST）​

提交法人账户草稿​

Request​

描述​

Request Body​

Response​

请求体参数​

account_owner 对象（PATCH）​

phone 对象​

address 对象​

company_representatives 对象​

documents 对象​

rg 对象​

cnh 对象​

cnh_digital 对象​

national_registry_of_foreigners 对象​

national_migration_registry 对象​

passport 对象​

cin_digital 对象​

响应体参数​

account_info 对象​

错误响应​

POST 和 PATCH 的区别​

使用场景​

场景 1：客户最初只有基本数据​

场景 2：客户一次性拥有所有数据​

场景 3：客户逐步发送部分数据​

枚举值​

person_type 枚举值​

company_type 枚举值​

state 枚举值​

marital_status 枚举值​

gender 枚举值​

representative_relationship 枚举值​

完整流程​

创建法人账户草稿

Request

描述

灵活性策略

示例 1：最小载荷（仅必填项）

示例 2：完整载荷（一次性发送全部数据）

Response

请求体参数

account_owner 对象（POST）

提交法人账户草稿

Request

描述

Request Body

Response

请求体参数

account_owner 对象（PATCH）

phone 对象

address 对象

company_representatives 对象

documents 对象

rg 对象

cnh 对象

cnh_digital 对象

national_registry_of_foreigners 对象

national_migration_registry 对象

passport 对象

cin_digital 对象

响应体参数

account_info 对象

错误响应

POST 和 PATCH 的区别

使用场景

场景 1：客户最初只有基本数据

场景 2：客户一次性拥有所有数据

场景 3：客户逐步发送部分数据

枚举值

person_type 枚举值

company_type 枚举值

state 枚举值

marital_status 枚举值

gender 枚举值

representative_relationship 枚举值

完整流程