开放接口文档

系统接口与供应链对接说明

面向品牌商户 IT、香港供应链 / OEM 工厂与分装设备方,梳理精准营养 SaaS 的业务接口,以及分药机 / 分装设备的任务推送、回执回调与传参字段。下列路径与报文为对接原型示例,正式协议以后端交付的接口规范为准。

REST / JSON 商户端鉴权 Webhook 回调 OEM 分药机对接 跨境报关链路

接入总览

对接前先确认环境、鉴权方式与通用报文结构。所有业务接口通过商户端身份鉴权,供应链与设备方使用独立的对接凭证与回调签名校验。

GET/v1/overview/env示例 · 待后端定稿

环境区分与基础域名说明,测试环境与生产环境相互隔离,密钥不可混用。

配置项说明示例 / 占位
base_url接口网关地址,按环境区分https://{gateway}.example.com/v1
env环境标识:sandbox / productionsandbox
app_key对接方接入标识,由风浪科技分配merchant_xxxx
token商户端登录后换取的访问令牌,放入请求头 AuthorizationBearer {access_token}
sign供应链 / 设备回调签名,按约定算法对报文加签校验见附录签名说明
// 通用请求头
Authorization: Bearer {access_token}
Content-Type: application/json; charset=utf-8
X-App-Key: merchant_xxxx
X-Timestamp: 1763500000
GET/v1/overview/response通用结构

统一响应结构:业务状态码、提示信息与数据体;分页接口返回列表与总数。

{
  "code": 0,
  "message": "ok",
  "data": { ... },
  "page": { "page_no": 1, "page_size": 20, "total": 128 }
}

商户与鉴权

商户端账号登录换取访问令牌,后续业务接口携带令牌调用;令牌过期后通过刷新接口续期。

POST/v1/auth/login示例

商户端账号密码登录,返回访问令牌与过期时间。

字段类型必填说明
accountstring是商户端账号 / 手机号
passwordstring是商户端登录密码(传输加密)
captchastring否图形 / 短信验证码,按风控要求启用
POST/v1/auth/refresh示例

使用刷新令牌换取新的访问令牌,避免重复登录。

GET/v1/merchant/profile示例

查询当前商户信息:品牌名称、编码、经营品类、接入状态。

GET/v1/merchant/permissions示例

查询当前角色可见的菜单与操作权限,用于商户端后台界面与接口鉴权。

问卷与测评

问卷模板下发、作答提交、报告生成与报告查询,对应系统内 AI 测评引擎链路。

GET/v1/survey/template示例

获取当前品牌启用的问卷模板:题目分组、题型、选项与跳转规则。

POST/v1/survey/submit示例

提交用户作答记录,写入用户健康档案,作为报告生成输入。

字段类型必填说明
user_idstring是用户档案标识
answersarray是题目编号与作答值列表
extraobject否补充信息:体检指标、饮食习惯、生活方式等
POST/v1/report/generate示例

基于作答与档案生成营养评估报告,返回报告编号与生成状态。

GET/v1/report/{report_id}示例

查询报告详情:风险 / 缺口标签、评估结论、建议方向与关联配方方案。

配方与套餐

配方方案、定制组合匹配与成分库查询,支撑定制营养包的组合与组包。

GET/v1/recipe/schemes示例

查询品牌已配置的配方方案与适用人群标签。

POST/v1/recipe/match示例

按报告结论 / 用户标签匹配定制组合,返回建议成分、剂型与套餐 SKU。

GET/v1/recipe/ingredients示例

成分库查询:成分编码、名称、规格、剂型、剂量单位与适用禁忌说明。

商品与订单

垂直商城的商品、购物车、下单、支付回调与订单售后链路。

GET/v1/products示例

商品 / 套餐列表,支持分类、标签与上下架状态筛选。

GET/v1/products/{sku}示例

商品详情:成分明细、套餐周期、价格、规格与图文说明。

POST/v1/orders示例

创建订单:用户、商品 / 套餐、数量、收货信息、优惠券与备注。

POST/v1/orders/pay-callback支付回调

