对接前必读

适用对象：本 API 的对接方（渠道商户 / 系统集成商）
文档版本：v1.0（2026-11-13）
阅读顺序：本文档（域名与公共参数）→ 接口对接指南（对接流程与接口清单）→ 接口签名鉴权说明（签名计算）

一、概述

本 API 面向贵方提供蛋糕订购能力。接入前请先了解以下三个基础约定：域名地址、请求公共参数、返回公共参数。三者是所有接口调用的共同基础，请务必在联调前完整阅读。

二、域名地址

环境	地址	说明
正式（生产）	`http://cake-api.fxzb.vip`	贵方上线时使用，以商务开通时我方提供的正式地址为准
联调（测试）	`http://dev.cake-api.fxzb.vip`	开发联调阶段使用

全部接口均通过 HTTPS 访问，路径以 /api/... 开头（如 https://open.fxzb.vip/api/goods?cityCode=330100）。

请在配置文件中将地址与环境绑定，避免联调/生产混用。

三、请求公共参数

每个请求的查询串必须携带以下 4 个公共参数：

参数	类型	必填	说明
`appId`	string	是	渠道标识（开通时由我方提供）
`timestamp`	string	是	请求时间戳（Unix 秒级），参与签名
`nonce`	string	是	随机字符串，每次请求重新生成，参与签名
`sign`	string	是	签名值，计算方式见《接口签名鉴权说明》，不参与签名

除公共参数外，各接口还有各自的业务参数（见接口文档）。

其它通用约定：

约定	说明
请求方式	GET / POST（以各接口说明为准）
POST 请求体	`Content-Type: application/json`，UTF-8 编码
GET 参数	全部走查询串
个别接口的 Header 参数	`GET /api/order/delivery_desc` 与 `GET /api/order/pick_up_store` 的 `cityCode` 需放在请求头（`Header: cityCode`），其余接口的 `cityCode` 均作为查询参数

四、返回公共参数

所有接口的响应均为统一的封装结构（HTTP 200 时）：

{
  "code": 0,
  "message": "成功",
  "data": { }
}

字段	类型	说明
`code`	int	返回码，`0` 表示成功，非 0 表示失败
`message`	string	结果描述（失败时为失败原因）
`data`	任意	业务数据，结构随接口而定；失败时一般为空

返回码（code）说明：

code	含义
0	成功
101	签名不匹配
300	参数错误（通用）
301	参数错误（提示具体字段，如 `参数(cityCode)错误：城市编码有误`）
501	内部异常
502	未处理异常
503	接口异常
其它	业务错误，请以 `message` 描述为准

data 结构：

单个对象接口：data 为对象（如商品详情）；

列表接口：data 为数组；

分页接口：data 为 { "total": 总条数, "list": [...] }（如商品搜索 GET /api/goods）。

HTTP 状态说明：

业务层面（参数错误、签名错误等）返回 HTTP 200，请以响应体中的 code 字段判断成败，不要仅凭 HTTP 状态码判断；

极少数服务端异常会返回 HTTP 500，此时响应体仍为上述统一结构，code 对应 501/502/503。

五、请求与响应示例

请求（GET，搜索杭州在售蛋糕）：

GET /api/goods?cityCode=330100&appId=100001&timestamp=1700000000&nonce=9f2c1a&sign=baf836d826a61b9faee58d820a57ba62

响应：

{
  "code": 0,
  "message": "成功",
  "data": {
    "total": 12,
    "list": [
      {
        "id": "g001",
        "name": "草莓鲜奶蛋糕",
        "salePrice": 168.0,
        "settlePrice": 118.0
      }
    ]
  }
}

请求（POST，创建订单）：请求体为 JSON，公共参数仍在查询串：

POST /api/order/create?appId=100001&timestamp=1700000000&nonce=9f2c1a&sign=0582087a8102cb2142b1924bbee5bfde
Content-Type: application/json

{ "cityCode": "330100", "count": 2 }

六、对接前检查清单

已拿到正式/联调域名地址

已拿到 appId 与 secret

已理解请求公共参数（appId / timestamp / nonce / sign）与 POST/GET 约定

已理解返回公共参数（code / message / data），并按 code 判断成败

已按《签名鉴权说明》实现签名并自测通过

已通读《接口对接指南》中本业务需要的接口

一、概述#

二、域名地址#

三、请求公共参数#

四、返回公共参数#