# GETGPT 普通买家 API（v1）

更新日期：2026-11-03
站点：https://getgpt.homes

普通买家无需注册、登录或申请 API Key。标准流程为：

1. 读取商品与支付方式。
2. 提交商品、邮箱和支付方式创建订单。
3. 打开返回的支付链接完成付款。
4. 使用订单号和创建时返回的 `order_token` 查询支付及交付状态。

## 响应结构

成功：

```json
{ "code": 200, "msg": "success", "data": {} }
```

失败：

```json
{ "code": 409, "msg": "商品不存在或暂不可售。", "error": "PRODUCT_UNAVAILABLE", "data": null }
```

## 接口

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/api/v1/products` | 在售商品列表 |
| GET | `/api/v1/products/{slug}` | 单个商品详情 |
| GET | `/api/v1/payment-methods` | 当前支付方式 |
| POST | `/api/v1/orders` | 创建订单 |
| GET | `/api/v1/orders/{tradeNo}` | 查询订单 |
| POST | `/api/v1/orders/{tradeNo}/payments/next` | 两笔支付的下一笔链接 |

## 创建订单

```http
POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: 6d9e34bc-74e5-4d5d-a78d-4587ba6f385b

{
  "product_slug": "chatgpt-plus-ios-us-card",
  "email": "buyer@example.com",
  "quantity": 1,
  "payment_method": "wechat"
}
```

字段：

- `product_slug`：必填，商品列表中的 slug。
- `email`：必填，购买邮箱。
- `variant_id`：可选，商品档位 ID。
- `quantity`：可选，默认 1，最多 99；商品支持情况以详情为准。
- `payment_method`：可选，`wechat` 或 `usdt`，默认 `wechat`。
- `trade_type`：USDT 支付时填写网络，例如 `usdt.bep20`。
- `Idempotency-Key`：可选；同一邮箱和同一键只创建一笔订单，参数不一致返回 `409 IDEMPOTENCY_CONFLICT`。
- 限流：创建订单 10 次/分钟/IP、20 次/小时/邮箱；查单 120 次/10 分钟/IP+订单。

成功响应：

```json
{
  "code": 201,
  "msg": "success",
  "data": {
    "order": {
      "trade_no": "GG20261103123000A1B2C3D4",
      "state": "pending",
      "status": "pending",
      "product_slug": "chatgpt-plus-ios-us-card",
      "product_name": "ChatGPT Plus 美区卡密（iOS）",
      "quantity": 1,
      "amount": "115.00",
      "currency": "CNY",
      "payment_method": "wechat",
      "payment_url": "https://checkout.example.com/...",
      "payment_expires_at": "2026-11-03T13:00:00.000Z",
      "delivery": [],
      "message": "订单已创建，请完成支付。"
    },
    "order_token": "eyJraW5kIjoiYXBpX29yZGVyIi...签名",
    "order_token_expires_at": "2026-12-03T12:30:00.000Z",
    "duplicate": false
  }
}
```

`order_token` 默认 30 天有效，只在创建订单时返回。请安全保存，不要在公开页面、聊天或日志中传播。

## 查询订单

```http
GET /api/v1/orders/GG20261103123000A1B2C3D4
Authorization: Bearer <order_token>
```

状态：

- `pending`：等待付款或仍有待支付步骤。
- `awaiting_stock`：已付款，正在补货或等待确认。
- `delivered`：已交付，`delivery` 可读取。
- `refunding`：退款处理中。
- `closed`：已关闭、过期或退款完成。

未支付和补货中不会提前返回卡密或账号内容。

## 两笔支付

当订单 `status` 为 `partially_paid` 时：

```http
POST /api/v1/orders/{tradeNo}/payments/next
Authorization: Bearer <order_token>
```

响应中的 `order.payment_url` 为下一笔支付链接。

## 错误码

| HTTP | error | 说明 |
| --- | --- | --- |
| 400 | `INVALID_REQUEST` | 请求字段格式错误 |
| 401 | `UNAUTHORIZED` | 订单令牌缺失、无效或过期 |
| 404 | `PRODUCT_NOT_FOUND` | 商品不存在或已下架 |
| 404 | `ORDER_NOT_FOUND` | 订单不存在 |
| 409 | `PRODUCT_UNAVAILABLE` | 商品暂不可售 |
| 409 | `VARIANT_UNAVAILABLE` | 档位不可用 |
| 409 | `IDEMPOTENCY_CONFLICT` | 幂等键用于了不同订单参数 |
| 422 | `TRADE_TYPE_UNSUPPORTED` | USDT 网络不受支持 |
| 429 | `RATE_LIMITED` | 请求过于频繁 |
| 503 | `PAYMENT_NOT_CONFIGURED` | 微信支付尚未配置 |
| 503 | `USDT_UNAVAILABLE` | USDT 支付暂时不可用 |

## 停止开放的接口

代理余额、API Key、HMAC 签名、商户订单号和回调通知已停止开放。旧 `/api/open/v1/*` 接口统一返回 HTTP 410。