> ## Documentation Index
> Fetch the complete documentation index at: https://docs.localpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 通过实体共享 KYB 信息

> 使用实体 API 发送子商户的 KYB 信息：公司、其所有者、其法定代表人及其文件。

本指南逐个调用地展示（含请求与响应）如何使用 Entities API 发送[虚拟账户受益人的KYB要求](https://docs.localpayment.com/zh/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md)中列出的信息。每一项在 Entities 中的位置见该页面的“如何发送”列。简而言之：公司是类型为 `COMPANY` 的实体，每个人是类型为 `INDIVIDUAL` 的实体（所有者作为 UBO 关联到公司），每份文件都是附带其文件的已声明文件。示例使用一家在巴西注册的虚构公司。

## 先决条件

* 此流程适用于巴西的虚拟账户。
* Stage 访问令牌。请参阅[获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)。
* 已为您的商户发布了包含 KYB 字段的自定义字段架构。请参阅[自定义字段](https://docs.localpayment.com/zh/docs/custom-fields.md)。
* 公司、其所有者及其法定代表人的信息和文件。请参阅[虚拟账户受益人的KYB要求](https://docs.localpayment.com/zh/docs/kyb-requirements-for-sub-merchants-and-virtual-account-end-beneficiaries.md)。

## 流程

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'background': '#ffffff', 'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'secondaryColor': '#31467c', 'tertiaryColor': '#ffffff', 'lineColor': '#0c1a29', 'textColor': '#0c1a29', 'edgeLabelBackground': '#ffffff', 'fontFamily': 'Manrope'}, 'fontFamily': 'Manrope', 'htmlLabels': false, 'flowchart': {'htmlLabels': false, 'wrappingWidth': 400, 'padding': 20}}}%%
flowchart TD
    A["1. 读取您的自定义字段 schema<br/>GET /api/entity/v1/custom-fields/schema"]:::lp --> B["2. 创建公司<br/>POST /api/entity/v1/entities, 类型为 COMPANY<br/>税号作为主要证件，企业资料放在 attributes 中"]
    B --> DH["3. 公司证件<br/>每份证件单独创建，并附带各自的文件"]:::lp
    DH --> D1["ARTICLES_OF_INCORPORATION<br/>必要时附上股权结构图"]
    DH --> D2["PROOF_OF_FUNDS<br/>每份证件一个文件"]
    DH --> D3["OTHER<br/>所有权证明，B2C"]
    D1 & D2 & D3 --> PH["4 和 5. 人员<br/>每位所有者及法定代表人各创建一个 INDIVIDUAL<br/>各附其身份证件"]:::lp
    PH --> P1["所有者 1<br/>身份证件<br/>FRONT, BACK"]
    PH --> P2["所有者 2、3 等<br/>步骤相同"]
    PH --> P3["法定代表人<br/>步骤相同"]
    P1 --> L1["6. 关联到公司，所有者 1<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage"]
    P2 --> L2["6. 关联到公司，其他每位所有者<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage"]
    P3 --> L3["6. 关联到公司，法定代表人<br/>POST /api/entity/v1/entities/{companyId}/ubos<br/>ownershipPercentage 0, controlRole LEGAL_REPRESENTATIVE"]
    L1 & L2 & L3 --> V["7. 通知 Localpayment 上传已完成<br/>POST /api/entity/v1/entities/{companyId}/verify"]
    V --> G[/"Localpayment 审核<br/>公司及每个人员"/]:::lp
    classDef default fill:#31467c,stroke:#0c1a29,stroke-width:1px,color:#ffffff,font-family:Manrope
    classDef lp fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef terminal fill:#0c1a29,stroke:#0c1a29,color:#ffffff
    classDef lbl fill:#0c1a29,stroke:#0c1a29,color:#ffffff,font-size:13px
```

> [!NOTE]
>
> **法定代表人。** 将其创建为 `INDIVIDUAL`（其身份证明文件可作为主要文件），并通过[关联 UBO](https://docs.localpayment.com/zh/reference/link-ubo.md) 将其关联到公司：`ownershipPercentage: 0` 和 `controlRole: LEGAL_REPRESENTATIVE`。如果法定代表人同时也是所有者，则只需关联一次，使用其持股比例和 `controlRole: LEGAL_REPRESENTATIVE`。

## 分步操作

按以下顺序执行下列调用。保留 API 返回的每个 `internalId` 和 `documentId`。示例仅发送最少必需的内容。

### 阅读您的自定义字段架构

`GET /api/entity/v1/custom-fields/schema` 返回您的账户接受的属性。以下为包含业务概况的节选：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "businessProfile": {
    "type": "string",
    "enum": [
      "MARKETPLACE",
      "B2C",
      "B2B"
    ]
  }
}
```

### 创建公司

`POST /api/entity/v1/entities`。税号为主要文件，业务概况放在 `attributes` 中：

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "COMPANY",
  "name": "Example Company S.A.",
  "residenceCountry": "BRA",
  "document": {
    "type": "CNPJ",
    "id": "00000000000100",
    "issuingCountry": "BRA"
  },
  "website": "https://www.example.com",
  "attributes": {
    "businessProfile": "B2C"
  }
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "externalId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "type": "COMPANY",
  "status": "PENDING_KYC",
  "name": "Example Company S.A.",
  "residenceCountry": "BRA",
  "website": "https://www.example.com",
  "attributes": {
    "businessProfile": "B2C"
  },
  "documentationStatus": "NO_FILES"
}
```

响应为 201 Created（节选）。主要文件会返回其 `documentId` 且不含文件，这是预期行为：它不需要文件。

### 申报公司文件并上传文件

使用 `POST /api/entity/v1/entities/{companyId}/documents` 声明每份文件。公司注册文件在 `id` 中携带注册号（在巴西为 CNPJ）：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "ARTICLES_OF_INCORPORATION",
  "id": "00000000000100",
  "issuingCountry": "BRA"
}
```

然后针对每个文件发送一次 `POST /api/entity/v1/documents/{documentId}/proofs`，并设置 `proofType=DOCUMENT` 及该文件。响应（节选）：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "4653bc4d-7df4-41c4-b8ef-60e7a3a378bb",
  "documentId": "84f3b6db-7b74-4def-968d-cbb5bf90cab7",
  "proofType": "DOCUMENT",
  "fileName": "certificate_of_incorporation.pdf",
  "mimeType": "application/pdf",
  "verificationStatus": "PENDING",
  "status": "CURRENT"
}
```

以同样的方式声明并上传资金来源文件，以及（对于 `B2C`）所有权证明：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "type": "PROOF_OF_FUNDS",
    "id": "SALES-2024-Q1",
    "issuingCountry": "BRA"
  },
  {
    "type": "OTHER",
    "id": "DOMAIN-example",
    "issuingCountry": "BRA"
  }
]
```

### 创建每个人

每位所有者以及法定代表人各创建一个 `INDIVIDUAL`，使用 `POST /api/entity/v1/entities`。身份证明文件可作为主要文件：

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "INDIVIDUAL",
  "name": "Jane",
  "lastname": "Doe",
  "residenceCountry": "BRA",
  "document": {
    "type": "NATIONAL_ID",
    "id": "000000000",
    "issuingCountry": "BRA"
  }
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "type": "INDIVIDUAL",
  "status": "PENDING_KYC",
  "document": {
    "documentId": "e6d636a0-362c-4e17-9ac9-5451d56ed393",
    "type": "NATIONAL_ID",
    "id": "000000000",
    "issuingCountry": "BRA",
    "isPrimary": true
  }
}
```

响应为 201 Created（节选）。

### 上传每个人的身份证明文件

正反面都上传到同一份文件：先使用 `proofType=FRONT` 调用 `POST /api/entity/v1/documents/{documentId}/proofs`，再使用 `proofType=BACK` 调用（护照：仅 `FRONT`）。两次上传后 `GET /api/entity/v1/documents/{documentId}/proofs` 的节选：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
[
  {
    "id": "d577e8e5-ef53-43b8-aaa3-b97ca202949a",
    "proofType": "FRONT",
    "fileName": "id_front.jpg",
    "verificationStatus": "PENDING",
    "status": "CURRENT"
  },
  {
    "id": "21e6e46d-e047-4f19-88f4-175132839e04",
    "proofType": "BACK",
    "fileName": "id_back.jpg",
    "verificationStatus": "PENDING",
    "status": "CURRENT"
  }
]
```

