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

# 上传文件和证明

> 申报实体支持文件，并上传 Localpayment 在 KYC/KYB 期间审核的文件（证明）。

文档是已声明的数据（类型和编号）。证明文件是支持该文档的文件。本指南介绍如何向实体添加文档、逐个上传文档文件、替换或删除文件，并检查每份文档是否均已覆盖，以确保实体已准备好接受审核。

## 先决条件

* 使用[创建实体](https://docs.localpayment.com/zh/docs/create-an-entity.md)创建的实体，以及其每个文档的 `documentId`。
* 文件格式为 JPG、PNG 或 PDF，每个文件最大 10 MB。

## 每个文档的文件

一个文档可以包含任意数量的文件。每个文件都有一个类型：

| proofType | 典型用途 | 对新上传的行为 |
| - | - | - |
| FRONT | 身份证件正面，或证件的单张图片。 | 替换当前文件，当前文件将变为 SUPERSEDED。 |
| BACK | 身份证件背面。 | 替换当前文件，当前文件将变为 SUPERSEDED。 |
| SELFIE | 身份证件上上传的本人照片。 | 替换当前文件，当前文件将变为 SUPERSEDED。 |
| DOCUMENT | 扫描文件（PDF）：地址证明、公司章程、税务登记。 | 添加文件，例如合同的每一页。 |
| OTHER | 任何其他证据。 | 添加文件。 |

已 APPROVED 的文件无法替换（409 `PROOF_APPROVED`）。误上传的文件在未获批准之前，可通过[删除证明文件](https://docs.localpayment.com/zh/reference/delete-proof.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["您的后端<br/>POST /api/entity/v1/entities/{entityId}/documents<br/>PROOF_OF_ADDRESS"] --> B["Entities API<br/>201：documentId"]:::lp
    B --> C["您的后端<br/>POST /api/entity/v1/documents/{docId}/proofs?proofType=FRONT<br/>multipart 文件"]
    C --> D["Entities API<br/>201：证明材料 id，verificationStatus PENDING"]:::lp
    D --> E["您的后端<br/>POST /api/entity/v1/documents/{docId}/proofs?proofType=DOCUMENT<br/>PDF"]
    E --> F["Entities API<br/>201：证明材料 id"]:::lp
    F --> G["您的后端<br/>GET /api/entity/v1/entities/{entityId}/kyc-status"]
    G --> H["Entities API<br/>200：documentationStatus COMPLETE"]:::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
```

## 分步说明

1. 如果实体尚无该文档，请使用[添加文档](https://docs.localpayment.com/zh/reference/add-entity-document.md)声明该文档。保留其 `documentId`。
2. 使用[上传证明文件](https://docs.localpayment.com/zh/reference/upload-proof.md)上传文件：`POST /api/entity/v1/documents/{docId}/proofs?proofType=FRONT`，格式为 `multipart/form-data`，并包含名为 `file` 的部分。
3. 检查上传结果：201 响应中的 `sizeBytes` 必须大于零，且 `mimeType` 符合预期。
4. 对身份证件的背面（`proofType=BACK`）和自拍照（`proofType=SELFIE`）以及其他每个文档重复上述步骤。
5. 使用[获取 KYC 状态](https://docs.localpayment.com/zh/reference/get-kyc-status.md)检查覆盖情况。`documentationStatus` 必须为 `COMPLETE`，实体才可供审核。

### 上传文件

```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/documents/2e16d844-4fa9-4295-9a21-83ec32ef241a/proofs?proofType=FRONT" \
  -H "Authorization: Bearer $LOCALPAYMENT_ACCESS_TOKEN" \
  -F "file=@id_front.jpg;type=image/jpeg"
```

```json Response theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "id": "2c4c2f74-7179-4113-83fb-f11dbce9e07d",
  "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
  "proofType": "FRONT",
  "fileName": "id_front.jpg",
  "mimeType": "image/jpeg",
  "sizeBytes": 102400,
  "verificationStatus": "PENDING",
  "verifiedBy": null,
  "verifiedAt": null,
  "verificationReason": null,
  "uploadedBy": "12345",
  "uploadedAt": "2024-01-15T17:03:13Z",
  "status": "CURRENT",
  "supersededAt": null,
  "supersededBy": null,
  "replacedByProofId": null,
  "deletedAt": null,
  "deletedBy": null,
  "inVerification": false
}
```

在Python中，检查存储文件的大小并处理上传错误：

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

BASE_URL = "https://api.stage.localpayment.com/api/entity"
access_token = os.environ["LOCALPAYMENT_ACCESS_TOKEN"]
doc_id = "2e16d844-4fa9-4295-9a21-83ec32ef241a"

with open("id_front.jpg", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/v1/documents/{doc_id}/proofs",
        params={"proofType": "FRONT"},
        files={"file": ("id_front.jpg", f, "image/jpeg")},
        headers={"Authorization": f"Bearer {access_token}"},
        timeout=60,
    )

if response.status_code == 201:
    proof = response.json()
    if proof["sizeBytes"] == 0:
        raise RuntimeError("Empty file stored: upload again with the same proofType")
elif response.status_code in (413, 415):
    raise RuntimeError("Use a JPG, PNG, or PDF file of 10 MB or less")
elif response.status_code == 502:
    pass  # STORAGE_WRITE_FAILED: retry the upload
else:
    problem = response.json()
    # 409 PROOF_APPROVED or ENTITY_IN_REVIEW: the file cannot be replaced now
    raise RuntimeError(f"{problem.get('code')} correlationId={problem.get('correlationId')}")
```

### 检查覆盖情况

KYC状态（两个文件都准备就绪后）：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "entityId": "5aced5da-40c1-4bec-85ff-c8cd1bcb4526",
  "status": "PENDING_KYC",
  "documentationStatus": "COMPLETE",
  "statusReason": null,
  "documents": [
    {
      "documentId": "2e16d844-4fa9-4295-9a21-83ec32ef241a",
      "type": "CPF",
      "status": "PENDING",
      "proofs": [
        {
          "proofId": "2c4c2f74-7179-4113-83fb-f11dbce9e07d",
          "verificationStatus": "PENDING"
        }
      ]
    },
    {
      "documentId": "e0ea9515-442e-4bc5-bc82-b8d278255c37",
      "type": "PROOF_OF_ADDRESS",
      "status": "PENDING",
      "proofs": [
        {
          "proofId": "acb78b3f-fe18-4094-b6a9-2107f502d709",
          "verificationStatus": "PENDING"
        }
      ]
    }
  ]
}
```

## 读回文件

[获取证明文件](https://docs.localpayment.com/zh/reference/get-proof.md)会返回元数据以及有效期为 10 分钟的 `downloadUrl`。[下载证明文件](https://docs.localpayment.com/zh/reference/download-proof-file.md)会直接重定向到该链接。两者都会记录审计，并关联您访问令牌中的用户。

> [!WARNING]
>
> 已签名的 `downloadUrl` 在过期之前可用于访问该文件。请勿存储该链接或与第三方共享。需要再次访问该文件时，请重新申请。

## 替换被拒绝的文件

当合规部门拒绝某个证明文件时，文档将变为 `REJECTED`，`verificationReason` 会说明原因：

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "documentId": "0266257c-a2aa-49ac-99fe-b3882a51d750",
  "entityId": "8f5b2c9a-1caf-4b2c-b085-82bbaead6ddd",
  "type": "NATIONAL_ID",
  "id": "00.000.000-0",
  "issuingCountry": "BRA",
  "issueDate": null,
  "expirationDate": null,
  "isPrimary": false,
  "status": "REJECTED",
  "metadata": null,
  "proofs": [
    {
      "id": "931398af-9c77-4958-abf8-4c749147c508",
      "documentId": "0266257c-a2aa-49ac-99fe-b3882a51d750",
      "proofType": "BACK",
      "fileName": "id_back.jpg",
      "mimeType": "image/jpeg",
      "sizeBytes": 98304,
      "verificationStatus": "REJECTED",
      "verifiedBy": "67890",
      "verifiedAt": "2024-01-15T17:20:34Z",
      "verificationReason": "Illegible image",
      "uploadedBy": "12345",
      "uploadedAt": "2024-01-15T17:19:49Z",
      "status": "CURRENT",
      "supersededAt": null,
      "supersededBy": null,
      "replacedByProofId": null,
      "deletedAt": null,
      "deletedBy": null,
      "inVerification": false
    }
  ],
  "createdAt": "2024-01-15T17:19:46Z",
  "updatedAt": "2024-01-15T17:19:46Z"
}
```

