接口对接指南

适用对象：本 API 的对接方（渠道商户 / 系统集成商）
文档版本：v1.0（2026-11-13）
配套文档：接口签名鉴权说明

一、简介

我们提供一套蛋糕订购开放 API，贵方完成对接后，可在自有的小程序、H5 或 App 中直接售卖蛋糕：用户选好城市和商品，即可下单、支付、查询订单，并支持售后。

对接过程不涉及贵方平台改造，贵方仅需：

获取对接凭证（appId / secret）；

按本指南完成接口调用；

在正式上线前完成联调自测。

步骤	说明	产出
① 商务开通	联系商务申请蛋糕 API 权限，确认结算方式与对账周期	合同 / 开通确认
② 获取凭证	我方为贵方开通渠道账号，发放 appId（渠道标识）与 secret（签名密钥）	appId、secret（请妥善保管，勿泄露）
③ 联调准备	获取联调（测试）环境地址；按《接口签名鉴权说明》实现签名计算并自测通过	本机可正常计算合法签名
④ 全链路联调	按「四、接口调用链路」逐接口联调，核对数据、状态流转、错误处理	联调通过记录
⑤ 切换生产	将联调代码的地址与凭证切换为正式环境	正式可用的接入代码
⑥ 上线运营	关注订单履约、对账、售后处理	稳定运营

建议：联调与生产使用同一套代码，仅切换环境配置，避免两套代码带来的差异风险。

贵方用户从选城市到完成售后，完整调用顺序如下：

环节	关键接口	说明
城市	`GET /api/data/cities`	获取全部城市列表（用于贵方城市选择器）
选品	`GET /api/goods?cityCode=`	按城市搜索在售蛋糕，支持关键词/品牌/口味筛选
看商品	`GET /api/goods/{id}`	商品详情（含套餐、口味、价格、配送方式）
配送范围	`GET /api/goods/{id}/cities`	该商品支持配送/自提的城市列表（`cityCode=NATIONAL` 表示全国可售）
下单前确认	`POST /api/order/check`	验单：校验库存/配送/价格，返回每个商品的可购状态与配送费
下单	`POST /api/order/create`	创建订单，返回平台订单号
订单查询	`GET /api/order/detail?orderNo=`	订单详情（含蛋糕信息、收货地址、物流、售后单）
售后	`POST /api/cake_after_sale/apply` 等	申请售后、提交退货物流、取消售后

注意：
下单前建议先调用 check 验单，确认商品可购与配送费后再创建订单；
创建订单成功后，由贵方引导用户完成支付；双方的资金结算方式以商务约定为准；
所有业务接口均需携带签名（详见《接口签名鉴权说明》）。

接口地址：https://open.fxzb.vip（以贵方开通时我方提供的正式地址为准；联调地址另行提供）

请求方式：GET / POST（以各接口说明为准）；POST 请求体为 application/json

编码：UTF-8

公共参数（所有请求必须携带）：

响应格式（统一封装）：

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

模块	接口	说明
账号	`GET /api/channel/balance`	查询贵方渠道账户余额
基础数据	`GET /api/data/cities`	城市列表
基础数据	`GET /api/data/regions/{cityCode}`	城市下区域列表
商品	`GET /api/goods`	搜索商品（按城市、关键词、品牌、口味、配送方式）
商品	`GET /api/goods/{id}`	商品详情
商品	`GET /api/goods/{id}/cities`	商品支持城市列表
品牌	`GET /api/brand` / `GET /api/brand/all` / `GET /api/brand/{id}`	品牌列表 / 全部品牌 / 品牌详情
口味	`GET /api/flavor` / `GET /api/flavor/all` / `GET /api/flavor/{id}`	口味列表 / 全部口味 / 口味详情
订单	`POST /api/order/create`	创建订单
订单	`POST /api/order/check`	验单
订单	`GET /api/order/detail`	订单详情
订单	`GET /api/order/delivery_desc`	配送规则
订单	`GET /api/order/pick_up_store`	自提门店
售后	`GET /api/cake_after_sale/reason_list`	售后原因选项
售后	`POST /api/cake_after_sale/apply`	申请售后
售后	`POST /api/cake_after_sale/logistics`	提交退货物流
售后	`POST /api/cake_after_sale/cancel/{afterSaleNo}`	取消售后
售后	`GET /api/cake_after_sale/{afterSaleNo}`	售后详情

完整字段定义与示例，以我方提供的 Swagger 接口文档为准。

已获取 appId 与 secret，并确认二者未被泄露

已实现签名计算，并用本指南示例自测通过

联调环境完成全链路调用（城市→商品→验单→下单→订单详情→售后）

已确认订单创建、状态查询、售后申请的数据流转正确

已正确处理错误响应（code != 0），并针对 101 签名错误做好日志与告警

生产环境地址与凭证已切换，完成一次生产环境冒烟验证