# 本站开发者 API 文档

更新：2026-10-21

基础地址：https://gpt.fkphp.com
文档：https://gpt.fkphp.com/developers

本文包括发卡（商品、余额采购、查单）与兑换（卡密状态、账号充值、订阅核查）全部接口。所有接口仅接受签名 POST 表单请求。示例商品、卡密、账号、响应均为占位，不可直接充值测试。

## 1. 接入与业务流程

注册本站账号，在开发者中心创建 USDT 开通订单，默认开通费20 USDT（以页面当前后台配置为准），加不超过0.999 USDT的识别尾差。仅支持 TRC20，20分钟内一次性准确转账；链上确认后自动开通，验证登录密码领取首次密钥。开通费不计入拿货余额；异常付款及退款联系客服人工核实。

商户使用人民币预存余额拿货。开通后在开发者中心发起 USDT 自助充值，使用 TRC20 按订单显示的三位小数金额在20分钟内准确转账，到账核验后自动增加人民币余额。汇率以创建充值订单时后台配置为准，含识别尾差的实收 USDT 全部折算，人民币向下取整到分；后续汇率变化不影响原单。异常收款由客服核实真实链上流水，重复扫描和重试不会重复入账。开发者中心可查看余额与流水，凭本站登录密码重置 API 密钥。已有商户无需重复支付开通费。

你的程序负责向自己的买家展示商品、设置零售价并收款；再用自己的商户余额调用本站采购接口。拿货按本站当前售价计费，你可以在此基础上自行加价。本站不会代你的程序向买家收款。

先拉取商品 → 查询实际规格总价 → 你的程序确认买家付款 → 以固定 request_no 采购 → 保存本站 tradeNo 并查单 → 领取卡密 → 按卡密类型提交兑换。价格、库存以下单重新核查为准。建议传 max_amount 限制本次可接受的拿货总金额。

接口只开放当前上架、有效、可识别规格的自动发货商品；预选卡、自定义设备和优惠券暂未开放。基础路径与上游常用协议相同，使用本站凭据和本站商品编码。不要填写其他销售站点的编码或卡密。

## 2. 请求与鉴权

所有机器接口仅接受 POST application/x-www-form-urlencoded；包括兑换接口。Session 对象请先 JSON 编码成 session_info 字符串。不要在 URL、浏览器、日志、公开仓库或聊天截图中放 app_key、签名、卡密或账号凭据。

每次请求带 app_id、sign_type、timestamp、nonce、sign。timestamp 为 Unix 秒时间戳，与服务器相差不超过300秒；nonce 为16～64位字母数字、下划线或短横线，每次 HTTP 请求重新生成。相同 nonce 会拒绝；采购重试只换 nonce/timestamp，request_no 和全部业务参数保持原样。

推荐 HMAC-SHA256：去掉 sign，按顶层键名排序，删除值严格为空字符串的字段（保留0），使用 PHP http_build_query 的 RFC1738 表单编码，以 app_key 为密钥计算小写 HMAC-SHA256。不要 URL 解码。嵌套 sku/fields 数组的顺序与发送内容保持一致。

兼容 MD5（sign_type=MD5 或省略）：排序和空串处理同上，编码后追加 &key=app_key，再整体 urldecode 后计算小写 MD5。该旧算法存在分隔符歧义，因此 MD5 参数值不允许 &、= 或控制字符；包含这类 Session/Token 的请求必须使用 HMAC-SHA256。

timestamp/nonce 是相对原常用协议增加的必填防重放字段。inventory.config 返回 JSON 字符串，并额外标明 config_format=json；不是 INI。兑换也需商户签名及卡密归属校验。这些差异需要接入方适配，不能直接当作原站的全部协议替换。

| 公共字段 | 类型 | 说明 |
| --- | --- | --- |
| app_id | string | 本站开通的商户 App ID |
| sign_type | string | 推荐 HMAC-SHA256；兼容 MD5 |
| timestamp | string | Unix 秒时间戳 |
| nonce | string | 每次请求不同的16～64位随机值 |
| sign | string | 小写十六进制签名；不要提交 app_key |

## [发卡] 3. 商品与采购接口

code 类似 TS-P4，是本站商品编码；不要把分类 ID、卡密或供应商编码当作商品编码。列表价格仅作参考，具体规格和数量以 valuation 和 trade 的金额为准。inventory.factory_price 是你在本站的拿货参考价，不是本站供应商成本。

