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

# 沙盒环境

> 在没有真实资金的情况下安全地测试您的集成

## 概述

KillB 沙盒环境允许您在不处理真实交易或转移实际资金的情况下测试您的集成。

<Info>
  所有沙盒交易都使用假钱。不会转移或收取真实资金。
</Info>

## 环境

<Tabs>
  <Tab title="沙盒（测试）">
    **Base URL：** `https://sandbox.killb.app`

    **功能：**

    * 使用假钱测试
    * 模拟支付流程
    * 不需要真实的 KYC 验证
    * 即时交易处理
    * 完整的 API 功能

    **用于：**

    * 开发和测试
    * 集成验证
    * 演示应用程序
    * CI/CD 测试
  </Tab>

  <Tab title="生产（上线）">
    **Base URL：** `https://killb.app`

    **功能：**

    * 真实资金交易
    * 完整的 KYC/KYB 验证
    * 实际支付处理
    * 监管合规
    * 生产支持

    **用于：**

    * 实时应用程序
    * 真实用户交易
    * 生产部署
  </Tab>
</Tabs>

## 开始使用沙盒

### 步骤 1：获取沙盒凭证

1. 在 [otc.killb.com](https://otc.killb.com) 注册
2. 导航到 **设置** → **API 密钥**
3. 创建 **沙盒 API 密钥**
4. 记录您的沙盒电子邮件和密码

### 步骤 2：设置环境变量

```bash .env theme={null}
KILLB_ENV=sandbox
KILLB_BASE_URL=https://sandbox.killb.app
KILLB_EMAIL=your-sandbox-email@example.com
KILLB_PASSWORD=your-sandbox-password
KILLB_API_KEY=your-sandbox-api-key
```

### 步骤 3：身份验证

```bash theme={null}
curl --request POST \
  --url https://sandbox.killb.app/api/v2/auth/login \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "your-sandbox-email@example.com",
    "password": "your-sandbox-password"
  }'
```

## 测试功能

### Faker 端点

沙盒提供特殊端点来模拟支付事件：

<AccordionGroup>
  <Accordion title="模拟现金入账" icon="money-bill-wave" defaultOpen>
    模拟用户完成法币支付（PSE、SPEI 等）

    ```bash theme={null}
    POST /api/v2/faker/cash-in
    ```

    **请求：**

    ```json theme={null}
    {
      "rampId": "ramp-id-from-creation"
    }
    ```

    **作用：**

    * 将现金入账标记为已完成
    * 触发转换过程
    * 将 ramp 移动到下一个状态

    **示例：**

    ```bash theme={null}
    curl --request POST \
      --url https://sandbox.killb.app/api/v2/faker/cash-in \
      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{"rampId": "your-ramp-id"}'
    ```
  </Accordion>

  <Accordion title="模拟现金出账" icon="money-bill-transfer">
    模拟加密货币到法币转换的完成

    ```bash theme={null}
    POST /api/v2/faker/cash-out
    ```

    **请求：**

    ```json theme={null}
    {
      "rampId": "ramp-id-from-creation"
    }
    ```

    **作用：**

    * 完成现金出账过程
    * 将 ramp 标记为 COMPLETED
    * 触发 webhooks

    **示例：**

    ```bash theme={null}
    curl --request POST \
      --url https://sandbox.killb.app/api/v2/faker/cash-out \
      --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
      --header 'Content-Type: application/json' \
      --data '{"rampId": "your-ramp-id"}'
    ```
  </Accordion>
</AccordionGroup>

## 测试工作流

### 完整的 On-Ramp 测试

<Steps>
  <Step title="创建测试用户">
    使用任何看起来有效的数据 - 沙盒中不需要真实验证

    ```json theme={null}
    {
      "firstName": "Test",
      "lastName": "User",
      "email": "test@example.com",
      "document": { "type": "PASSPORT", "number": "TEST123" }
    }
    ```
  </Step>

  <Step title="创建钱包账户">
    使用任何有效的钱包地址格式

    ```json theme={null}
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "network": "POLYGON",
      "currency": "USDC"
    }
    ```
  </Step>

  <Step title="创建报价">
    使用沙盒费率获取测试报价
  </Step>

  <Step title="创建 Ramp">
    执行 ramp 交易
  </Step>

  <Step title="模拟支付">
    使用 `/api/v2/faker/cash-in` 模拟用户支付
  </Step>

  <Step title="验证完成">
    检查 ramp 状态是否移动到 COMPLETED
  </Step>
</Steps>

### 完整的 Off-Ramp 测试

<Steps>
  <Step title="创建测试用户">
    与 on-ramp 流程相同
  </Step>

  <Step title="创建银行账户">
    使用测试银行详情

    ```json theme={null}
    {
      "type": "PSE",
      "accountNumber": "1234567890",
      "bankCode": "0001"
    }
    ```
  </Step>

  <Step title="创建报价">
    从 USDC 到 COP/MXN 的报价
  </Step>

  <Step title="创建 Ramp">
    使用加密货币源执行 ramp
  </Step>

  <Step title="模拟完成">
    使用 `/api/v2/faker/cash-out` 完成流程
  </Step>

  <Step title="验证状态">
    确认状态为 COMPLETED 并触发 webhooks
  </Step>
</Steps>

## 测试数据

### 测试银行账户（哥伦比亚）

| 银行名称            | 银行代码 | 账户类型              |
| --------------- | ---- | ----------------- |
| Bancolombia     | 0001 | savings, checking |
| Banco de Bogotá | 0002 | savings, checking |
| Davivienda      | 0003 | savings, checking |

### 测试银行账户（墨西哥）

| 银行名称      | 银行代码 | CLABE 格式             |
| --------- | ---- | -------------------- |
| BBVA      | 012  | 012XXXXXXXXXXXXXXXXX |
| Santander | 014  | 014XXXXXXXXXXXXXXXXX |
| Banorte   | 072  | 072XXXXXXXXXXXXXXXXX |

### 测试钱包地址

```
Polygon (MATIC):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Solana:
5FHwkrdxntdK24hgQU8qgBjn35Y1zwhz1GZwCkP4UJnC

Ethereum:
0x71C7656EC7ab88b098defB751B7401B5f6d8976F

Tron:
TXYZopYRdj2D9XRtbG4uXyrFPRw6sM3pjN
```

<Note>
  这些是用于测试的示例地址。在沙盒中，任何格式有效的地址都可以工作。
</Note>

## 沙盒限制

<Warning>
  请注意沙盒和生产环境之间的这些差异：
</Warning>

| 功能       | 沙盒    | 生产      |
| -------- | ----- | ------- |
| 真实资金     | ❌ 否   | ✅ 是     |
| KYC 验证   | ❌ 模拟  | ✅ 真实验证  |
| 支付处理     | ⚡ 即时  | ⏱️ 真实时间 |
| Webhooks | ✅ 是   | ✅ 是     |
| API 速率限制 | 🔓 宽松 | 🔒 强制执行 |

## 在沙盒中调试

### 启用详细日志

```javascript theme={null}
const DEBUG = process.env.KILLB_ENV === 'sandbox';

async function makeRequest(endpoint, options) {
  if (DEBUG) {
    console.log('Request:', endpoint, options);
  }
  
  const response = await fetch(endpoint, options);
  const data = await response.json();
  
  if (DEBUG) {
    console.log('Response:', data);
  }
  
  return data;
}
```

### 监控 Ramp 状态

```javascript theme={null}
async function waitForRampCompletion(rampId, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const ramp = await fetch(`/api/v2/ramps/${rampId}`, {
      headers: { 'Authorization': `Bearer ${token}` }
    }).then(r => r.json());
    
    console.log(`Attempt ${i + 1}: Status = ${ramp.status}`);
    
    if (ramp.status === 'COMPLETED') {
      return ramp;
    }
    
    if (['FAILED', 'CANCELED', 'REJECTED'].includes(ramp.status)) {
      throw new Error(`Ramp ${ramp.status}: ${ramp.details}`);
    }
    
    await new Promise(resolve => setTimeout(resolve, 2000));
  }
  
  throw new Error('Ramp completion timeout');
}
```

## 切换到生产环境

当您准备上线时：

<Steps>
  <Step title="更新 Base URL">
    从 `teste-94u93qnn.uc.gateway.dev` 更改为 `killb.app`

    ```javascript theme={null}
    const baseUrl = 'https://killb.app';
    ```
  </Step>

  <Step title="使用生产凭证">
    用生产 API 密钥替换沙盒凭证
  </Step>

  <Step title="移除 Faker 调用">
    移除所有对 `/api/v2/faker/*` 端点的调用
  </Step>

  <Step title="实现真实 KYC">
    处理实际的 KYC 验证和文档上传
  </Step>

  <Step title="添加错误处理">
    实现生产级错误处理和日志记录
  </Step>

  <Step title="启用监控">
    为您的集成设置监控和警报
  </Step>
</Steps>

## 测试清单

在上线生产之前，测试这些场景：

<AccordionGroup>
  <Accordion title="正常路径" icon="check">
    * [ ] 用户创建和 KYC
    * [ ] 账户创建（银行和钱包）
    * [ ] 报价生成
    * [ ] On-ramp 完成
    * [ ] Off-ramp 完成
    * [ ] Webhook 接收
    * [ ] 收据生成
  </Accordion>

  <Accordion title="错误场景" icon="xmark">
    * [ ] 过期报价处理
    * [ ] 无效账户详情
    * [ ] 余额不足
    * [ ] 支付失败模拟
    * [ ] 网络错误
    * [ ] 令牌过期
    * [ ] 无效 webhook 签名
  </Accordion>

  <Accordion title="边缘情况" icon="flask">
    * [ ] 非常小的金额（\<\$1）
    * [ ] 非常大的金额（>\$10,000）
    * [ ] 并发交易
    * [ ] 速率限制
    * [ ] 重复预防（externalId）
    * [ ] 每个用户的多个账户
  </Accordion>
</AccordionGroup>

## 需要帮助？

<CardGroup cols={1}>
  <Card title="电子邮件支持" icon="envelope" href="mailto:tech@killb.com">
    联系我们的团队
  </Card>
</CardGroup>