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

# 上传订单文件

> 为指定订单附加发票或证明文件。当订单处于 RFI 状态或在放款前等待提交文件时必须上传。

某些订单需要证明文件 —— 例如，合规部门要求补充信息时（`status: 11`），或订单正在等待证明文件时（`status: 31`）。使用此接口每次调用最多可上传五个文件。支持的格式为 JPG、JPEG、PNG 和 PDF，每个文件最大 5 MB。向处于 `status: 11` 的订单上传文件后，订单将变为 `status: 12`。对于 `fiat_to_crypto` 和 `crypto_to_fiat` 订单，向处于 `status: 31` 的订单上传文件后，订单将变为 `status: 40`（待付款）。`fiat_to_fiat` 订单仅在缺少必需文件时显示 `status: 31`；上传后会显示其实际状态（`41` 或 `51`）。在其他可接受状态下上传不会改变状态；关于哪些上传会被附加到订单，请参见下方说明。

## 接口地址

```text theme={null}
POST https://api.velafi.com/v2/order/invoice
```

> [!NOTE]
>
> 在沙盒环境中测试时，请使用 `https://api-test.velafi.com/v2/order/invoice`。

## 请求头

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

## 请求参数

**orderId** `integer` *required*

要附加文件的订单数字 ID。

**orderType** `string` *required*

订单类型。必须为 `fiat_to_crypto`、`crypto_to_fiat` 或 `fiat_to_fiat` 之一。

**files** `file` *required*

要上传的一个或多个文件。每次请求最多 5 个文件。每个文件最大 5 MB。支持的格式：`jpg`、`jpeg`、`png`、`pdf`。

## 响应字段

**code** `integer`

响应状态码。`200` 表示成功。

**msg** `string`

可读的响应信息。

**data** `boolean`

文件上传成功时为 `true`。

## 示例

```bash theme={null}
curl -X POST "https://api.velafi.com/v2/order/invoice" \
  -H "X-BH-TOKEN: YOUR_TOKEN" \
  -F "orderId=493829236956962816" \
  -F "orderType=fiat_to_crypto" \
  -F "files=@/path/to/invoice.pdf" \
  -F "files=@/path/to/receipt.jpg"
```

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": true
}
```

> [!WARNING]
>
> 仅在以下状态下接受上传：`fiat_to_crypto` 和 `crypto_to_fiat` 订单为 `11`、`12`、`31`、`32`、`40`、`50` 和 `60`；`fiat_to_fiat` 订单为 `10`、`11`、`12`、`31`、`41`、`51` 和 `60`。向处于其他任何状态的订单上传文件会返回错误。上传前请使用 `GET /v2/order/detail` 检查当前状态。

> [!NOTE]
>
> 文件大小和数量限制：每次上传请求最多 **5 个文件**，单个文件最大 **5 MB**。支持的格式为 `jpg`、`jpeg`、`png` 和 `pdf`。

> [!NOTE]
>
> 对于不处于 RFI（`status: 11` 或 `12`）阶段的 `fiat_to_crypto` 和 `crypto_to_fiat` 订单，只有第一次上传的文件会附加到订单。之后的上传仍会返回 `data: true`，但不会被附加。在 RFI 期间，每次上传都会替换之前上传的 RFI 文件。


## Related topics

- [上传文件](https://docs.velafi.com/cn/api-reference/basic-configuration/upload-file.md)
- [订单事件](https://docs.velafi.com/cn/api-reference/webhooks/fiat-crypto-order-message-push.md)
- [订单状态](https://docs.velafi.com/cn/docs/order-statuses.md)
- [确认订单](https://docs.velafi.com/cn/api-reference/order/confirm-a-specific-order.md)
- [出金（加密货币兑法币）](https://docs.velafi.com/cn/docs/guides/off-ramp.md)


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