item 字段包括 id、code、name、description、price、user_price、stock、delivery_way、contact_type、password_status、minimum、maximum、config、widget、draft_status。当前 draft_status 固定为0。config.category、sku_price、wholesale/category_wholesale 中的价格均转换为本站售价。

contact_type：0不限、1手机号、2邮箱、3QQ。password_status=1 时提交6～64位 password（订单查单密码，不能填账号登录密码）。widget 项含 name/title/required，建议按 fields[控件name] 提交，也兼容非保留名称的顶层控件字段。sku 使用 sku[规格名]=选项；不传 JSON 字符串。

| 路径（全部 POST） | 额外参数 | 返回要点 |
| --- | --- | --- |
| /shared/authentication/connect | 无 | shopName、可用 balance、currency=CNY |
| /shared/commodity/items | 无 | 分类数组，每项 name、children 商品数组 |
| /shared/commodity/item | code | 商品详情、本站售价、规格 config 和 widget |
| /shared/commodity/stock | code；可选 race、sku | 实时 stock；不预留库存 |
| /shared/commodity/inventoryState | shared_code、num；可选 race、sku | available=true 表示当时检查通过，不预留库存 |
| /shared/commodity/inventory | sharedCode；可选 race、sku | count、price、user_price、factory_price、config、config_format |
| /shared/commodity/valuation | code、num；可选 race、sku | price 为本次数量和规格的人民币总价；price_scope=total |
| /shared/commodity/trade | shared_code、num、request_no；其余按商品要求 | 本站 tradeNo、实际扣款 amount、secret、state、settlement |
| /shared/commodity/query | tradeNo 或原 request_no | 仅查询当前商户自己的订单；不重新购买 |

## [发卡] 连接商户与查询余额

POST https://gpt.fkphp.com/shared/authentication/connect
Content-Type: application/x-www-form-urlencoded

验证本站商户凭据，返回店铺名称和人民币可用余额。开通费用不会加入此余额。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| 无额外参数 | — | — | 只需公共鉴权字段 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| shopName | string | 本站店铺名 |
| balance | string | 可用于采购的人民币余额，两位小数 |
| currency | string | 固定 CNY |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "shopName": "Token Store",
        "balance": "500.00",
        "currency": "CNY"
    }
}
~~~

- 不扣款。可用于接入时测试签名；余额以采购事务内实际检查为准。

## [发卡] 获取商品分类列表

POST https://gpt.fkphp.com/shared/commodity/items
Content-Type: application/x-www-form-urlencoded

返回当前上架且可通过接口采购的自动发货商品，按分类分组。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| 无额外参数 | — | — | 只需公共鉴权字段 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| data | array | 分类数组，每项 name 和 children |
| children | array | 商品对象，字段含义见商品详情接口 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": [
        {
            "name": "AI 订阅",
            "children": [
                {
                    "id": 4,
                    "code": "TS-P4",
                    "name": "示例 AI 订阅商品",
                    "description": "请核对商品及账号要求",
                    "price": "151.80",
                    "user_price": "151.80",
                    "stock": "10",
                    "delivery_way": 0,
                    "draft_status": 0,
                    "draft_premium": "0.00",
                    "contact_type": 2,
                    "password_status": 0,
                    "minimum": 1,
                    "maximum": 1000,
                    "config": {},
                    "widget": [],
                    "currency": "CNY"
                }
            ]
        }
    ]
}
~~~

- 列表来自本站同步缓存，通常每10分钟刷新。生成采购订单时仍实时核价与查库存。

## [发卡] 获取商品详情与规格

POST https://gpt.fkphp.com/shared/commodity/item
Content-Type: application/x-www-form-urlencoded

