让你的商城接入星火AI
面向代理商城服务端:同步商品与库存、创建订单、获取支付宝付款链接、查询付款和兑换凭证。
本接口采用「客户向星火AI支付宝付款,核实到账后发货」。金额由主站按商品零售价计算,分佣沿用代理档位。特级代理的微信拿货价不在本版API自动扣款。
1. 获取你的独立密钥
店主在主站「代理管理 → 代理API」为你的代理账号创建密钥。API地址:
https://xn--ai-4y7dq09a.com/api/partner/v1
每次请求加入请求头:
Authorization: Bearer 你的完整API密钥
密钥只显示创建时这一次,请放在你的商城服务端环境变量中。不要放进网页、App前端、URL或公开代码。密钥到期、被停用或代理被停用后,接口返回401。更换密钥不影响同一代理查询原有API订单。
2. 四个接口
| 方法 | 路径 | 作用 |
|---|---|---|
| GET | /products | 商品编号、名称、零售价及可用库存 |
| POST | /orders | 创建待付款订单,每单一份 |
| POST | /orders/{merchantOrderId}/payment | 获取支付宝付款跳转链接 |
| GET | /orders/{merchantOrderId} | 查询订单,到账发货后返回兑换凭证 |
每个密钥每分钟总计120次请求,其中创建订单最多20次、获取付款链接最多30次。429响应的 Retry-After 表示需要等待的秒数。
3. 创建订单并引导付款
先读取商品列表,使用返回的商品编号创建订单。代理订单号由你的商城生成,长度1至64位,只包含字母、数字、下划线或短横线,首字符为字母或数字。
POST /orders
Content-Type: application/json
{
"merchantOrderId": "MYSHOP_20261015_0001",
"productId": "chatgpt-plus"
}同一个代理订单号重复提交会返回原订单,不会重复占库存。网络超时后请先查询或用同一订单号重试;同一订单号不可换商品。API不接受客户端提交的价格、已付款标记、代理编号或卡密。
{
"merchantOrderId": "MYSHOP_20261015_0001",
"orderId": "DS…",
"priceCents": 14800,
"currency": "CNY",
"status": "pending",
"paymentVerified": false,
"checkoutUrl": "https://星火ai.com/order.html#订单访问令牌"
}所有金额以「分」为单位,14800表示148元。将客户引导到返回的 checkoutUrl 进入主站收银台;也可以调用 /orders/{merchantOrderId}/payment,取得 paymentUrl 后让客户跳转支付宝。支付宝付款完成后返回主站订单页。checkoutUrl 包含订单访问凭证,只交给该订单客户。
4. 付款后查询发货
客户付款期间每10至15秒查询一次订单。服务器会通过支付宝签名通知或主动查单确认真实付款。只有同时返回 paymentVerified=true 和 delivery.code 才表示已确认收款并完成发货。
{
"merchantOrderId": "MYSHOP_20261015_0001",
"status": "delivered",
"paymentVerified": true,
"delivery": { "code": "兑换凭证内容" }
}本版采用轮询查询,暂不向代理服务器推送回调。不要根据客户截图、前端页面跳转或客户端提交的付款状态发货。过期订单保持原订单号;需要重新购买时使用新的代理订单号。支付到达但暂未发货时继续查询并提示联系客服,不要让客户重复付款。
Node.js 示例
import { XinghuoPartnerClient } from './partner-client.mjs';
const client = new XinghuoPartnerClient({
apiKey: process.env.XINGHUO_API_KEY
});
const catalog = await client.products();
const order = await client.createOrder({
merchantOrderId: 'MYSHOP_20261015_0001',
productId: catalog.products[0].id
});
// 由你的服务端把 order.checkoutUrl 提供给该订单客户。
const status = await client.order(order.merchantOrderId);
if (status.paymentVerified && status.delivery?.code) {
// 保存并向该订单客户展示 status.delivery.code。
}常见响应
200:成功或重复订单返回原单;201:新订单创建成功;400:参数不正确;401:密钥无效;404:商品、订单或接口不存在;409:库存不足、订单号冲突或当前状态不能付款;413:请求过大;415:JSON格式请求头不正确;429:调用过快;503:支付宝或服务暂时不可用。
错误格式:{"error":"错误说明"}。代理仅能查询由自己API创建的订单;所有代理共用库存,库存数字可能随其他客户购买而变化。