DEVELOPER CENTER

将数字服务接入你的网站。

大唐供货 API · v1 · JSON / HTTPS

申请接入

从一次安全的下单开始

此接口用于数字商品供货：读取商品、获取报价、余额采购及查询交付。它不提供模型推理接口；ChatGPT 会员、Codex 产品内积分与模型 API 余额是不同商品。

注册账户，提交代理与 API 申请。
管理员审核后，在代理中心创建 API 密钥并充值商城余额。
读取商品 → 获取报价 → 用户确认 → 创建订单 → 查询交付。

金额统一使用人民币“分”的整数：500 = ¥5.00。密钥仅保存在你的服务器，不要嵌入前端。

接口与认证

下载 OpenAPI 描述 ↗

请求头：Authorization: Bearer dtk_live_…。每个密钥每分钟最多60次调用，有效期90天，可随时撤销。

方法	路径	用途
GET	`/api/v1/products`	已上架且可供货的商品
GET	`/api/v1/balance`	商城可用余额
POST	`/api/v1/quotes`	获取120秒有效报价
POST	`/api/v1/orders`	余额采购，必须提交幂等键
GET	`/api/v1/orders`	分页读取自己的订单
GET	`/api/v1/orders/{id}`	查询自己的订单与交付内容

请求示例

把示例域名替换为你当前访问的商城域名。

1. 获取报价

curl https://你的商城域名/api/v1/quotes \
  -H "Authorization: Bearer $DATANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"商品ID","quantity":1}'

响应中的 id 为 quote_id；total 是待扣除的人民币分数，expires_at 为毫秒时间戳。

2. 使用固定订单号采购

curl https://你的商城域名/api/v1/orders \
  -H "Authorization: Bearer $DATANG_API_KEY" \
  -H "Idempotency-Key: YOUR-ORDER-20261023-001" \
  -H "Content-Type: application/json" \
  -d '{"product_id":"商品ID","quantity":1,"quote_id":"报价ID"}'

你方同一订单每次重试必须使用相同的 Idempotency-Key。相同键会返回原订单，参数不一致返回409。报价只确认当前价格与库存，实际下单时再次校验。

3. 查询交付

curl https://你的商城域名/api/v1/orders/订单ID \
  -H "Authorization: Bearer $DATANG_API_KEY"

也可以使用商城订单号或你传入的幂等键查询。建议15至30秒查询一次，状态为 delivered 时读取 delivery 并停止查询。

订单状态与异常处理

状态	含义与处理
`queued / purchasing`	已扣余额，采购处理中
`pending / uncertain`	等待交付或采购结果尚未确认；持续查询原订单
`delivered`	交付完成，delivery 字段包含交付内容
`failed / refunded`	款项已退回商城余额

网络超时或 uncertain 状态时，继续查询原订单，禁止更换订单号重复采购。API 返回401请检查密钥，402请充值，409请检查库存、报价和幂等键，429请降低频率。

API 权限仅允许操作你自己的订单和余额。退款由管理员核实处理；付款方式、结算汇率及商品售后以后台配置和商品说明为准。