### 将每个人关联到公司

每人调用一次 `POST /api/entity/v1/entities/{companyId}/ubos`。Jane Doe 持股 60%，同时也是法定代表人：

```json Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "personId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "ownershipPercentage": 60,
  "controlRole": "LEGAL_REPRESENTATIVE"
}
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "37325b16-514f-40f5-afca-a2acd201f629",
  "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "personId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "ownershipPercentage": 60.0,
  "controlRole": "LEGAL_REPRESENTATIVE",
  "validFrom": "2024-01-15",
  "validTo": null,
  "createdAt": "2024-01-15T17:04:17Z"
}
```

John Doe 持股 40%，角色使用大写：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "personId": "c0b9c624-7777-4f6c-a4c5-57ef00f895c2",
  "ownershipPercentage": 40,
  "controlRole": "PARTNER"
}
```

`GET /api/entity/v1/entities/{companyId}/ubos` 会列出两者：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "items": [
    {
      "id": "37325b16-514f-40f5-afca-a2acd201f629",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
      "ownershipPercentage": 60.0,
      "controlRole": "LEGAL_REPRESENTATIVE",
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:04:17Z"
    },
    {
      "id": "848b821f-1ebb-42cf-b4c1-634b5db579e6",
      "companyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "personId": "c0b9c624-7777-4f6c-a4c5-57ef00f895c2",
      "ownershipPercentage": 40.0,
      "controlRole": "PARTNER",
      "validFrom": "2024-01-15",
      "validTo": null,
      "createdAt": "2024-01-15T17:04:18Z"
    }
  ]
}
```