实时读取商品并返回本站售价、规格与必填信息。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 本站商品编码，如 TS-P4，从商品列表获得 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| code | string | 本站唯一商品编码，下单使用此值 |
| name / description | string | 商品名称及购买说明 |
| price / user_price | string | 本站人民币参考单价，具体规格/数量需询价 |
| stock | string | 库存参考值；不表示已预留 |
| delivery_way / draft_status | integer | 当前均为0：自动发货、不开放预选卡 |
| contact_type | integer | 0不限、1手机号、2邮箱、3QQ |
| password_status | integer | 1时采购必须提交6～64位 password |
| minimum / maximum | integer | 商品允许的购买数量范围 |
| config | object | 种类 category、规格 sku / sku_price、阶梯价 wholesale / category_wholesale |
| widget | array | 自定义填写项 name、title、required；采购填 fields[name] |
| currency | string | 固定 CNY |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "code": "TS-P4"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "id": 4,
        "code": "TS-P4",
        "name": "示例 AI 订阅商品",
        "description": "请核对商品及账号要求",
        "price": "151.80",
        "user_price": "151.80",
        "stock": "10",
        "delivery_way": 0,
        "draft_status": 0,
        "draft_premium": "0.00",
        "contact_type": 2,
        "password_status": 0,
        "minimum": 1,
        "maximum": 1000,
        "config": {},
        "widget": [],
        "currency": "CNY"
    }
}
~~~

- config.category 的键用于 race；config.sku 的维度和选项用于 sku。涉及 sku_price 的组合键由商品定义，不能猜测价格或漏选规格。

- wholesale 为数量门槛对应单价；category_wholesale 为按种类区分的阶梯价。展示值仅参考，请用 valuation 得到总价。自定义控件按 fields[控件名] 传入。

## [发卡] 查询实时库存

POST https://gpt.fkphp.com/shared/commodity/stock
Content-Type: application/x-www-form-urlencoded

检查指定商品/规格当前库存。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 本站商品编码，如 TS-P4，从商品列表获得 |
| race | string | 按商品 | config.category 的键名；无种类时省略 |
| sku | array | 按商品 | 表单数组 sku[规格名]=选项，不是 JSON 字符串 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| stock | string | 当前库存值；保持原始库存表示，不把非数字状态当成无限库存 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "code": "TS-P4"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "stock": "10"
    }
}
~~~

- 只读取、不锁定库存；库存可能在采购之前变化。

## [发卡] 检查购买数量是否可用

POST https://gpt.fkphp.com/shared/commodity/inventoryState
Content-Type: application/x-www-form-urlencoded

按商品、数量、种类及规格检查当前能否购买。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| shared_code | string | 是 | 本站商品编码，注意下划线 |
| num | integer | 建议 | 默认1；1～1000且满足商品 minimum / maximum |
| race | string | 按商品 | config.category 的键名；无种类时省略 |
| sku | array | 按商品 | 表单数组 sku[规格名]=选项，不是 JSON 字符串 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| available | boolean | true 表示本次检查通过 |
| num | integer | 本次检查的数量 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "shared_code": "TS-P4",
    "num": "1"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "available": true,
        "num": 1
    }
}
~~~

- 失败返回业务错误而非一定返回 available=false。此接口不会创建订单、扣款或预留库存。

## [发卡] 获取库存与定价配置

POST https://gpt.fkphp.com/shared/commodity/inventory
Content-Type: application/x-www-form-urlencoded

获取库存摘要和商品配置，适合服务端刷新缓存。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| sharedCode | string | 是 | 本站商品编码；此接口使用驼峰 sharedCode |
| race | string | 按商品 | config.category 的键名；无种类时省略 |
| sku | array | 按商品 | 表单数组 sku[规格名]=选项，不是 JSON 字符串 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| count | integer | 数字库存；非数字库存表示会转换为0，请结合 stock 使用 |
| price / user_price / factory_price | string | 均为本站拿货参考价，不是供应商成本 |
| config | string | JSON 字符串，解析一次得到配置对象 |
| config_format | string | 固定 json，不是 INI |
| is_category | boolean | 是否存在种类配置 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "sharedCode": "TS-P4"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "count": 10,
        "delivery_way": 0,
        "draft_status": 0,
        "price": "151.80",
        "user_price": "151.80",
        "factory_price": "151.80",
        "config": "{}",
        "config_format": "json",
        "is_category": false
    }
}
~~~

- 配置中的价格已经按本站售价规则计算；不要再使用其他站点的商品编码或售价。

## [发卡] 计算本次采购总价

POST https://gpt.fkphp.com/shared/commodity/valuation
Content-Type: application/x-www-form-urlencoded

按当前数量与规格实时询价，不扣款。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 本站商品编码，如 TS-P4，从商品列表获得 |
| num | integer | 建议 | 默认1；1～1000且满足商品 minimum / maximum |
| race | string | 按商品 | config.category 的键名；无种类时省略 |
| sku | array | 按商品 | 表单数组 sku[规格名]=选项，不是 JSON 字符串 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| price | string | 本次数量合计人民币金额，不是单价 |
| currency | string | CNY |
| price_scope | string | 固定 total |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "code": "TS-P4",
    "num": "1"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "price": "151.80",
        "currency": "CNY",
        "price_scope": "total"
    }
}
~~~