支付渠道异步通知,校验支付状态后更新订单;回调需验签并保证幂等。

GET/v1/orders示例

订单列表,支持状态、时间区间与用户筛选,分页返回。

GET/v1/orders/{order_id}示例

订单详情:商品明细、金额、履约状态、报关状态与物流节点。

POST/v1/orders/{order_id}/refund示例

退款 / 售后申请,按订单状态与售后规则流转。

履约与库存

库存查询、履约状态推送、物流节点回传与对账导出。

GET/v1/inventory/{sku}示例

查询商品 / 成分库存与可售数量。

POST/v1/fulfillment/status状态回传

仓储 / 供应链方回传履约节点状态,系统同步订单进度。

POST/v1/logistics/track物流回传

物流节点轨迹回传:承运商、运单号、节点时间与地点。

GET/v1/settlement/export示例

按时间区间导出对账数据,支持订单、报关与履约维度汇总。

跨境报关

跨境实名采集、报文推送、状态回传与异常重推,适配进口膳食补剂的合规履约场景。

POST/v1/customs/identity示例

采集跨境订购人实名信息:姓名、证件类型 / 号码、手机号与收货地址。

POST/v1/customs/declaration报文推送

生成并推送报关报文:订单、商品、金额、实名与监管要素,对接单一电子口岸 / 保税仓接口。

POST/v1/customs/status状态回传

报关状态回传:申报中、放行、查验、退单等节点与回执说明。

POST/v1/customs/repush异常重推

报关失败 / 异常报文修正后重新推送,保留原始报文与重推记录。

供应链 / OEM 分药机对接

订单生成后,系统向香港供应链 / OEM 工厂及分药机推送分装任务;设备与工厂通过回执回调回传接单、配料、称重复核与完成结果。工厂与分装设备由品牌方或其合作方提供,系统侧完成清单与数据对接,具体设备报文以实测与正式沟通为准。

1

订单生成

支付成功,生成生产 / 分装任务

2

任务推送

系统推送分药任务与成分明细

3

接单配料

设备 / 工厂回执接单并配料分装

4

称重复核

逐包称重与成分清点复核

5

完成回传

完成状态、包数与异常回传系统

POST/v1/oem/packing-task系统 → 工厂 / 设备

推送分药 / 分装任务。任务号作为幂等键,重复推送不重复组包。

字段类型必填说明
task_nostring是分装任务号(幂等键,唯一)
order_nostring是关联订单号
brand_codestring是品牌编码
merchant_codestring是商户 / OEM 工厂编码
package_codestring是套餐 / 配方编号
cycle_indexint是本次为周期第几天(如 7 / 30)
pack_datestring是分装日期,YYYY-MM-DD
pack_countint是本次分装包数(每日包数)
recipientobject是收件人、联系电话与收货地址
itemsarray是每包成分明细,见下表
labelobject否袋身标签:称呼、周期天数、二维码内容、储存提示
callback_urlstring是回执 / 回调地址
timestamplong是时间戳,用于签名与防重放
signstring是报文签名

items 成分明细字段

字段类型必填说明
packet_noint是包序号(第 1 包 / 第 2 包…)
take_datestring是对应服用日期
ing_codestring是成分编码
ing_namestring是成分名称
dosage_formstring是剂型:软胶囊 / 片剂 / 胶囊 / 粉剂等
dosestring是单粒 / 单次剂量与单位
quantityint是数量(粒 / 片 / 袋)
specstring否规格与备注
{
  "task_no": "PT202611190001",
  "order_no": "SO202611190001",
  "brand_code": "BRAND_DEMO",
  "merchant_code": "OEM_HK_01",
  "package_code": "PKG_WEEK_07",
  "cycle_index": 7,
  "pack_date": "2026-11-19",
  "pack_count": 1,
  "recipient": { "name": "Hi Kaya", "phone": "138****0000", "address": "……" },
  "items": [
    {
      "packet_no": 1,
      "take_date": "2026-11-19",
      "ing_code": "VIT_D3",
      "ing_name": "维生素 D3",
      "dosage_form": "软胶囊",
      "dose": "1000IU",
      "quantity": 1,
      "spec": ""
    }
  ],
  "label": { "salutation": "Hi Kaya", "cycle_text": "07 / 30", "qr_content": "PT202611190001", "storage": "阴凉干燥处保存" },
  "callback_url": "https://{gateway}/v1/oem/callback",
  "timestamp": 1763500000,
  "sign": "xxxx"
}
POST/callback/oem/ack设备 → 系统 · 接单回执

