对外 API 接入文档

1. 基础信息

2. 认证方式

三类凭证，互不通用。服务端到服务端用 API Key；客户自助查单用订单 Token。

2.1 API Key（渠道方 / 合作方）

两种写法等价，任选其一。密钥格式 sfk_<32 位 urlsafe base64>。

# 写法 A
Authorization: Bearer sfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 写法 B
X-API-Key: sfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

2.2 订单 Token（客户自助查单 / 下载）

X-Order-Token: <token>

下单成功时服务端签发，token 绑定到具体订单号。持 token 只能访问该订单，不能越权看别人的单。

2.3 公开路径（无需凭证）

3. 统一响应格式

3.1 成功

{
  "ok": true,
  "data": { "...": "业务载荷" }
}

3.2 失败

{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "缺少必填字段：name",
    "details": { "field": "name" },
    "retryable": false
  }
}

4. 端点全表

幂等列：是 = 副作用接口，必须带 Idempotency-Key；否 = 只读。

4.1 建单参数

spec 各 SKU 的字段：

4.2 建单响应

{
  "ok": true,
  "data": {
    "order_id": "ORD-20261108-1A2B",
    "sku": "016",
    "tier": "script_pack",
    "tier_label": "脚本包",
    "price": 329,
    "includes": ["脚本正文", "字幕文件", "拍摄清单"],
    "not_in_scope": ["不含视频成片", "不含代运营发布"],
    "pay_note": "转账请备注订单号 ORD-20261108-1A2B",
    "delivery_hours": 48,
    "rework_free_limit": 2
  }
}

5. 幂等用法

所有产生副作用的请求（建单、退款、返工等）都必须带 Idempotency-Key。

Idempotency-Key: cust_9f2:order:1

# 也接受放在请求体里（字段名 idempotency_key），此时优先级低于请求头
{ "idempotency_key": "cust_9f2:order:1", "...": "..." }

6. 限流与 Retry-After

滑动窗口（sliding window）计数，窗口 60 秒，非固定窗口。超限返回 429。

6.1 响应头

Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1762562295

7. 错误码表

共 69 条，覆盖 400 / 401 / 403 / 404 / 409 / 422 / 429 / 500 / 503。

7.1 400 参数与请求格式

7.2 401 / 403 认证与授权

7.3 404 资源不存在

7.4 409 冲突

7.5 422 语义校验失败

7.6 429 限流与配额 / 5xx 服务端

7.7 别名与「契约码 vs 实际返回码」

网关内部有少量集成别名，与 14 号契约的正式码一一对应。对外返回哪个码，以「实际返回码」列为准；两列都列出来，是为了让你在日志与文档之间不会对不上。

8. 调用示例

8.1 curl

BASE=http://127.0.0.1:8080
KEY=sfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# 1. 看 SKU 目录（公开）
curl -s $BASE/api/skus | head -c 400

# 2. 报价（公开）
curl -s -X POST $BASE/api/quote \
  -H 'Content-Type: application/json' \
  -d '{"sku":"016","spec":{"brand":"青山茶铺","product":"冷萃乌龙茶",
       "audience":"一二线城市白领","platform":"douyin","count":5}}'

# 3. 建单（需 API Key + 幂等键）
curl -s -X POST $BASE/api/order \
  -H "Authorization: Bearer $KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: channel_a:order:1' \
  -d '{"sku":"016","spec":{"brand":"青山茶铺","product":"冷萃乌龙茶",
       "audience":"一二线城市白领","platform":"douyin","count":5},
       "name":"青山茶铺","phone":"13812345678","channel":"xhs"}'

# 4. 客户查单（订单 Token）
curl -s "$BASE/api/portal/order?order_id=ORD-20261108-1A2B" \
  -H "X-Order-Token: $TOKEN"

# 5. 下载交付物
curl -s -o out.zip "$BASE/api/portal/download/ORD-20261108-1A2B/脚本包.zip" \
  -H "X-Order-Token: $TOKEN"