- 报价不预留库存和价格。建议把核对后的总价作为 trade.max_amount 上限；超出时采购会被拒绝且不扣余额。

## [发卡] 使用余额采购发卡

POST https://gpt.fkphp.com/shared/commodity/trade
Content-Type: application/x-www-form-urlencoded

先预扣商户人民币余额，再采购并返回订单。由你的程序先向买家收款，本站不代你收款。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| shared_code | string | 是 | 本站商品编码，注意下划线 |
| num | integer | 建议 | 默认1；1～1000且满足商品 minimum / maximum |
| request_no | string | 是 | 8～64位字母数字或 _ . : -，独立购买唯一，重试固定不变 |
| race | string | 按商品 | config.category 的键名；无种类时省略 |
| sku | array | 按商品 | 表单数组 sku[规格名]=选项，不是 JSON 字符串 |
| contact | string | 按商品 | 满足 contact_type 的联系方式，最长128字符 |
| password | string | 按商品 | 订单查询密码6～64位，不是目标账号密码 |
| fields | array | 按商品 | 一层表单数组 fields[widget.name]=填写内容 |
| max_amount | decimal | 推荐 | 人民币总额上限，如151.80；两位小数 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| tradeNo | string | 本站订单号，请保存；不是供应商订单号 |
| request_no | string | 你的原始业务订单号，同一商户幂等 |
| amount | string | 本单实际扣款，已退款时为0.00 |
| order_amount | string | 最初订单总额，退款后仍保留 |
| status | integer | 1表示本站已用余额支付，不表示已兑换成功 |
| state | string | waiting / processing / delivered / failed / manual / unknown |
| settlement | string | reserved预扣、charged交付、refunded退回余额 |
| refunded | boolean | 是否已经退回商户余额 |
| secret | string\|null | 仅已付款且 delivered 时返回交付内容；可能是多行卡密或实际发货内容 |
| balance | string | 调用时可用人民币余额 |
| cards.available | boolean | 本站是否已识别可通过兑换 API 使用的卡密 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "shared_code": "TS-P4",
    "num": "1",
    "request_no": "YOUR_ORDER_20261021_0001",
    "contact": "customer@example.com",
    "max_amount": "151.80"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "tradeNo": "20261021000000EXAMPLE",
        "request_no": "YOUR_ORDER_20261021_0001",
        "amount": "151.80",
        "order_amount": "151.80",
        "status": 1,
        "state": "delivered",
        "settlement": "charged",
        "refunded": false,
        "secret": "YOUR_DELIVERED_CARD",
        "balance": "348.20",
        "cards": {
            "available": true
        }
    }
}
~~~

- 同一 request_no 和同一组业务参数只创建一单、预扣一次。重复请求只返回原订单，不会再次采购。参数变化返回 request.conflict；nonce / timestamp 每次仍必须更新。

- 余额不足或超出 max_amount 时不创建采购单。超时或 unknown 必须先查原单；禁止改请求号盲目重买。明确失败会自动退回原扣款，原请求号仍指向失败单。

- 未开放 coupon、非零 card_id、非零 device 与 draftCard/draft 预选卡功能；请勿提交未知字段。

## [发卡] 查询原采购订单

POST https://gpt.fkphp.com/shared/commodity/query
Content-Type: application/x-www-form-urlencoded

通过本站订单号或原业务请求号查单，不产生新的采购。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| tradeNo | string | 二选一 | trade 返回的本站订单号 |
| request_no | string | 二选一 | 采购时原业务请求号；两者同时传入时优先 tradeNo |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| tradeNo | string | 本站订单号，请保存；不是供应商订单号 |
| request_no | string | 你的原始业务订单号，同一商户幂等 |
| amount | string | 本单实际扣款，已退款时为0.00 |
| order_amount | string | 最初订单总额，退款后仍保留 |
| status | integer | 1表示本站已用余额支付，不表示已兑换成功 |
| state | string | waiting / processing / delivered / failed / manual / unknown |
| settlement | string | reserved预扣、charged交付、refunded退回余额 |
| refunded | boolean | 是否已经退回商户余额 |
| secret | string\|null | 仅已付款且 delivered 时返回交付内容；可能是多行卡密或实际发货内容 |
| balance | string | 调用时可用人民币余额 |
| cards.available | boolean | 本站是否已识别可通过兑换 API 使用的卡密 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "request_no": "YOUR_ORDER_20261021_0001"
}
~~~

