AI 接入说明

本页用于让 AI 编程助手直接生成或检查 CheapEmail API 对接代码。优先使用下面的机器可读文件：

• AI 完整说明（纯文本）
• llms.txt
• OpenAPI 3.1
• Python 完整示例
• Go 完整示例

API 对接权限需要在 CheapEmail 用户后台申请，审核通过后才能生成 API Key / Secret。

最小任务约定

调用方下单时只提供两个业务参数：

sku_code + quantity

不要要求调用方提供 sku_id，也不要在基础下单流程中加入其他订单字段。程序按以下顺序执行：

1. 分页请求 GET /api/v1/upstream/products，获取全部商品。
2. 把每个启用的 skus[].sku_code 与商品标题、描述、价格、库存及 skus[].id 关联。
3. 向用户展示匹配的 sku_code、商品标题、规格、描述、价格和库存，先确认要购买的 SKU。
4. 用户确认后，用选定的 sku_code 精确查找 skus[].id。
5. 将查到的数字 ID 作为 sku_id，向 POST /api/v1/upstream/orders 发送 sku_id + quantity。
6. 使用响应中的 order_id 轮询 GET /api/v1/upstream/orders/:id。
7. 状态为 delivered 或 completed 后，读取并保存 fulfillment.payload。

参数边界

sku_code + quantity 是脚本或业务层的输入。Open API 的创建订单请求体仍是 sku_id + quantity，其中 sku_id 必须由程序通过商品接口自动解析。

鉴权必须这样实现

每个请求发送以下 Header：

Dujiao-Next-Api-Key: <API_KEY>
Dujiao-Next-Timestamp: <Unix 秒级时间戳>
Dujiao-Next-Signature: <小写十六进制签名>
Content-Type: application/json

签名串是四行文本：

{METHOD}\n{PATH}\n{TIMESTAMP}\n{BODY_MD5}

签名计算必须包含 API_SECRET 的转换：

secret_bytes = UTF8(API_SECRET)
message_bytes = UTF8(sign_string)
signature = HEX_LOWER(HMAC-SHA256(key=secret_bytes, message=message_bytes))

不要先对 API_SECRET 做 MD5 或 SHA256。MD5 只计算最终发送的请求体字节；无请求体时使用空字节的 MD5：

d41d8cd98f00b204e9800998ecf8427e

PATH 不包含域名和查询字符串。例如请求 /products?page=2 时，参与签名的路径仍是：

/api/v1/upstream/products

获取全部 SKU

使用 page_size=100 从第 1 页开始读取，直到累计项目数达到响应的 total。对每个启用的 SKU 输出至少以下信息：

{
  "sku_code": "SKU-1",
  "title": "商品标题",
  "description": "商品描述",
  "price": "1.00",
  "stock_status": "in_stock",
  "stock_quantity": 100,
  "sku_id": 11
}

面向用户显示和接收 sku_code；sku_id 只用于程序内部创建订单。

如果用户尚未明确给出 sku_code，AI 应先列出合适的 SKU 及对应描述，并要求用户确认。不要根据商品名称猜测 SKU，也不要在未确认时创建订单。

创建并等待订单

程序根据 sku_code 找到 sku_id 后，只发送：

{
  "sku_id": 11,
  "quantity": 2
}

POST 的 JSON 必须先序列化为最终字节，再用同一份字节计算 MD5、签名和发送请求。创建成功后保存 order_id 和 order_no，再轮询订单详情。

购买数据必须按行处理

购买到的数据位于：

fulfillment.payload

JSON 响应中的 \n 表示换行。下面的 payload 包含两条购买数据：

{
  "fulfillment": {
    "status": "delivered",
    "payload": "data-1\ndata-2"
  }
}

解析 JSON 并拆分后必须得到：

data-1
data-2

一行就是一条购买数据。 实现应同时兼容解析后的真实换行，以及上游字符串中可能出现的文本形式 \n、\r\n，并过滤空行。

保存为 UTF-8 TXT：

orders/order_<order_no>.txt

文件中每行一条购买数据，文件名使用 API 返回的 order_no，并过滤不适合文件名的字符。

可直接运行的参考实现

Python：

pip install -r requirements.txt
python test.py
python test.py order SKU-1 2

Go：

go run dujiao_client.go -action skus
go run dujiao_client.go -action order -sku-code SKU-1 -quantity 2 -wait

公开示例中的凭证是占位符。API_SECRET 只能保存在服务端或本地环境中，不能写入浏览器端代码。