8.2 Python

import os, time, uuid, json, urllib.request, urllib.error

BASE = os.environ.get("SF_BASE", "http://127.0.0.1:8080")
KEY  = os.environ.get("SF_API_KEY", "")

def call(method, path, body=None, headers=None, idem=None):
    h = {"Accept": "application/json"}
    if body is not None:
        h["Content-Type"] = "application/json"
    if KEY:
        h["Authorization"] = "Bearer " + KEY
    if idem:
        h["Idempotency-Key"] = idem
    h.update(headers or {})

    data = json.dumps(body).encode("utf-8") if body is not None else None
    req = urllib.request.Request(BASE + path, data=data, headers=h, method=method)

    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            return r.status, json.loads(r.read().decode("utf-8"))
    except urllib.error.HTTPError as e:
        payload = json.loads(e.read().decode("utf-8") or "{}")
        return e.code, payload

def is_retryable(payload):
    return bool(payload.get("error", {}).get("retryable"))

def create_order(sku, spec, name, phone, channel="web"):
    # 幂等键在整个重试过程中保持不变
    key = "channel_a:order:" + str(uuid.uuid4())
    for attempt in range(3):
        status, payload = call("POST", "/api/order",
                               {"sku": sku, "spec": spec, "name": name,
                                "phone": phone, "channel": channel}, idem=key)
        if status < 300:
            return payload["data"]
        if not is_retryable(payload):
            raise RuntimeError(payload["error"])
        time.sleep(2 ** attempt)   # 退避
    raise RuntimeError("重试 3 次仍失败")

data = create_order(
    "016",
    {"brand": "青山茶铺", "product": "冷萃乌龙茶",
     "audience": "一二线城市白领", "platform": "douyin", "count": 5},
    "青山茶铺", "13812345678", channel="xhs",
)
print("订单号:", data["order_id"], "金额:", data["price"], "元")
print("付款备注:", data["pay_note"])

8.3 JavaScript

const BASE = "http://127.0.0.1:8080";
const KEY = "sfk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx";

async function call(method, path, body, { idempotencyKey, headers = {} } = {}) {
  const h = { Accept: "application/json", ...headers };
  if (KEY) h["Authorization"] = `Bearer ${KEY}`;
  if (body !== undefined) h["Content-Type"] = "application/json";
  if (idempotencyKey) h["Idempotency-Key"] = idempotencyKey;

  const res = await fetch(BASE + path, {
    method,
    headers: h,
    body: body === undefined ? undefined : JSON.stringify(body),
  });

  const payload = await res.json().catch(() => ({}));
  if (!payload.ok) {
    const err = new Error(payload.error?.message || "请求失败");
    err.code = payload.error?.code;
    err.retryable = !!payload.error?.retryable;
    err.status = res.status;
    if (res.status === 429) err.retryAfter = Number(res.headers.get("Retry-After") || 5);
    throw err;
  }
  return payload.data;
}

async function createOrder(sku, spec, name, phone, channel = "web") {
  const key = `channel_a:order:${crypto.randomUUID()}`;
  for (let i = 0; i < 3; i++) {
    try {
      return await call("POST", "/api/order",
        { sku, spec, name, phone, channel }, { idempotencyKey: key });
    } catch (e) {
      if (!e.retryable) throw e;             // 只重试可重试错误
      const wait = e.retryAfter ?? 2 ** i;    // 限流按 Retry-After
      await new Promise(r => setTimeout(r, wait * 1000));
    }
  }
  throw new Error("重试 3 次仍失败");
}

const data = await createOrder("016", {
  brand: "青山茶铺", product: "冷萃乌龙茶",
  audience: "一二线城市白领", platform: "douyin", count: 5,
}, "青山茶铺", "13812345678", "xhs");

console.log("订单号:", data.order_id, "金额:", data.price, "元");
console.log("付款备注:", data.pay_note);

9. 接入检查清单