### 响应示例

~~~json
{
    "code": 200,
    "error": "",
    "msg": "success",
    "data": {
        "tradeNo": "20261021000000EXAMPLE",
        "request_no": "YOUR_ORDER_20261021_0001",
        "amount": "151.80",
        "order_amount": "151.80",
        "status": 1,
        "state": "delivered",
        "settlement": "charged",
        "refunded": false,
        "secret": "YOUR_DELIVERED_CARD",
        "balance": "348.20",
        "cards": {
            "available": true
        }
    }
}
~~~

- 只能查当前商户的订单。建议至少5秒查一次，超过速率限制须退避。

- delivered 且 secret 非空才取得发货内容；manual / unknown 请人工核实。已失败并退余额的订单仍返回原数据，但外层 code=0、error=trade.failed。

- cards.available=false 可稍后查询原单重试卡密识别，不重复扣费；仅成功识别且属于当前商户的卡密可调用兑换接口。

## [发卡] 4. 采购字段与金额

同一商户的相同 request_no 只创建一个本站订单、预扣一次余额，并且不允许改变商品、数量、规格、联系方式等业务参数。重复请求会返回原订单的最新结果，不再次采购。不同商户的相同 request_no 相互隔离。不要把网络重试当作一笔新的购买。

| 字段 | 必填 | 规则 |
| --- | --- | --- |
| shared_code | 是 | 本站商品编码，例如 TS-P4 |
| num | 是 | 1～1000整数，并满足商品最小/最大数量 |
| request_no | 是 | 8～64位字母数字或 _ . : -；你的每次独立购买使用唯一值 |
| contact | 按商品要求 | 有效联系方式，最长128字符 |
| race / sku | 按商品要求 | 选择 item.config 中的种类和规格，键名与选项保持原值 |
| password | 按商品要求 | 订单查询密码，不是 GPT/Claude 登录密码 |
| fields | 按商品要求 | 一层表单数组，填入 widget 定义的填写项 |
| max_amount | 推荐 | 本次人民币总额上限；超过则不创建订单、不扣余额 |

~~~
app_id=YOUR_APP_ID
sign_type=HMAC-SHA256
timestamp=YOUR_UNIX_TIMESTAMP
nonce=YOUR_FRESH_RANDOM_NONCE
shared_code=TS-P4
num=1
request_no=YOUR_ORDER_20261021_0001
max_amount=200.00
contact=customer@example.com
sign=YOUR_CALCULATED_SIGNATURE
~~~

## [发卡] 5. 响应、查单与余额处理

发卡接口检查 JSON code=200；HTTP 200 不等于业务成功。业务失败 code=0，并有稳定 error、msg；查已失败订单时 data 仍可能含原 tradeNo 和退款状态。鉴权/格式/限流/服务错误可能同时使用 HTTP 4xx/503，程序须保留原 request_no。

采购先在事务内预扣商户可用余额，settlement=reserved；实际发货后为 charged，不再次扣钱。waiting/processing/manual/unknown 不代表已经交付，secret 可能为 null。status=1 只表示本站订单已用余额支付，不表示卡密已激活或订阅已到账。

上游明确采购失败时，在同一事务内将原金额退回商户余额，settlement=refunded、refunded=true、amount=0.00，order_amount 保留原订单金额。相同请求号仍返回这个失败订单，不会重新扣费。如确需重新购买，应先确认原单已明确失败且已退回余额，再用新的业务请求号发起独立订单。

HTTP 超时、503、响应损坏或 state=unknown 时，可能已经扣款或采购。请使用原 request_no 或已取得的本站 tradeNo 查询，等待原订单处理；不能换新请求号重买，也不能假设已退款。人工发货待核实同样不自动退余额。

只有 state=delivered 且 secret 非空时才取得发货内容。secret 可能是完整卡密、多行卡密、实际礼品链接或发货说明；不要把任何字符串都当成可充值卡密。cards.available=false 时可稍后查原单重试识别，不会再次采购。

