> ## 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.

# 实体概览

> 注册与您合作的个人和公司，附上他们的 KYC/KYB 证明，并接受 Localpayment 的审核。

Entities 允许您注册与您合作的个人（`INDIVIDUAL`）和公司（`COMPANY`），声明其身份和相关证明文件，上传用于证明的文件，并跟进 Localpayment 执行的 KYC/KYB 审核结果。Entities 在收款和付款中共享：同一实体可用于 Localpayment 的所有产品。

本指南适用于通过 API 引导客户、受益人或业务合作伙伴的开发人员。

> [!NOTE]
>
> Entities 用于存储身份数据和证明材料，并记录审核结果。您可以通过“请求验证”发起审核，但无法自行批准：审核由 Localpayment 合规部门决定。Entities 不会对照政府登记机构验证证件号码，也不持有余额。

## 对象

| 对象 | 它是什么 | 标识符 |
| - | - | - |
| 实体 | 属于您商户账户的个人（INDIVIDUAL）或公司（COMPANY）。持有 KYC 数据、地址、自定义属性及其相关文档。 | internalId (UUID) 和您的 externalId |
| 文档 | 一份声明为数据的文件包含以下信息：类型、编号、签发国家/地区和有效期。可存储所需数量的文件。每个实体只能有一份主要文件（身份证明文件，通常是税号或身份证）。 | documentId |
| 证明 | 支持文档的文件：FRONT、BACK、SELFIE、DOCUMENT 或 OTHER。最大 10 MB。每个证明都有其独立的审核状态。 | id (proofId) |
| UBO链接 | 公司（COMPANY）与拥有或控制该公司的个人（INDIVIDUAL）之间的关系，包含 ownershipPercentage 和 controlRole。 | id (uboId) |
| 自定义字段架构 | Localpayment 为您的商户配置的额外字段。其值通过 attributes 传递，并据此进行验证。 | version |

```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 LR
    M["您的商户账户"] --> S["自定义字段 schema"]
    M --> P["实体：INDIVIDUAL"]
    M --> C["实体：COMPANY"]
    P --> D1["证件：CPF （主要）<br/>证明材料：FRONT, BACK, SELFIE"]
    P --> D2["证件：PROOF_OF_ADDRESS<br/>证明材料：DOCUMENT"]
    C --> D3["证件：CNPJ （主要）<br/>证明材料：DOCUMENT"]
    C --> D4["证件：ARTICLES_OF_INCORPORATION<br/>证明材料：DOCUMENT"]
    C -.- L1(["UBO 关联：60%，CEO"]):::lbl -.-> P
    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
```

## 工作原理

您的集成包含五个步骤。最后一步 `verify` 会告知 Localpayment 上传已完成并启动审核。执行 `verify` 后，您的上传工作即告结束：之后无需轮询实体的状态。只有当 Localpayment 要求更正时，您才需要再次对实体进行操作。

```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. 创建实体及其主要证件<br/>POST /api/entity/v1/entities"] --> B["2. 添加其他证件<br/>POST /api/entity/v1/entities/{entityId}/documents"]
    B --> C["3. 上传每份证件的文件<br/>POST /api/entity/v1/documents/{docId}/proofs"]
    C --> Q{"是否为公司？"}
    Q --- L1(["是"]):::lbl --> D["4. 关联所有者<br/>POST /api/entity/v1/entities/{companyId}/ubos"]
    Q --- L2(["否"]):::lbl --> V
    D --> V["5. 请求验证<br/>POST /api/entity/v1/entities/{entityId}/verify<br/>在所有内容上传完毕后，对公司发起"]
    V --> E[/"Localpayment 审核该实体"/]:::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
```

