{
  "openapi": "3.1.0",
  "info": {
    "title": "速通智达开放平台 API",
    "version": "1.0.0",
    "summary": "跨城急件当日达的询价、下单、查询、轨迹、取消与城市列表接口",
    "description": "本规范声明速通智达开放平台已公开的接口路径、鉴权方式与业务语义。接口网关地址（Base URL）、AppId 与 AppSecret 在商务开通后下发；请求与响应的具体字段以接入后发放的正式接口文档为准。平台采用「先询价、后下单」机制：先调用 /v1/quote 获取 quoteId 与报价（有效期 30 分钟），再凭 quoteId 调用 /v1/order/create，下单时服务端按报价单锁定金额。",
    "contact": {
      "name": "速通智达开放平台",
      "url": "https://savir.com.cn/openapi",
      "email": "luofuyuan@gxyxdz.cn"
    },
    "x-brand": "速通智达",
    "x-operator": "广西宜鑫电子有限公司",
    "x-usci": "91450100MAE2C95732",
    "x-agent-manifest": "https://savir.com.cn/agent.json",
    "x-onboarding": {
      "steps": [
        "提交接入申请（企业信息、业务场景、预估单量）",
        "商务确认合作方式与折扣档位并签署协议",
        "开通沙箱环境并发放 AppId / AppSecret",
        "按文档联调：询价 → 下单 → 查询 → 回调",
        "切换生产环境，月结对账"
      ],
      "typicalLeadTime": "最快 3 个工作日上线",
      "fee": "标准接口接入不额外收费，具体以合作协议为准"
    },
    "x-mcp": {
      "status": "unavailable",
      "note": "当前未提供 MCP 服务端点；智能体需按本规范的 REST 接口对接，或经人工渠道下单。"
    },
    "x-humanChannel": {
      "phone": "132-7770-1086",
      "hours": "7×24",
      "miniProgram": "速通智达"
    }
  },
  "externalDocs": {
    "description": "接入流程、鉴权算法与商务说明",
    "url": "https://savir.com.cn/openapi"
  },
  "servers": [
    {
      "url": "/",
      "description": "占位服务器。实际网关地址在商务开通后随 AppId 与 AppSecret 一并下发。"
    }
  ],
  "tags": [
    {
      "name": "报价",
      "description": "运费试算与报价单"
    },
    {
      "name": "订单",
      "description": "创建、查询、轨迹与取消"
    },
    {
      "name": "基础数据",
      "description": "开通城市与编码"
    }
  ],
  "security": [
    {
      "AppId": []
    },
    {
      "Timestamp": []
    },
    {
      "Nonce": []
    },
    {
      "Sign": []
    }
  ],
  "paths": {
    "/v1/quote": {
      "post": {
        "tags": [
          "报价"
        ],
        "summary": "运费试算",
        "description": "输入收发城市与重量，返回权威报价与 quoteId。报价有效期 30 分钟，超时需重新询价。",
        "operationId": "createQuote",
        "requestBody": {
          "required": true,
          "description": "请求体字段名与结构以正式接口文档为准；语义上必须包含发件城市、收件城市与重量。",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "返回报价金额与 quoteId（有效期 30 分钟）。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败：签名不通过时平台直接拒绝请求。"
          }
        },
        "x-validity-minutes": 30,
        "x-documented-semantics": [
          "发件城市",
          "收件城市",
          "重量"
        ],
        "x-fields-finalized-in": "接入后发放的正式接口文档"
      }
    },
    "/v1/order/create": {
      "post": {
        "tags": [
          "订单"
        ],
        "summary": "创建订单",
        "description": "凭 quoteId 下单。服务端按报价单强制锁定金额，请求中传入的价格字段不生效。物品名称与性质须在 goods.desc 中如实申报，寄件方对申报内容负责。",
        "operationId": "createOrder",
        "requestBody": {
          "required": true,
          "description": "必须携带有效 quoteId 与物品描述（goods.desc）；其余字段以正式接口文档为准。",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "订单创建成功，返回订单标识与锁定金额。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败：签名不通过时平台直接拒绝请求。"
          }
        },
        "x-price-locked-server-side": true,
        "x-documented-semantics": [
          "quoteId",
          "goods.desc 物品名称与性质",
          "收发件人信息"
        ],
        "x-fields-finalized-in": "接入后发放的正式接口文档"
      }
    },
    "/v1/order/detail": {
      "post": {
        "tags": [
          "订单"
        ],
        "summary": "订单查询",
        "description": "返回订单状态、费用明细与收发信息。",
        "operationId": "getOrderDetail",
        "requestBody": {
          "required": true,
          "description": "请求体字段以正式接口文档为准。",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "订单状态、费用明细与收发信息。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败：签名不通过时平台直接拒绝请求。"
          }
        },
        "x-documented-semantics": [
          "订单标识"
        ],
        "x-fields-finalized-in": "接入后发放的正式接口文档"
      }
    },
    "/v1/order/track": {
      "post": {
        "tags": [
          "订单"
        ],
        "summary": "轨迹查询",
        "description": "返回物流节点，包含已取件、已到站、已送达等状态。",
        "operationId": "getOrderTrack",
        "requestBody": {
          "required": true,
          "description": "请求体字段以正式接口文档为准。",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "物流节点列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败：签名不通过时平台直接拒绝请求。"
          }
        },
        "x-documented-semantics": [
          "订单标识"
        ],
        "x-fields-finalized-in": "接入后发放的正式接口文档"
      }
    },
    "/v1/order/cancel": {
      "post": {
        "tags": [
          "订单"
        ],
        "summary": "取消订单",
        "description": "支持备注取消原因，系统自动校验订单归属。",
        "operationId": "cancelOrder",
        "requestBody": {
          "required": true,
          "description": "请求体字段以正式接口文档为准；可携带取消原因备注。",
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "取消结果。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败：签名不通过时平台直接拒绝请求。"
          }
        },
        "x-documented-semantics": [
          "订单标识",
          "取消原因（可选）"
        ],
        "x-fields-finalized-in": "接入后发放的正式接口文档"
      }
    },
    "/v1/city/list": {
      "get": {
        "tags": [
          "基础数据"
        ],
        "summary": "城市列表",
        "description": "返回全部开通城市及其编码，便于接入方本地映射。",
        "operationId": "listCities",
        "responses": {
          "200": {
            "description": "开通城市及编码列表。",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "401": {
            "description": "鉴权失败：签名不通过时平台直接拒绝请求。"
          }
        },
        "x-documented-semantics": [],
        "x-fields-finalized-in": "接入后发放的正式接口文档"
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AppId": {
        "type": "apiKey",
        "in": "header",
        "name": "X-STZD-AppId",
        "description": "开放平台分配的应用 ID。"
      },
      "Timestamp": {
        "type": "apiKey",
        "in": "header",
        "name": "X-STZD-Timestamp",
        "description": "毫秒级时间戳，与服务端偏差超过 5 分钟拒绝。"
      },
      "Nonce": {
        "type": "apiKey",
        "in": "header",
        "name": "X-STZD-Nonce",
        "description": "随机串，用于防重放。"
      },
      "Sign": {
        "type": "apiKey",
        "in": "header",
        "name": "X-STZD-Sign",
        "description": "HMAC-SHA256 签名：sign = HMAC_SHA256(AppSecret, AppId + Timestamp + Nonce + 请求原始Body).toUpperCase()"
      }
    }
  }
}