| error / state | 含义 | 程序处理 |
| --- | --- | --- |
| balance.insufficient | 商户余额不足，未采购 | 补充余额后重试原请求 |
| price.changed | 超过 max_amount，未采购 | 重新核对报价与买家订单 |
| request.conflict | 原请求号业务参数发生变化 | 恢复原参数，不新建重复订单 |
| auth.replay / auth.expired | nonce 重复或时间超窗 | 生成新 nonce、timestamp，业务请求号不变 |
| trade.failed / refunded | 采购明确失败且余额已退 | 按原单完成售后；新购买须单独确认 |
| unknown / manual | 采购结果未知或已接单未交付 | 查询原单，人工核实，禁止盲目重买 |
| rate.limited | 调用过于频繁 | 遵循 Retry-After，建议查单间隔至少5秒 |

~~~
{
  "code": 200,
  "error": "",
  "msg": "success",
  "data": {
    "tradeNo": "20261021000000EXAMPLE",
    "request_no": "YOUR_ORDER_20261021_0001",
    "amount": "151.80",
    "order_amount": "151.80",
    "status": 1,
    "state": "delivered",
    "settlement": "charged",
    "refunded": false,
    "secret": "YOUR_DELIVERED_CARD",
    "balance": "348.20",
    "cards": {"available": true}
  }
}
~~~

## [兑换] 6. 兑换接口与账号风险

兑换响应使用 success 布尔值、稳定字符串 code、msg、data，区别于发卡接口的数字 code。鉴权、归属和格式失败仍可能返回数字 code=0 的公共错误结构，程序应先检查 HTTP 与 error。卡密必须完整，不能猜测固定分段格式。

gpt 支持 Session JSON字符串或 account.id 的标准 UUID；不要使用 user.id 或 workplace 工作空间 UID。claude 支持 SessionKey 或 Organization ID；claude_s 只支持 SessionKey；grok 支持 uid。所有调用均需本站商户签名，不能直接使用其他商户、普通商城订单或其他渠道的卡密。

提交前你的程序必须让买家确认卡密、套餐、目标账号和对应风险，再传 confirm=1。GPT force=1 还需单独确认放弃剩余会员时间，传 force_confirm=1；force 不绕过冷却或重复充值限制。

Claude UID 方式无法完整预检账号封禁、订阅和账务状态，错误账号可能消耗卡密但无法到账。建议 SessionKey。Max 商品需按商品和兑换要求核对注册时长、身份认证、账务及账号可用状态。

activation.processing 只查询原卡密，不能反复 activate；activation.verify_failed 表示仍需买家重新登录核实，不能仅凭 use_status=1 判断最终到账。in_cooldown=true 且剩余秒数0表示未知，不代表冷却已结束。查询和刷新不等于重新充值。

如发货内容已取得但卡密尚未识别，先查询原采购订单以重试识别，再调用 check。账号 Session/Token 仅用于本次请求转发，本站不会写入订单、数据库或普通日志；接入方也应采用相同保密措施。

| 路径（全部 POST） | 额外字段 | 说明 |
| --- | --- | --- |
| /api/check | cdkey | 仅当前商户通过本接口购买并交付的卡密 |
| /api/activate | cdkey、confirm=1；session_info 或 uid | 有 Session 时优先 Session，不在 Session 失败后自动降级 UID |
| /api/service_status | cdkey；可选 product | product 若提供必须匹配卡密的 service_product |
| /api/claude_refresh | cdkey、session_info | Claude 的原 SessionKey 刷新；遵循 retry_after |
| /api/refresh-subscription | cdkey、session_info | GPT 的原 Session / Token 查询刷新 |

## [兑换] 查询卡密状态与适用产品

POST https://gpt.fkphp.com/api/check
Content-Type: application/x-www-form-urlencoded

兑换前和提交后查询同一卡密，判断账号类型、冷却及处理进度。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cdkey | string | 是 | 当前商户通过余额采购获得并已识别的完整卡密，最长2000字节 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| success | boolean | 请求业务结果，不等于订阅到账 |
| code | string | 稳定状态码，例如 activation.ready / processing / completed / verify_failed |
| data.app | string | gpt / claude / claude_s / grok，决定提交账号方式 |
| data.gift_name / service_product | string | 卡密套餐名和服务产品标识 |
| data.use_status | integer | 0未使用，1已使用，-1等其他状态须结合 status_code 核实 |
| data.status_code / status_hint | string | 当前阶段与操作提示 |
| data.in_cooldown / cooldown_remaining | boolean / integer | 冷却标记及秒数；冷却中且0秒表示时长未知 |
| data.account / completed_at | string，可选 | 领取账号标识和完成时间，是否返回取决于阶段 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "cdkey": "YOUR_DELIVERED_CARD"
}
~~~

