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

# 上传文件

> 向 VelaFi 上传 KYC/KYB 身份证明文件或发票文件。每次请求最多支持 5 个文件，格式为 JPG、PNG、JPEG 或 PDF。

使用 **POST** `/v2/base/file/upload` 端点向 VelaFi 上传文件。该端点支持上传 KYC/KYB 身份验证文件以及商户账户的发票文件。请求必须以 `multipart/form-data` 格式发送。单次请求最多可上传五个文件；每个文件大小必须在 10 KB 到 3 MB 之间，且为受支持的格式之一。响应会为每个已上传的文件返回一个临时签名 URL，以便您在后续 API 调用中引用该文件之前确认上传成功。

> [!WARNING]
>
> 此端点需要授权。每个请求都必须包含 `X-BH-TOKEN` 请求头。没有有效令牌的请求将被拒绝。

## 请求

```text theme={null}
POST /v2/base/file/upload
```

### 请求头

| 请求头 | 值 | 必填 |
| - | - | - |
| `X-BH-TOKEN` | 通过 `GET /v2/token/generate` 获取的令牌 | ✓ |
| `Content-Type` | `multipart/form-data` | ✓ |

### 请求体参数

**businessType** `string` *required*

所上传文件的业务类型。目前固定为 `FIAT_ACCOUNT`。

**files** `file` *required*

要上传的一个或多个文件。每次请求最多 **5 个文件**。每个文件大小必须在 **10 KB 到 3 MB** 之间。支持的格式：`jpg`、`jpeg`、`png`、`pdf`。

## 响应字段

**code** `number`

HTTP 风格的状态码。`200` 表示成功。

**msg** `string`

可读的状态消息，例如 `"SUCCESS"`。

**data** `array`

已上传文件对象的数组，每个文件对应一个条目。

**data\[]**

**fileName** `string`

上传时提供的原始文件名（例如 `"id-front.jpg"`）。

**fileType** `string`

已上传文件的扩展名（例如 `"jpg"`、`"pdf"`）。

**fileUrl** `string`

文件的相对存储路径（例如 `"100001/00000000-0000-0000-0000-000000000001.jpg"`）。在后续 API 调用中引用该文件时使用此值，例如 `Pix - Woovi` 渠道激活中的文件字段（`govIdFrontUrl`、`govIdBackUrl`、`certificateOfIncorporationDocumentUrl`、`taxIdentificationDocumentUrl`）。

**tempFileUrl** `string`

临时预签名 URL，可用于确认文件已正确上传。该 URL 在上传 30 分钟后过期，不应永久存储。

## 示例

```bash cURL — single file theme={null}
curl --request POST \
  --url 'https://api.velafi.com/v2/base/file/upload' \
  --header 'X-BH-TOKEN: YOUR_TOKEN' \
  --header 'Content-Type: multipart/form-data' \
  --form 'businessType=FIAT_ACCOUNT' \
  --form 'files=@/path/to/id-front.jpg'
```

```bash cURL — multiple files theme={null}
curl --request POST \
  --url 'https://api.velafi.com/v2/base/file/upload' \
  --header 'X-BH-TOKEN: YOUR_TOKEN' \
  --header 'Content-Type: multipart/form-data' \
  --form 'businessType=FIAT_ACCOUNT' \
  --form 'files=@/path/to/id-front.jpg' \
  --form 'files=@/path/to/id-back.jpg'
```

### 响应

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "fileName": "id-front.jpg",
      "fileType": "jpg",
      "fileUrl": "100001/00000000-0000-0000-0000-000000000001.jpg",
      "tempFileUrl": "https://example-bucket.s3.amazonaws.com/00000000-0000-0000-0000-000000000001.jpg?X-Amz-Signature=..."
    }
  ]
}
```

> [!NOTE]
>
> 请保存响应中的 `fileUrl` 字段——这是您在 KYC/KYB 提交请求中引用的永久相对路径。`tempFileUrl` 是仅用于验证的短期签名 URL，会过期失效。


## Related topics

- [上传订单文件](https://docs.velafi.com/cn/api-reference/order/upload-invoice-documents-for-a-specific-order.md)
- [激活企业商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-business.md)
- [订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)
- [激活个人商户账户](https://docs.velafi.com/cn/api-reference/merchant/activate-merchant-account-for-individual.md)
- [订单事件](https://docs.velafi.com/cn/api-reference/webhooks/fiat-crypto-order-message-push.md)


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