实体恢复为 `PENDING_KYC` 后，请使用相同的 `proofType` 上传新文件。被拒绝的证明文件将被替换，文档恢复为 `PENDING`。完成更正后，请再次调用[请求验证](https://docs.localpayment.com/zh/reference/request-entity-verification.md)。

## 编辑文档

[更新文档](https://docs.localpayment.com/zh/reference/update-entity-document.md)可更改签发国家/地区、日期和元数据。任何更改都会将该文档已获批准的证明文件重置为 `PENDING`。类型和编号不可更改：请改为添加新文档并删除旧文档。主文档无法删除。

## 常见错误

| 错误 | 原因 | 解决方法 |
| - | - | - |
| 413 FILE\_TOO\_LARGE | 文件大于 10 MB。 | 压缩或分割文件。 |
| 415 UNSUPPORTED\_FILE\_TYPE | 该文件不是 JPG、PNG 或 PDF 格式。 | 转换文件格式后再重新上传。 |
| 400 VALIDATION\_ERROR | 缺少或无效的 proofType。 | 检查查询字符串。 |
| 409 PROOF\_APPROVED | 您要替换或删除的文件已经获得批准。 | 保留此文件。请以 DOCUMENT 或 OTHER 形式上传其他证据。 |
| 409 ENTITY\_IN\_REVIEW | 实体正在审核中：无法上传、替换或删除任何文件。 | 请在获取 KYC 状态中等待结果。 |
| 409 ENTITY\_NOT\_EDITABLE | 该实体为 REJECTED、BLOCKED 或 CLOSED 状态。 | 无法向该实体添加文件。 |
| 201，sizeBytes 为 0 | 该多部分请求没有文件部分。 | 请附上该文件，并使用相同的 proofType 再次上传。 |

## 下一步

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

> [card] [文件和证明类型](https://docs.localpayment.com/zh/reference/entity-document-and-proof-types.md)
>
> 可接受的文档和证明类型以及文件约束。


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