### 响应示例

~~~json
{
    "success": true,
    "code": "activation.ready",
    "msg": "可提交兑换",
    "data": {
        "app": "gpt",
        "gift_name": "示例订阅",
        "service_product": "EXAMPLE_PRODUCT",
        "use_status": 0,
        "status_code": "activation.ready",
        "status_hint": "请核对目标账号",
        "in_cooldown": false,
        "cooldown_remaining": 0
    }
}
~~~

- 示例仅展示部分字段，实际字段随商品及阶段变化。不能仅凭 use_status=1 判断套餐最终到账；verify_failed 需用户重新登录目标账号核实。

## [兑换] 查询产品服务状态

POST https://gpt.fkphp.com/api/service_status
Content-Type: application/x-www-form-urlencoded

检查该卡密对应服务是否正常，不提交充值。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cdkey | string | 是 | 当前商户通过余额采购获得并已识别的完整卡密，最长2000字节 |
| product | string | 否 | 若提供，必须与 check.data.service_product 一致 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| data.level | string | normal正常、unstable不稳定、abnormal异常、unknown未知 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "cdkey": "YOUR_DELIVERED_CARD"
}
~~~

### 响应示例

~~~json
{
    "success": true,
    "data": {
        "level": "normal"
    }
}
~~~

- 即便查询服务状态也必须传所属卡密并签名；不能匿名按 product 查询。缺少服务产品标识时返回 unknown。服务状态不等于库存或到账保证。

## [兑换] 提交账号兑换充值

POST https://gpt.fkphp.com/api/activate
Content-Type: application/x-www-form-urlencoded

把已取得的卡密兑换至买家明确确认的目标账号。此步骤可能消耗卡密，不能当作报价或试调用。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cdkey | string | 是 | 当前商户通过余额采购获得并已识别的完整卡密，最长2000字节 |
| confirm | string | 是 | 固定1，调用前由你的程序展示套餐、账号及风险并获得确认 |
| session_info | string | 按方式 | GPT：Session JSON 字符串或支持的 Token，最长262144字节；Claude：sk-ant-sid 开头 SessionKey，最长2000字节 |
| uid | string | 按方式 | GPT account.id 标准UUID；Claude Organization ID 标准UUID；Grok uid |
| force | string | 否 | 仅 GPT Session 方式，1代表申请覆盖剩余套餐 |
| force_confirm | string | force=1时 | 固定1，必须另行确认剩余会员时间损失风险 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| code / data.status_code | string | 处理阶段，后续必须通过 check 查询 |
| data.submitted_uid / redeemed_uid | string，可选 | 提交与领取账号，用于核对；是否返回视产品而定 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "cdkey": "YOUR_DELIVERED_CARD",
    "confirm": "1",
    "session_info": "{\"YOUR_SESSION_FIELD\":\"YOUR_SESSION_VALUE\"}"
}
~~~

### 响应示例

~~~json
{
    "success": true,
    "code": "activation.processing",
    "msg": "正在处理，请查询原卡密",
    "data": {
        "status_code": "activation.processing"
    }
}
~~~

- app=gpt：优先 Session 信息；UID 必须为 account.id，不可填 user.id 或工作空间ID。app=claude：推荐 SessionKey，也支持 Organization ID；claude_s 只支持 SessionKey；grok 只支持 uid。

- 有 session_info 时优先 Session，失败后不会自动降级 UID。Claude SessionKey 支持 sk-ant-sid… 或 sessionKey=sk-ant-sid…，不要提交浏览器整段 Cookie。

- Claude UID 无法完整预检封禁/账务/套餐，错误账号可能消耗卡密但无法到账。购买前应核对商品对注册时长、身份认证等要求。

- ready 且未冷却才允许提交。processing 或请求超时后仅查原卡密，勿循环 activate。force 不绕过冷却或重复充值限制。示例 Session 为占位值，必须换成真实有效结构。

## [兑换] Claude 刷新订阅

POST https://gpt.fkphp.com/api/claude_refresh
Content-Type: application/x-www-form-urlencoded

