> ## 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，也没有任何风险。

VelaFi 沙盒环境是一个隔离的测试环境，使用完全模拟的数据复现生产 API 的结构和行为。您可以创建订单、查询账户并完整演练请求/响应流程，而无需转移真实资金、验证真实身份或影响任何正式商户账户。它是任何新集成的推荐起点，也是在部署到生产环境之前验证变更的安全场所。

## 沙盒环境 Base URL

将您的 HTTP 客户端指向以下 Base URL 即可访问沙盒环境：

```
https://api-test.velafi.com
```

所有生产端点均以相同的路径结构在此 Base URL 下提供。例如，在沙盒环境中获取法币交易对：

```bash theme={null}
curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols
```

此端点为公开端点，无需令牌。操作您账户的端点则需要令牌：请参阅[认证](https://docs.velafi.com/cn/api-reference/authentication.md)。

## 获取沙盒环境凭证

沙盒环境 API 密钥与生产密钥分开开通，不通过控制台生成。如需获取沙盒环境的 API key 和 API secret，请直接联系 VelaFi 团队：

* **邮箱：**[contact@velafi.com](mailto:contact@velafi.com)

> [!NOTE]
>
> 访问沙盒环境无需完成 KYC/KYB，也无需创建商户账户。VelaFi 团队会为您开通一个预配置的测试账户，其中包含可直接使用的模拟用户和商户数据。

收到凭证后，使用它们通过 `GET /v2/token/generate` 获取令牌，并在每个请求的 `X-BH-TOKEN` 请求头中携带该令牌，方式与生产环境完全相同：

```http theme={null}
X-BH-TOKEN: YOUR_SANDBOX_TOKEN
```

## 沙盒环境与生产环境对比

下表总结了两个环境之间的主要行为差异。在决定某项操作适合在哪个环境中进行时，可将其作为检查清单。

| 功能 | 沙盒环境 | 生产环境 |
| - | - | - |
| **是否需要 KYC / KYB** | 否——提供预配置的测试账户 | 是——需要完成完整的身份验证 |
| **API 密钥创建** | 无需创建——凭证由 VelaFi 提供 | 需要创建——通过控制台并使用双重验证（2FA）生成 |
| **用户和账户数据** | 虚拟模拟数据，不关联真实个人 | 与已验证商户和用户关联的真实数据 |
| **资金转账** | 不转移真实资金，所有交易均为模拟 | 通过实际支付通道转移真实资金 |
| **Webhook 回调** | 不触发——不会发送任何回调事件 | 订单状态变化时触发 |
| **Base URL** | `https://api-test.velafi.com` | `https://api.velafi.com` |

> [!WARNING]
>
> 切勿将生产 API 密钥用于沙盒环境 Base URL，也切勿将沙盒环境凭证用于生产 Base URL。请在环境配置中严格区分这两套凭证。

## 示例：获取法币交易对

以下请求演示了一次完整的沙盒环境 API 调用。它使用的是公开端点，因此可以确认您能够访问沙盒环境，但不会测试您的凭证。

```bash cURL theme={null}
curl --request GET \
  --url https://api-test.velafi.com/v2/base/fiat/symbols
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api-test.velafi.com/v2/base/fiat/symbols",
)
print(response.json())
```

```javascript Node.js theme={null}
const response = await fetch(
  "https://api-test.velafi.com/v2/base/fiat/symbols",
  {
    method: "GET",
  }
);
const data = await response.json();
console.log(data);
```

成功的响应会返回测试环境中支持的法币交易对列表：

```json theme={null}
{
  "code": 200,
  "msg": "SUCCESS",
  "data": [
    {
      "symbol": "ARS_USDT",
      "base_currency": "ARS",
      "quote_currency": "USDT",
      "status": "active"
    },
    {
      "symbol": "MXN_USDT",
      "base_currency": "MXN",
      "quote_currency": "USDT",
      "status": "active"
    }
  ]
}
```

> [!TIP]
>
> 在切换到生产环境之前，请在沙盒环境中完整演练入金、出金和全球支付订单流程。由于沙盒环境不会触发 Webhook 回调，测试期间请手动轮询订单状态端点以验证状态流转。

## 推荐的测试流程

上线前，请在沙盒环境中按以下顺序进行端到端集成验证：

**1. 确认凭证**

使用沙盒环境的 API key 和 secret 通过 `GET https://api-test.velafi.com/v2/token/generate` 获取令牌，然后使用该令牌调用 `GET /v2/user/account`。成功的响应表明您的 key、secret、IP 白名单和 API 访问权限均已配置妥当。

**2. 测试入金订单创建**

使用模拟的商户和账户数据创建法币兑加密货币订单。验证系统是否返回 `order_id`，以及能否通过 ID 获取该订单。

**3. 测试出金订单创建**

创建加密货币兑法币订单，并确认响应包含预期的结算详情和收款人信息。

**4. 测试全球支付订单创建**

创建一个法币兑法币订单，其付款方商户和收款方商户配置为不同的法币币种。确认订单状态按预期推进。

**5. 切换到生产环境**

将沙盒环境 Base URL 替换为 `https://api.velafi.com`，换用您的生产 API key 和 secret，并从生产主机获取令牌。对生产环境的 `/v2/user/account` 端点重新运行冒烟测试，以确认切换成功。

***

## 沙盒环境测试工具

沙盒环境提供两个模拟入账充值的端点，您无需转移真实资金即可为测试商户注资。它们仅存在于 `https://api-test.velafi.com`；在 `https://api.velafi.com` 上会返回 `404`。两者均支持 `GET` 或 `POST`，参数以查询参数形式发送。

### 模拟法币充值

`https://api-test.velafi.com/v2/platform/test/deposit`

模拟一笔向商户已激活法币账户的入账银行充值。

**merchantId** `number` *required*

要入账的商户 ID。

**fiat** `string` *required*

法币代码，例如 `MXN`。

**fiatAmount** `number` *required*

充值金额。必须大于 `0`。

**paymentId** `number` *required*

该商户在此币种下已激活法币账户的支付方式 ID。

**depositAlias** `string`

同一 `merchantId`、`fiat` 和 `paymentId` 下某个虚拟账户的别名。设置后，充值将进入该虚拟账户。

常见失败消息：

* `The merchant has not activated the corresponding fiat currency account.` — 该商户没有此 `fiat` 和 `paymentId` 对应的已激活账户。
* `The depositAlias invalid.` — 没有与 `depositAlias` 匹配的虚拟账户。
* `This method of currency recharge is not currently supported.` — 此支付方式没有充值模拟器。

```bash cURL theme={null}
curl -G https://api-test.velafi.com/v2/platform/test/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "fiat=MXN" \
  --data-urlencode "fiatAmount=1000" \
  --data-urlencode "paymentId=105"
```

### 模拟加密货币充值

`https://api-test.velafi.com/v2/platform/test/crypto/deposit`

向商户钱包添加测试加密货币资金。

**merchantId** `number` *required*

已获批准的商户 ID。

**crypto** `string` *required*

`USDT`、`USDC`、`BTC`、`MMXN`、`COPM` 或 `MXNB` 之一。其他值将返回 `{"code":500, "msg":"crypto is invalid"}`。

**amount** `number` *required*

要添加的数量。必须大于 `0`。

成功时，响应的 `code` 为 `200`。

```bash cURL theme={null}
curl -G https://api-test.velafi.com/v2/platform/test/crypto/deposit \
  --data-urlencode "merchantId=151209" \
  --data-urlencode "crypto=USDT" \
  --data-urlencode "amount=500"
```

> [!NOTE]
>
> 模拟器仅支持成功的充值，无法生成失败或被退回的充值。

***

## 后续步骤

> [card] [快速入门](https://docs.velafi.com/cn/docs/quickstart.md)
>
> 设置您的生产账户并生成正式 API 密钥。

> [card] [API 参考](https://docs.velafi.com/cn/api-reference/overview.md)
>
> 浏览所有可用端点、参数和响应结构。


## Related topics

- [认证](https://docs.velafi.com/cn/api-reference/authentication.md)
- [基础 URL](https://docs.velafi.com/cn/api-reference/basic-configuration/api-endpoint.md)
- [简介](https://docs.velafi.com/cn/docs/introduction.md)
- [支付方式](https://docs.velafi.com/cn/docs/payment-methods.md)
- [创建 API 密钥](https://docs.velafi.com/cn/docs/guides/creating-api-key.md)


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