| 步 | endpoint | 结果 |
| - | - | - |
| 1 | [创建实体](https://docs.localpayment.com/zh/reference/create-entity.md) | 处于 PENDING\_KYC 状态的实体及其主要文档。响应中包含您上传文件所需的 documentId。 |
| 2 | [添加文档](https://docs.localpayment.com/zh/reference/add-entity-document.md) | 申报的其他文件：身份证件、地址证明、公司章程、授权委托书。 |
| 3 | [上传证明](https://docs.localpayment.com/zh/reference/upload-proof.md) | 每个文档都附带所需数量的文件。documentationStatus 从 NO\_FILES 变为 PARTIAL，最后变为 COMPLETE。 |
| 4 | [链接UBO](https://docs.localpayment.com/zh/reference/link-ubo.md) | 仅限公司。首先将每位所有者创建为 INDIVIDUAL（步骤 1 至 3），然后将其与其持股比例和控制角色关联。公司将显示 uboCount 和 uboRequirementMet。 |
| 5 | [请求验证](https://docs.localpayment.com/zh/reference/request-entity-verification.md) | 202 Accepted。实体进入 IN\_REVIEW 状态，并在 Localpayment 处理完成前被锁定。 |

如果 Localpayment 需要更正，会告知您需要修复的内容：每个被拒绝的文件都带有其 `verificationReason`。请使用相同的 `proofType` 上传替换文件，或更正数据，然后再次调用[请求验证](https://docs.localpayment.com/zh/reference/request-entity-verification.md)。请参阅[跟踪审核并修复拒绝项](https://docs.localpayment.com/zh/docs/track-review-and-fix-rejections.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
    S((开始)) --- L1(["创建实体"]):::lbl --> PK[PENDING_KYC]
    PK --- L2(["请求验证（由您发起）"]):::lbl --> IR[IN_REVIEW]
    IR --- L3(["要求更正（附原因）"]):::lbl --> PK
    IR --- L4(["已批准"]):::lbl --> AC[ACTIVE]
    IR --- L5(["已拒绝（附原因）"]):::lbl --> RJ[REJECTED]
    AC --- L6(["已阻止（附原因）"]):::lbl --> BL[BLOCKED]
    BL --- L7(["已解除阻止"]):::lbl --> AC
    PK --- L8(["关闭实体"]):::lbl --> CL[CLOSED]
    IR --> CL
    AC --> CL
    BL --> CL
    RJ --> CL
    CL --> E((结束))
    class S,E terminal
    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
```

| 状态 | 意义 | 可编辑 | 设置者 |
| - | - | - | - |
| PENDING\_KYC | 已创建，或已退回进行更正（原因见 statusReason）。文件可能仍然缺失。 | 是的 | 您，在创建时。Localpayment 合规部门，当它要求更正时。 |
| IN\_REVIEW | 正在由 Localpayment 审核。 | 否。数据、文档、文件和 UBO 链接均被冻结（409 ENTITY\_IN\_REVIEW）。 | 您，通过请求验证 |
| `ACTIVE` | 已获 Localpayment 产品批准并可使用。 | 是的 | Localpayment 合规部门 |
| `REJECTED` | 审核失败。原因已记录在状态历史记录中。无法再次提交。 | 否 | Localpayment 合规部门 |
| `BLOCKED` | 暂时被阻止。原因请查看状态记录。 | 否 | Localpayment 合规部门 |
| `CLOSED` | 已逻辑删除。保留以供审核和读取，但不可编辑。最终版本。 | 否 | 您，使用“关闭实体”功能 |

“可编辑”表示 KYC 数据、文档和文件仍可更改。编辑文档会将其已批准的文件重置为 PENDING。编辑其他实体数据不会更改已记录的审核结果。

## 文件和证明状态

Localpayment 合规部门会设置每份证明的状态。文档的状态由其证明和有效性得出。

| 对象 | 状态 | 规则 |
| - | - | - |
| 证明 | PENDING, IN\_REVIEW, APPROVED, REJECTED | 由合规部门设置。当实体回到 PENDING\_KYC 状态后，被拒绝的 FRONT、BACK 或 SELFIE 需通过再次上传相同的 proofType 来替换。 |
| 文档 | PENDING, VERIFIED, REJECTED, EXPIRED | 当所有有效证明均为 APPROVED 时为 VERIFIED。当任一有效证明为 REJECTED 时为 REJECTED。当 expirationDate 已过期时为 EXPIRED。否则为 PENDING。 |

实体上的 `documentationStatus` 汇总了文件覆盖情况：`NO_FILES`（没有任何文档有文件）、`PARTIAL`（部分文档有文件）或 `COMPLETE`（所有文档都有文件）。它并不表示批准。

## 约定

| 主题 | 约定 |
| - | - |
| 基本 URL | Stage [https://api.stage.localpayment.com/api/entity](https://api.stage.localpayment.com/api/entity)。请参阅 [API 密钥和环境](https://docs.localpayment.com/zh/docs/api-keys-and-environments.md)。 |
| 验证 | 持有者访问令牌（[获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)）。您的商户账户将根据此令牌进行解析。 |
| 操作用户 | 从访问令牌中提取并存储以供审计（uploadedBy、changedBy）。无需额外的标头。 |
| 标识符 | UUID。实体的 internalId，文档的 documentId，证明和 UBO 链接的 id。 |
| 日期 | 日期格式为 YYYY-MM-DD，时间戳格式为 ISO 8601 UTC。国家/地区格式为 ISO 3166-1 alpha-3。 |
| 并发性 | 实体响应包含 ETag 标头和版本字段。PATCH 请求需要 If-Match 字段。 |
| 追踪 | 请发送 X-Correlation-ID (UUID) 并将其提供给技术支持。该 ID 会在每个响应和错误信息中返回。 |
| 错误 | application/problem+json 包含稳定的字符串代码。请参阅[实体状态和错误代码](https://docs.localpayment.com/zh/reference/entity-statuses-and-error-codes.md)。 |
| 通知 | Entities 没有 Webhook。请求验证后无需轮询；如需跟踪审核进度，请调用 Get KYC Status。 |

## 下一步

> [card] [创建实体](https://docs.localpayment.com/zh/docs/create-an-entity.md)
>
> 使用原始文件注册个人或公司。

> [card] [上传文件和证明](https://docs.localpayment.com/zh/docs/upload-documents-and-proofs.md)
>
> 请附上支持每个文档的文件。

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

> [card] [通过实体共享 KYB 信息](https://docs.localpayment.com/zh/docs/share-kyb-information-through-entities.md)
>
> 发送虚拟账户受益人的 KYB 数据。


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