开户 — 企业 (PJ)

本指南介绍如何开立企业账户。与 PF 的区别：股权结构中的每位股东（或合作社的法定董事）都需要完成人脸生物识别，您须按公司类型上传公司 PDF，且所有 PJ 开户在账户开立前都要经过分析师的事先审核。

流程

第 1 步：创建 accreditation

请求

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pj" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-company-9876" \
  -d '{
    "company": {
      "legalName": "Empresa Exemplo LTDA",
      "tradeName": "Exemplo",
      "cnpj": "12345678000199",
      "email": "financeiro@exemplo.com",
      "phone": "+5511333334444",
      "monthlyRevenue": 150000.00,
      "legalForm": "ltda"
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    },
    "partners": [
      {
        "name": "João Souza",
        "cpf": "11122233344",
        "birthDate": "1985-03-10",
        "email": "joao@exemplo.com",
        "phone": "+5511988887777",
        "ownershipPercent": 60,
        "isAdministrator": true
      },
      {
        "name": "Ana Lima",
        "cpf": "55566677788",
        "birthDate": "1992-11-02",
        "email": "ana@exemplo.com",
        "phone": "+5511977776666",
        "ownershipPercent": 40,
        "isAdministrator": false
      }
    ]
  }'

参数

字段	类型	必填	说明
`company.legalName`	string	是	公司注册名称。
`company.tradeName`	string	是	商号。清算机构对 CNPJ 强制要求该字段。若公司没有登记商号，请填写公司注册名称。
`company.cnpj`	string	是	CNPJ（14 位数字，无标点）。
`company.email` / `company.phone`	string	是	公司联系方式。
`company.monthlyRevenue`	number	否	申报月营业额（BRL）。
`company.legalForm`	string	否	公司类型：`mei`、`ltda`（默认）、`sa`、`cooperative`。决定必填 PDF。
`address.*`	object	是	公司地址。`neighborhood`（街区）必填（或旧字段 `district`）。`cityIbgeCode` 为 7 位 IBGE 代码。
`partners[]`	array	是	股权结构（若 `legalForm=cooperative` 则为法定董事）。至少一位须 `isAdministrator: true`。
`partners[].name` / `cpf` / `birthDate`	—	是	每位股东/董事信息。所有人都需完成人脸生物识别。
`partners[].email` / `phone`	string	是	联系方式 — 用于生物识别流程。
`partners[].ownershipPercent`	number	是	持股比例（%）。
`partners[].isAdministrator`	boolean	是	是否为管理人。
`partners[].biometry`	object	否	仅用于自带生物识别流程。
`callbackUri`	string	否	每位股东完成生物识别后把他带回何处。需事先向支持团队登记 —— 参见返回您的应用。

初始 PIX 限额将自动应用保守默认值。限额变更（上调或下调）需向支持人工申请。

合作社

legalForm=cooperative 时，在 partners[] 中填写法定董事（非全体社员名单）。必填文件与 sa 相同。

响应 (201)

{
  "accreditationId": "acr_1a2b3c4d5e6f",
  "type": "pj",
  "status": "PENDING_BIOMETRY",
  "legalForm": "ltda",
  "requiredDocumentKinds": ["company_articles", "company_proof_of_address"],
  "missingDocumentKinds": ["company_articles", "company_proof_of_address"],
  "documents": [],
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "11122233344",
      "name": "João Souza",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc111...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    },
    {
      "personId": "prs_8d2f4e6a1c0b",
      "cpf": "55566677788",
      "name": "Ana Lima",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc222...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-07T18:00:00Z"
}

账户尚未绑定

在 PENDING_BIOMETRY 期间，CNPJ 不会绑定到 tenant，且 POST 不会去重——用同一 CNPJ 重复请求会创建新的 accreditation。请用 POST /v1/accreditations/{id}/cancel 取消放弃的待处理流程。

异步链接

biometryLink 会在数秒内生成，但生成过程是异步的——POST 响应中可能暂缺这些字段。此时请通过 accreditation.biometry.link.created webhook（按股东逐一发出）接收，或随后调用 GET 查询。

第 2 步：上传公司 PDF

201 之后，按 legalForm 上传必填文件（一律 application/pdf）：

legalForm	必填	可选
`mei`、`ltda`	`company_articles`、`company_proof_of_address`	`business_license`、`regulatory_license`、`other`
`sa`、`cooperative`	LTDA 套件 + `cnpj_card`、`financial_statements`	同上

有类型的 kind：每个 accreditation 一份（重新上传会替换）。
other：可多份；fileName 必填。
文件时效（如地址证明）由运营在事先审核中核对。

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/documents" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "company_articles",
    "fileName": "contrato-social.pdf",
    "contentType": "application/pdf"
  }'

响应含 uploadUrl（PUT，1 小时有效）。对每个必填 kind 重复。accreditation 的 GET 会显示 documents[] 与 missingDocumentKinds[]。

PUT 之后，文件先经过病毒扫描和净化处理（PDF 会被栅格化）再归档，通常只需几秒。若文件实际不是 PDF，或已被感染、损坏，则会被拒绝并在运营审核中显示为拒绝；此时请用正确的文件重新上传。

第 3 步：将链接交付给每位股东

每位股东都会收到自己专属的 biometryLink，须各自完成流程。当所有股东的生物识别都通过后，accreditation 进入审核（PDF 可并行上传）。

每个链接 7 天后过期 — 按人跟踪 linkExpiresAt。
accreditation.biometry.link.created 事件按股东逐一发出。
待处理的股东在 GET 中显示 biometryStatus: "PENDING"。

第 4 步：事先审核

全部生物识别通过后，accreditation 进入 PENDING_REVIEW — 所有 PJ 都要经过事先审核。理想情况下必填 PDF 已上传（missingDocumentKinds 为空）；分析师可在详情中看到缺口。进入和离开该阶段时您都会收到 accreditation.updated。通常 1 个工作日内完成。

批准（文件齐全）→ INTEGRATING，在清算方开立账户。
强制批准 — 若仍缺 PDF，运营可用 forceIncompleteDocuments: true + reason 强制通过；记录为 accreditation 上的 documentsOverride*。
拒绝 → 状态变为 FAILED，errorReason 说明原因。

第 5 步：账户就绪

账户开立后您会收到 accreditation.active。accountId 已绑定到您的 tenant，可以操作。

按股东重试

如果某位股东的链接过期或采集失败，只为该股东生成新链接 — 其他人不受影响：

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/persons/55566677788/retry" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"

取消

状态仍为 PENDING_BIOMETRY 时，可取消整笔 accreditation：

curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/cancel" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{"reason":"company abandoned onboarding"}'

查询

curl -X GET "https://tenant.api.corpx.com/v1/accreditations/pj?document=12345678000199" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"

响应包含聚合状态和每位股东的详情（各自的 biometryStatus、链接和过期时间），方便您在系统中搭建跟踪界面。

流程​

第 1 步：创建 accreditation​

请求​

参数​

响应 (201)​

第 2 步：上传公司 PDF​

第 3 步：将链接交付给每位股东​

第 4 步：事先审核​

第 5 步：账户就绪​

按股东重试​

取消​

查询​

流程