保留公司的 `internalId`：它在 Localpayment 中标识该受益人。

### 通知 Localpayment 上传已完成

当公司、其文件以及每位人员都已加载并关联后，对该公司调用 `POST /api/entity/v1/entities/{companyId}/verify`（[请求验证](https://docs.localpayment.com/zh/reference/request-entity-verification.md)）。它会通知 Localpayment 文档上传已完成。响应为 `202 Accepted`（节选）：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "type": "COMPANY",
  "status": "IN_REVIEW",
  "updatedAt": "2024-01-15T17:05:00Z"
}
```

当公司处于 `IN_REVIEW` 状态时会被锁定（409 `ENTITY_IN_REVIEW`）。调用 `verify` 后，您这部分的上传即告结束：之后无需轮询该实体的状态。

## 检查清单

* 您申报的每份文件（公司注册文件、资金来源证明、身份证明文件）都有各自的存档。主要的税务识别文件无需存档。
* 每位所有者都已通过其 `ownershipPercentage` 关联到公司，法定代表人则通过 `controlRole: LEGAL_REPRESENTATIVE` 关联。
* 已在公司上设置 `attributes.businessProfile`。
* 全部内容加载完成后，您已对公司调用了 `verify`。
* 税务识别号码仅包含数字，且姓名与证件上的姓名完全一致。
* 每个文件均为 PDF、PNG、JPG 或 JPEG 格式，且大小小于 10 MB。

> [!NOTE]
>
> 核对清单完成后，Localpayment 会对公司和每位人员进行审核，并告知您是否需要进行任何更正。请参阅[跟踪审核并修复拒绝问题](https://docs.localpayment.com/zh/docs/track-review-and-fix-rejections.md)。

## 下一步

> [card] [跟踪审核并修复拒绝问题](https://docs.localpayment.com/zh/docs/track-review-and-fix-rejections.md)
>
> 根据审核结果，更正 Localpayment 要求的内容。

> [card] [管理 UBO](https://docs.localpayment.com/zh/docs/manage-ubos.md)
>
> 更新或终止所有者链接。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.