开放平台 API 文档

接口地址: https://{your-domain}/api/open/v1

快速开始

所有接口使用 JSON,通过 AppKey + Secret 的 HMAC-SHA256 签名鉴权。请求需携带 4 个自定义头。

X-Api-KeyAPI Key(公开标识)
X-Timestamp毫秒时间戳,需在有效窗口内
X-Nonce随机串,8~64 位,不可重复使用
X-SignatureHMAC-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: —

错误码

CodeHTTP说明
BAD_SIGNATURE401签名校验失败
MISSING_AUTH_HEADER401缺少鉴权请求头
BAD_APPKEY401AppKey 无效
TIMESTAMP_EXPIRED401Timestamp 超出有效窗口
NONCE_REPLAY401Nonce 已被使用(重放)
RATE_LIMIT_IP429IP 级限流
RATE_LIMIT_KEY429API Key 级限流
KEY_FROZEN403API Key 已被冻结
KEY_REVOKED403API Key 已撤销
KEY_EXPIRED403API Key 已过期
INSUFFICIENT_BALANCE400账户余额不足
OUT_OF_STOCK400库存不足
BELOW_COST400价格低于成本底线
PRODUCT_OFF400商品已下架
NOT_FOUND404资源不存在
BAD_INPUT400参数非法