{
  "openapi": "3.1.0",
  "info": {
    "title": "跨境无忧代理 API",
    "version": "2.0.0",
    "description": "跨境无忧自有业务 API，遵循本平台开放 API v2 兼容规范。对外只返回本地商品、售价、钱包和订单数据。"
  },
  "servers": [{"url": "https://fb.payfb.cn"}],
  "security": [{"ApiKey": [], "Timestamp": [], "Nonce": [], "Signature": []}],
  "paths": {
    "/api/v2/categories": {
      "get": {"summary": "商品分类", "responses": {"200": {"description": "开放 API v2 兼容响应"}}}
    },
    "/api/v2/products": {
      "get": {
        "summary": "商品列表",
        "parameters": [
          {"name": "lang", "in": "query", "schema": {"type": "string", "example": "zh-cn"}},
          {"name": "cate_id", "in": "query", "schema": {"type": "integer"}},
          {"name": "keyword", "in": "query", "schema": {"type": "string"}}
        ],
        "responses": {"200": {"description": "开放 API v2 兼容响应"}}
      }
    },
    "/api/v2/products/sku": {
      "get": {
        "summary": "SKU 详情与库存",
        "parameters": [
          {"name": "sku_id", "in": "query", "required": true, "schema": {"type": "integer"}},
          {"name": "lang", "in": "query", "schema": {"type": "string", "example": "zh-cn"}},
          {"name": "response_mode", "in": "query", "schema": {"type": "string", "enum": ["strict"]}}
        ],
        "responses": {"200": {"description": "开放 API v2 兼容响应"}}
      }
    },
    "/api/v2/account/balance": {
      "get": {"summary": "本平台钱包余额", "responses": {"200": {"description": "开放 API v2 兼容响应"}}}
    },
    "/api/v2/order/create": {
      "post": {
        "summary": "幂等创建订单",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {"$ref": "#/components/schemas/CreateOrderRequest"}
            }
          }
        },
        "responses": {
          "200": {"description": "业务结果；请检查 JSON code"},
          "400": {"description": "参数错误"},
          "401": {"description": "认证错误"},
          "429": {"description": "请求过于频繁"}
        }
      }
    },
    "/api/v2/order/query": {
      "get": {
        "summary": "查询订单与获取卡密",
        "parameters": [
          {"name": "request_no", "in": "query", "schema": {"type": "string", "maxLength": 64}},
          {"name": "order_no", "in": "query", "schema": {"type": "string"}}
        ],
        "responses": {"200": {"description": "已发货时 delivery_content/secret 包含完整卡密"}}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKey": {"type": "apiKey", "in": "query", "name": "api_key"},
      "Timestamp": {"type": "apiKey", "in": "query", "name": "timestamp"},
      "Nonce": {"type": "apiKey", "in": "query", "name": "nonce"},
      "Signature": {
        "type": "apiKey",
        "in": "query",
        "name": "signature",
        "description": "lowercase HMAC-SHA256 of METHOD\\ntimestamp\\nnonce\\npath\\nPHP-http_build_query(sorted business parameters)"
      }
    },
    "schemas": {
      "CreateOrderRequest": {
        "type": "object",
        "required": ["sku_id", "quantity"],
        "properties": {
          "sku_id": {"type": "integer"},
          "quantity": {"type": "integer", "minimum": 1, "maximum": 1000},
          "sku_race_id": {"type": "integer", "description": "Required only when has_race=1"},
          "remark": {"type": "string", "maxLength": 500},
          "request_no": {"type": "string", "maxLength": 64, "pattern": "^[A-Za-z0-9_-]+$"},
          "response_mode": {"type": "string", "enum": ["strict"]},
          "notify_url": {"type": "string", "format": "uri", "maxLength": 500, "description": "Must exactly match this key's enabled public HTTPS Webhook endpoint"}
        }
      },
      "OrderShippedWebhook": {
        "type": "object",
        "description": "Status-only notification. Query by request_no to retrieve cards.",
        "required": ["event", "status", "order_no", "request_no"],
        "properties": {
          "event": {"type": "string", "const": "order.shipped"},
          "status": {"type": "string", "const": "shipped"},
          "order_no": {"type": "string"},
          "request_no": {"type": "string"},
          "quantity": {"type": "integer"},
          "sku_id": {"type": "integer"},
          "deliver_time": {"type": "integer"},
          "callback_time": {"type": "integer"}
        }
      }
    }
  },
  "webhooks": {
    "orderShipped": {
      "post": {
        "summary": "order.shipped 状态通知，正文不含卡密或上游字段",
        "parameters": [
          {"name": "X-Event-Id", "in": "header", "required": true, "schema": {"type": "string"}},
          {"name": "X-Timestamp", "in": "header", "required": true, "schema": {"type": "string"}},
          {"name": "X-Signature", "in": "header", "required": true, "schema": {"type": "string"}}
        ],
        "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OrderShippedWebhook"}}}},
        "responses": {"200": {"description": "accepted; any other status is retried"}}
      }
    }
  }
}