设备 / 工厂确认接单,返回任务受理结果;拒绝接单需说明原因。

字段类型必填说明
task_nostring是对应分装任务号
statusstring是accepted / rejected
reasonstring否拒绝或异常原因
timestamp / signstring是时间戳与回调签名
POST/callback/oem/progress设备 → 系统 · 配料进度

回传配料 / 分装进度与当前环节,便于订单进度跟踪。

POST/callback/oem/weighing设备 → 系统 · 称重复核

逐包称重复核结果:理论重量、实际重量、偏差与是否通过。

字段类型必填说明
task_nostring是分装任务号
packet_noint是包序号
weight_expectednumber是理论重量(g)
weight_actualnumber是实际称重(g)
deviationnumber否重量偏差(g / %)
passedbool是复核是否通过
POST/callback/oem/complete设备 → 系统 · 完成回传

分装完成回传:完成包数、清点结果、出库状态与时间。

{
  "task_no": "PT202611190001",
  "order_no": "SO202611190001",
  "status": "completed",
  "pack_count": 1,
  "checked_count": 1,
  "weight_check": "passed",
  "finished_at": "2026-11-19 15:30:00",
  "remark": "",
  "timestamp": 1763500000,
  "sign": "xxxx"
}
POST/callback/oem/alert设备 → 系统 · 异常告警

缺料、设备故障、称重超限、标签异常等告警回传,触发人工介入与任务挂起。

对接约定:所有回调以任务号为幂等键,重复回调不重复更新状态;回调报文需验签,时间戳超出有效窗口视为失效;设备侧报文字段以厂家接口规范为准,必要时在上述通用字段基础上增减。

硬件设备预留

智能穿戴、体脂秤等健康硬件的接入预留,当前为规划方向,接口字段随设备方案细化。

POST/v1/device/bind规划中

用户与硬件设备绑定,同步设备型号与档案归属。

POST/v1/device/data规划中

设备测量数据回传(体重、体脂、心率、睡眠等),写入健康档案并与方案联动。

附录

通用错误码、签名约定、环境与变更记录。

GET错误码表示例
code含义处理建议
0成功正常读取数据
4001参数缺失或格式错误核对必填字段与类型
4011令牌缺失 / 过期重新登录或刷新令牌
4031无操作权限核对商户角色与权限
4091报文签名校验失败核对密钥、签名算法与时间戳
4221业务状态不允许操作核对订单 / 任务当前状态
5000系统内部错误保留请求号联系技术支持
GET签名与安全约定示例
  • · 接入凭证(app_key / secret)由风浪科技分配,仅在服务端保存,不下发到客户端。
  • · 签名基于报文参数 + 时间戳 + 密钥按约定算法生成,服务端验签通过后再处理业务。
  • · 回调接口校验来源与签名,防止伪造报文;关键写操作以业务单号做幂等控制。
  • · 传输全程使用 HTTPS,敏感信息(证件号、手机号)按合规要求脱敏存储。
GET变更记录原型 v01
版本日期说明
v012026-11-19初版对接原型:业务接口分组与 OEM 分药机传参框架
对接咨询

获取正式接口规范与对接支持

需要完整接口文档、测试环境凭证或分药机 / 工厂对接评估,留下业务信息,商务与技术顾问将联系您。

  • 商务邮箱:待确认
  • 0757-63522379 / 0757-63522380
  • 佛山 13420680555 | 广州 18529232263
原型页面:提交后不会实际发送数据,正式上线时对接线索收集与技术对接跟进。