> ## 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 数据和主要文件，这是 KYC/KYB 入职的第一步。

本指南将引导您使用 [创建实体](https://docs.localpayment.com/zh/reference/create-entity.md) 功能注册个人和公司。创建实体时无需上传文件。您需要在下一步 [上传文件和证明](https://docs.localpayment.com/zh/docs/upload-documents-and-proofs.md) 中上传文件。

## 先决条件

* Stage 访问令牌。请参阅 [获取访问令牌](https://docs.localpayment.com/zh/reference/get-token.md)。
* 实体类型：`INDIVIDUAL` 适用于自然人，`COMPANY` 适用于法人实体。
* 身份证明文件。对于个人：税务识别号（`CPF`、`CUIT`、`RFC`、`CURP`）或身份证明文件（`DNI`、`PASSPORT`、`CC`）。对于公司：税务识别号（`CNPJ`、`CUIT`、`RFC`、`RUC`、`NIT`）。它将成为主要文件。
* 稳定的 `externalId`：您自己的参考编号，每个商家独一无二。
* 如果 Localpayment 为您的商户配置了自定义字段，请参阅 [自定义字段](https://docs.localpayment.com/zh/docs/custom-fields.md) 部分。

## 需要申报哪些文件

一份文件对应一个 id，其中可包含您需要的任意数量的文件，例如身份证件的正面、背面和自拍照。创建实体时，请在 `document` 中发送身份证明文件：它将成为主要文件。其他所有文件请使用 [添加文件](https://docs.localpayment.com/zh/reference/add-entity-document.md) 进行申报。`type` + `id` 的组合在您的商户中必须是唯一的。

| 类型 | 主要文件 | 其他文件 |
| - | - | - |
| `INDIVIDUAL` | 税务识别号或身份证明文件（CPF、DNI、PASSPORT）。证明材料：FRONT、BACK、SELFIE。 | PROOF\_OF\_ADDRESS，以及任何其他证明（PROOF\_OF\_FUNDS、PAYSLIP、OTHER）。 |
| `COMPANY` | 税务识别号（CNPJ、CUIT、RFC、RUC、NIT）。证明材料：DOCUMENT。 | ARTICLES\_OF\_INCORPORATION、PROOF\_OF\_ADDRESS。所有者注册为 INDIVIDUAL 实体，并通过 [管理最终受益所有人](https://docs.localpayment.com/zh/docs/manage-ubos.md) 进行关联。 |

完整的值列表请参阅 [文档和证明类型](https://docs.localpayment.com/zh/reference/entity-document-and-proof-types.md)。

## 最低数据

| 类型 | API 要求 | 强烈推荐 |
| - | - | - |
| `INDIVIDUAL` | externalId, type, name, lastname, document | birthdate, nationality, residenceCountry, email, phone, address |
| `COMPANY` | externalId, type, name, document | incorporationCountry, incorporationDate, legalRepresentativeName, website, email, phone, address |

缺少必需的 KYC 数据将返回 422 `INCOMPLETE_KYC_DATA`。

## 创建个人

```bash Request theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl -X POST https://api.stage.localpayment.com/api/entity/v1/entities \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Correlation-ID: 0e8f6a2c-5b3d-4c1e-9a7f-6d5e4c3b2a10" \
  -d '{
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastname": "Doe",
    "birthdate": "1990-01-15",
    "nationality": "BRA",
    "birthCountry": "BRA",
    "residenceCountry": "BRA",
    "isPep": false,
    "email": "jane.doe@example.com",
    "phone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "999990001"
    },
    "address": {
      "street": "Rua Exemplo",
      "number": "123",
      "city": "São Paulo",
      "state": "SP",
      "zipCode": "01310-100",
      "country": "BRA"
    },
    "document": {
      "type": "CPF",
      "id": "00000000000",
      "issuingCountry": "BRA"
    }
  }'
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "internalId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "type": "INDIVIDUAL",
  "status": "PENDING_KYC",
  "name": "Jane",
  "lastname": "Doe",
  "birthdate": "1990-01-15",
  "gender": null,
  "nationality": "BRA",
  "birthCountry": "BRA",
  "residenceCountry": "BRA",
  "occupation": null,
  "isPep": false,
  "incorporationDate": null,
  "incorporationCountry": null,
  "website": null,
  "legalRepresentativeName": null,
  "email": "jane.doe@example.com",
  "phone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999990001"
  },
  "address": {
    "street": "Rua Exemplo",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "number": "123",
    "comment": null,
    "country": "BRA",
    "line2": null,
    "line3": null
  },
  "attributes": null,
  "documentationStatus": "NO_FILES",
  "document": {
    "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
    "entityId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
    "type": "CPF",
    "id": "00000000000",
    "issuingCountry": "BRA",
    "issueDate": null,
    "expirationDate": null,
    "isPrimary": true,
    "status": "PENDING",
    "metadata": null,
    "proofs": [],
    "createdAt": "2024-01-15T17:03:10Z",
    "updatedAt": "2024-01-15T17:03:10Z"
  },
  "documents": [],
  "version": 0,
  "createdAt": "2024-01-15T17:03:10Z",
  "updatedAt": "2024-01-15T17:03:10Z",
  "customFieldSchemaVersion": null
}
```

响应状态码为 201 Created，并带有以下标头：`ETag: "0"`。

请保留 `internalId`（实体）和 `document.documentId`（主要文件）。后续步骤需要用到这两个值。

## 创建公司

以税务识别号为主要文件、包含附加行的地址以及自定义字段的公司：

```json 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.",
  "incorporationCountry": "BRA",
  "incorporationDate": "2020-01-15",
  "website": "https://www.example.com",
  "email": "test@example.com",
  "phone": {
    "countryCode": "55",
    "areaCode": "11",
    "number": "999990000"
  },
  "legalRepresentativeName": "Jane Doe",
  "isPep": false,
  "address": {
    "street": "Rua Exemplo",
    "number": "100",
    "city": "São Paulo",
    "state": "SP",
    "zipCode": "01310-100",
    "country": "BRA",
    "line2": "Sala 100",
    "line3": "Torre A"
  },
  "document": {
    "type": "CNPJ",
    "id": "00000000000100",
    "issuingCountry": "BRA"
  },
  "attributes": {
    "reasonForAccountOpening": "receive_payments_for_goods_and_services",
    "sourceOfFundsAndIncome": "sales_of_goods_and_services",
    "numberOfEmployees": "11-50",
    "estimatedAnnualRevenueUsd": "1m_to_10m",
    "estimatedMonthlyVolumeUsd": "50000",
    "businessActivityDescription": "Online retail of home goods. Receives payments from end customers in Brazil via PIX.",
    "countryTaxResidence": "BRA",
    "socialMedia": "https://www.linkedin.com/company/example",
    "emailPixKey": "test@example.com"
  }
}
```

## 处理集成中的错误

```python theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
import os
import uuid
import requests

BASE_URL = "https://api.stage.localpayment.com/api/entity"
access_token = os.environ["LOCALPAYMENT_ACCESS_TOKEN"]

payload = {
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "type": "INDIVIDUAL",
    "name": "Jane",
    "lastname": "Doe",
    "document": {"type": "CPF", "id": "00000000000", "issuingCountry": "BRA"},
}

response = requests.post(
    f"{BASE_URL}/v1/entities",
    json=payload,
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Correlation-ID": str(uuid.uuid4()),
    },
    timeout=30,
)

if response.status_code == 201:
    entity = response.json()
    entity_id = entity["internalId"]
    primary_document_id = entity["document"]["documentId"]
else:
    problem = response.json()  # application/problem+json
    code = problem.get("code")
    if code == "DUPLICATE_ENTITY":
        # Already registered: look it up with GET /v1/entities?externalId=...
        pass
    elif code in ("VALIDATION_ERROR", "CUSTOM_FIELDS_INVALID"):
        for detail in problem.get("details", []):
            print(f"{detail['field']}: {detail['issue']}")
    else:
        # Quote the correlation id when you contact support
        print(f"{response.status_code} {code} correlationId={problem.get('correlationId')}")
```

## 常见错误

| 错误 | 原因 | 解决方法 |
| - | - | - |
| 400 VALIDATION\_ERROR | 未知属性、两位字母的国家代码、文档列表而不是文档，或者没有文档。 | 检查 details 中每个条目所指的字段。将多余数据移至 attributes。 |
| 400 CUSTOM\_FIELDS\_INVALID | attributes 不符合自定义字段 schema。 | 阅读 schema 并修复 details 中所指的字段。 |
| 409 DUPLICATE\_ENTITY | externalId，或者文档类型 + id，已经在您的商户中使用。 | 重用现有实体。使用 [列出实体](https://docs.localpayment.com/zh/reference/list-entities.md) 查找它。 |
| 422 INCOMPLETE\_KYC\_DATA | 缺少最低限度的 KYC 数据。 | 添加 name 和 lastname（个人）或 name（公司）。 |

自定义字段验证错误示例：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "type": "about:blank",
  "title": "Validation error",
  "status": 400,
  "detail": "Validation error",
  "instance": "/api/entity/v1/entities",
  "code": "CUSTOM_FIELDS_INVALID",
  "correlationId": "fff39bf8-1cb2-40c7-ac99-37478d819943",
  "details": [
    {
      "field": "numberOfEmployees",
      "issue": "NOT_IN_OPTIONS"
    },
    {
      "field": "legacyNote",
      "issue": "UNKNOWN_FIELD"
    }
  ]
}
```

> [!WARNING]
>
> 税务识别号（`CPF`、`CNPJ`、`CUIT`、`RFC`）是一份文件，而不是实体的字段。请在 `document` 中发送。国家代码必须符合 ISO 3166-1 alpha-3 标准（使用 `BRA`，而不是 `BR`）。

## 下一步

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

> [card] [创建实体引用](https://docs.localpayment.com/zh/reference/create-entity.md)
>
> 所有请求字段、响应字段和错误代码。


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