开放平台 API 文档
接口地址: https://{your-domain}/api/open/v1
快速开始
所有接口使用 JSON,通过 AppKey + Secret 的 HMAC-SHA256 签名鉴权。请求需携带 4 个自定义头。
| X-Api-Key | API Key(公开标识) |
| X-Timestamp | 毫秒时间戳,需在有效窗口内 |
| X-Nonce | 随机串,8~64 位,不可重复使用 |
| X-Signature | HMAC-SHA256 签名(hex 小写) |
认证方式
签名字符串构造:
METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + sha256(body)APP_KEY="ak_xxx"
SECRET="sk_xxx"
TS=$(date +%s%3N)
NONCE=$(openssl rand -hex 12)
BODY='{"product_id":"1","quantity":2}'
BODY_HASH=$(printf '%s' "$BODY" | sha256sum | cut -d' ' -f1)
CANON="POST\n/api/open/v1/orders\n$TS\n$NONCE\n$BODY_HASH"
SIG=$(printf '%b' "$CANON" | openssl dgst -sha256 -hmac "$SECRET" -hex | awk '{print $2}')
curl -X POST "https://accsupply.exeprog.com/api/open/v1/orders" \
-H "X-Api-Key: $APP_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIG" \
-H "Content-Type: application/json" \
-d "$BODY"商品接口
GET/api/open/v1/products
商品列表,按代理等级返回价格
Params: page, per_page, search
GET/api/open/v1/products/{id}
商品详情(含库存与价格)
Params: id 支持内部 ID 或 slug
curl "https://accsupply.exeprog.com/api/open/v1/products?per_page=20" \
-H "X-Api-Key: $APP_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIG"订单接口
POST/api/open/v1/orders
创建订单(幂等)
Params: product_id, quantity, out_trade_no
GET/api/open/v1/orders/{order_no}
查询订单状态
Params: order_no
GET/api/open/v1/orders/{order_no}/credentials
获取订单凭证(仅本人订单)
Params: order_no
下单价格一律由服务端按当前成本与会员折扣重算,前端传入的价格不生效;最终售价不会低于成本价。
账户接口
GET/api/open/v1/balance
查询账户余额
Params: —
错误码
| Code | HTTP | 说明 |
|---|---|---|
| BAD_SIGNATURE | 401 | 签名校验失败 |
| MISSING_AUTH_HEADER | 401 | 缺少鉴权请求头 |
| BAD_APPKEY | 401 | AppKey 无效 |
| TIMESTAMP_EXPIRED | 401 | Timestamp 超出有效窗口 |
| NONCE_REPLAY | 401 | Nonce 已被使用(重放) |
| RATE_LIMIT_IP | 429 | IP 级限流 |
| RATE_LIMIT_KEY | 429 | API Key 级限流 |
| KEY_FROZEN | 403 | API Key 已被冻结 |
| KEY_REVOKED | 403 | API Key 已撤销 |
| KEY_EXPIRED | 403 | API Key 已过期 |
| INSUFFICIENT_BALANCE | 400 | 账户余额不足 |
| OUT_OF_STOCK | 400 | 库存不足 |
| BELOW_COST | 400 | 价格低于成本底线 |
| PRODUCT_OFF | 400 | 商品已下架 |
| NOT_FOUND | 404 | 资源不存在 |
| BAD_INPUT | 400 | 参数非法 |