已领取后的原账号使用原 SessionKey 同步/核查订阅，不重新购买。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cdkey | string | 是 | 当前商户通过余额采购获得并已识别的完整卡密，最长2000字节 |
| session_info | string | 是 | 原领取账号的 Claude SessionKey，最长2000字节 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| success / msg | boolean / string | 本次处理结果及说明 |
| data.retry_after | integer，可选 | 再次请求前建议等待的秒数 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "cdkey": "YOUR_DELIVERED_CARD",
    "session_info": "sk-ant-sid-YOUR_ORIGINAL_SESSION_KEY"
}
~~~

### 响应示例

~~~json
{
    "success": true,
    "msg": "刷新请求已处理",
    "data": {
        "retry_after": 60
    }
}
~~~

- 仅 claude / claude_s 卡密可用，必须是原领取账号。本站先设置60秒并发保护，再按返回 retry_after 更新等待时间（5～86400秒）。响应超时后也应等待后再查询。

## [兑换] GPT 查询订阅到账情况

POST https://gpt.fkphp.com/api/refresh-subscription
Content-Type: application/x-www-form-urlencoded

按原账号 Session / Token 查询当前订阅，用于到账核对。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| cdkey | string | 是 | 当前商户通过余额采购获得并已识别的完整卡密，最长2000字节 |
| session_info | string | 是 | 原领取账号 GPT Session JSON 字符串或支持的 Token，最长262144字节 |

### 返回字段

| 返回字段 | 类型 | 含义 |
| --- | --- | --- |
| data.verify_result | array，可选 | [true,[套餐,到期时间,账号]]；失败可能为 [false,原因] |
| data.retry_after | integer，可选 | 再次查询前等待秒数 |

### 额外业务参数（JSON仅用于说明；实际发送表单并加入公共鉴权）

~~~json
{
    "cdkey": "YOUR_DELIVERED_CARD",
    "session_info": "{\"YOUR_SESSION_FIELD\":\"YOUR_SESSION_VALUE\"}"
}
~~~

### 响应示例

~~~json
{
    "success": true,
    "msg": "查询完成",
    "data": {
        "verify_result": [
            true,
            [
                "示例套餐",
                "EXAMPLE_EXPIRY",
                "EXAMPLE_ACCOUNT"
            ]
        ],
        "retry_after": 60
    }
}
~~~

- 本站必须传 cdkey 做归属和类型检查；此接口仅支持 gpt 卡密。当前订阅查询不能单独证明本次目标档位已到账，需结合套餐、账号和实际到期时间。Session/Token 不写入本站订单或普通日志。

## 7. PHP 服务端示例

下载下方 PHP SDK，保存于你自己程序的服务端；SDK 每次自动生成防重放字段和 HMAC 签名，不会自动重试采购。自己的零售价、买家付款和买家售后由自己的程序管理。示例中的商品编码、金额上限、账号信息均须替换为实际核对结果。

~~~
require 'MerchantClient.php';
$client = new TokenStoreMerchantClient(
    'https://YOUR_STORE_DOMAIN',
    getenv('STORE_APP_ID'),
    getenv('STORE_APP_KEY')
);
$items = $client->call('/shared/commodity/items');
$quote = $client->call('/shared/commodity/valuation', [
    'code' => 'TS-P4', 'num' => '1'
]);
// Save your business order and fixed request_no BEFORE requesting purchase.
$result = $client->call('/shared/commodity/trade', [
    'shared_code' => 'TS-P4', 'num' => '1',
    'request_no' => 'YOUR_ORDER_20261021_0001',
    'max_amount' => '200.00', 'contact' => 'customer@example.com'
]);
// Timeout / unknown: query using the SAME business request number.
$status = $client->call('/shared/commodity/query', [
    'request_no' => 'YOUR_ORDER_20261021_0001'
]);
// After presenting account risks and receiving the buyer's confirmation:
$check = $client->call('/api/check', ['cdkey' => 'YOUR_DELIVERED_CARD']);
// Session object must be encoded as a string for the form protocol.
$activation = $client->call('/api/activate', [
    'cdkey' => 'YOUR_DELIVERED_CARD', 'confirm' => '1',
    'session_info' => json_encode($targetSession, JSON_UNESCAPED_UNICODE)
]);
~~~

PHP SDK：https://gpt.fkphp.com/developers/sdk