面向品牌商户 IT、香港供应链 / OEM 工厂与分装设备方,梳理精准营养 SaaS 的业务接口,以及分药机 / 分装设备的任务推送、回执回调与传参字段。下列路径与报文为对接原型示例,正式协议以后端交付的接口规范为准。
对接前先确认环境、鉴权方式与通用报文结构。所有业务接口通过商户端身份鉴权,供应链与设备方使用独立的对接凭证与回调签名校验。
环境区分与基础域名说明,测试环境与生产环境相互隔离,密钥不可混用。
| 配置项 | 说明 | 示例 / 占位 |
|---|---|---|
| base_url | 接口网关地址,按环境区分 | https://{gateway}.example.com/v1 |
| env | 环境标识:sandbox / production | sandbox |
| app_key | 对接方接入标识,由风浪科技分配 | merchant_xxxx |
| token | 商户端登录后换取的访问令牌,放入请求头 Authorization | Bearer {access_token} |
| sign | 供应链 / 设备回调签名,按约定算法对报文加签校验 | 见附录签名说明 |
统一响应结构:业务状态码、提示信息与数据体;分页接口返回列表与总数。
商户端账号登录换取访问令牌,后续业务接口携带令牌调用;令牌过期后通过刷新接口续期。
商户端账号密码登录,返回访问令牌与过期时间。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| account | string | 是 | 商户端账号 / 手机号 |
| password | string | 是 | 商户端登录密码(传输加密) |
| captcha | string | 否 | 图形 / 短信验证码,按风控要求启用 |
使用刷新令牌换取新的访问令牌,避免重复登录。
查询当前商户信息:品牌名称、编码、经营品类、接入状态。
查询当前角色可见的菜单与操作权限,用于商户端后台界面与接口鉴权。
问卷模板下发、作答提交、报告生成与报告查询,对应系统内 AI 测评引擎链路。
获取当前品牌启用的问卷模板:题目分组、题型、选项与跳转规则。
提交用户作答记录,写入用户健康档案,作为报告生成输入。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| user_id | string | 是 | 用户档案标识 |
| answers | array | 是 | 题目编号与作答值列表 |
| extra | object | 否 | 补充信息:体检指标、饮食习惯、生活方式等 |
基于作答与档案生成营养评估报告,返回报告编号与生成状态。
查询报告详情:风险 / 缺口标签、评估结论、建议方向与关联配方方案。
配方方案、定制组合匹配与成分库查询,支撑定制营养包的组合与组包。
查询品牌已配置的配方方案与适用人群标签。
按报告结论 / 用户标签匹配定制组合,返回建议成分、剂型与套餐 SKU。
成分库查询:成分编码、名称、规格、剂型、剂量单位与适用禁忌说明。
垂直商城的商品、购物车、下单、支付回调与订单售后链路。
商品 / 套餐列表,支持分类、标签与上下架状态筛选。
商品详情:成分明细、套餐周期、价格、规格与图文说明。
创建订单:用户、商品 / 套餐、数量、收货信息、优惠券与备注。
支付渠道异步通知,校验支付状态后更新订单;回调需验签并保证幂等。
订单列表,支持状态、时间区间与用户筛选,分页返回。
订单详情:商品明细、金额、履约状态、报关状态与物流节点。
退款 / 售后申请,按订单状态与售后规则流转。
库存查询、履约状态推送、物流节点回传与对账导出。
查询商品 / 成分库存与可售数量。
仓储 / 供应链方回传履约节点状态,系统同步订单进度。
物流节点轨迹回传:承运商、运单号、节点时间与地点。
按时间区间导出对账数据,支持订单、报关与履约维度汇总。
跨境实名采集、报文推送、状态回传与异常重推,适配进口膳食补剂的合规履约场景。
采集跨境订购人实名信息:姓名、证件类型 / 号码、手机号与收货地址。
生成并推送报关报文:订单、商品、金额、实名与监管要素,对接单一电子口岸 / 保税仓接口。
报关状态回传:申报中、放行、查验、退单等节点与回执说明。
报关失败 / 异常报文修正后重新推送,保留原始报文与重推记录。
订单生成后,系统向香港供应链 / OEM 工厂及分药机推送分装任务;设备与工厂通过回执回调回传接单、配料、称重复核与完成结果。工厂与分装设备由品牌方或其合作方提供,系统侧完成清单与数据对接,具体设备报文以实测与正式沟通为准。
支付成功,生成生产 / 分装任务
系统推送分药任务与成分明细
设备 / 工厂回执接单并配料分装
逐包称重与成分清点复核
完成状态、包数与异常回传系统
推送分药 / 分装任务。任务号作为幂等键,重复推送不重复组包。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_no | string | 是 | 分装任务号(幂等键,唯一) |
| order_no | string | 是 | 关联订单号 |
| brand_code | string | 是 | 品牌编码 |
| merchant_code | string | 是 | 商户 / OEM 工厂编码 |
| package_code | string | 是 | 套餐 / 配方编号 |
| cycle_index | int | 是 | 本次为周期第几天(如 7 / 30) |
| pack_date | string | 是 | 分装日期,YYYY-MM-DD |
| pack_count | int | 是 | 本次分装包数(每日包数) |
| recipient | object | 是 | 收件人、联系电话与收货地址 |
| items | array | 是 | 每包成分明细,见下表 |
| label | object | 否 | 袋身标签:称呼、周期天数、二维码内容、储存提示 |
| callback_url | string | 是 | 回执 / 回调地址 |
| timestamp | long | 是 | 时间戳,用于签名与防重放 |
| sign | string | 是 | 报文签名 |
items 成分明细字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| packet_no | int | 是 | 包序号(第 1 包 / 第 2 包…) |
| take_date | string | 是 | 对应服用日期 |
| ing_code | string | 是 | 成分编码 |
| ing_name | string | 是 | 成分名称 |
| dosage_form | string | 是 | 剂型:软胶囊 / 片剂 / 胶囊 / 粉剂等 |
| dose | string | 是 | 单粒 / 单次剂量与单位 |
| quantity | int | 是 | 数量(粒 / 片 / 袋) |
| spec | string | 否 | 规格与备注 |
设备 / 工厂确认接单,返回任务受理结果;拒绝接单需说明原因。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_no | string | 是 | 对应分装任务号 |
| status | string | 是 | accepted / rejected |
| reason | string | 否 | 拒绝或异常原因 |
| timestamp / sign | string | 是 | 时间戳与回调签名 |
回传配料 / 分装进度与当前环节,便于订单进度跟踪。
逐包称重复核结果:理论重量、实际重量、偏差与是否通过。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| task_no | string | 是 | 分装任务号 |
| packet_no | int | 是 | 包序号 |
| weight_expected | number | 是 | 理论重量(g) |
| weight_actual | number | 是 | 实际称重(g) |
| deviation | number | 否 | 重量偏差(g / %) |
| passed | bool | 是 | 复核是否通过 |
分装完成回传:完成包数、清点结果、出库状态与时间。
缺料、设备故障、称重超限、标签异常等告警回传,触发人工介入与任务挂起。
智能穿戴、体脂秤等健康硬件的接入预留,当前为规划方向,接口字段随设备方案细化。
用户与硬件设备绑定,同步设备型号与档案归属。
设备测量数据回传(体重、体脂、心率、睡眠等),写入健康档案并与方案联动。
通用错误码、签名约定、环境与变更记录。
| code | 含义 | 处理建议 |
|---|---|---|
| 0 | 成功 | 正常读取数据 |
| 4001 | 参数缺失或格式错误 | 核对必填字段与类型 |
| 4011 | 令牌缺失 / 过期 | 重新登录或刷新令牌 |
| 4031 | 无操作权限 | 核对商户角色与权限 |
| 4091 | 报文签名校验失败 | 核对密钥、签名算法与时间戳 |
| 4221 | 业务状态不允许操作 | 核对订单 / 任务当前状态 |
| 5000 | 系统内部错误 | 保留请求号联系技术支持 |
| 版本 | 日期 | 说明 |
|---|---|---|
| v01 | 2026-11-19 | 初版对接原型:业务接口分组与 OEM 分药机传参框架 |
需要完整接口文档、测试环境凭证或分药机 / 工厂对接评估,留下业务信息,商务与技术顾问将联系您。