开放平台接口文档

对接说明

调用接口前请先了解以下通用约定，具体字段以各接口说明为准。

Long 型字段约定

• 响应中的 Long 型标识字段统一按 string 返回，避免php,js等出现精度丢失问题。
• 请求参数中的 UID、ID、lastId 等字段可直接传数字，无需转成字符串。
• 分页场景建议将上次响应中的 nextLastId 原样传入下一次请求。
• 常见字段包括：id、uid、lastId、nextLastId。

通用数据格式约定

• 请求与响应统一使用 UTF-8 编码，请求体固定为 application/json。
• 时间字段统一使用 yyyy-MM-dd HH:mm:ss，除请求头时间戳外不使用毫秒。
• 时间范围统一使用 datetimeBegin / datetimeEnd；查询区间为左闭右开，即包含开始时间、不包含结束时间。
• 金额、库存、数量等业务数字按数值类型返回，不额外转字符串。
• 涉及金额的字段统一按元处理，数据类型为 BigDecimal；除非接口字段说明中特殊标明，金额参数和返回值都表示“元”，例如 12.50 表示 12.5 元。
• 连锁门店建议统一使用总部的 appId / appKey，查哪家子门店数据，请求体就传对应门店的 account。

对接步骤

对接准备

• 先向开放平台申请 appId 与 appKey。
• 审核通过并领取 appKey 后，建议先登录控制台；首次登录会赠送 10000 Token，可直接用于接口调试。
• 根据业务场景确认本次调用对应的门店 account。
• 先阅读“对接说明”、本节与公共响应格式，再进入商品、会员、销售单据、景区票务或网单接口页面查看业务细节。

请求方式

请求头

业务门店规则

请求体必须包含 account，表示要操作哪家门店的数据。如果调用方传的是总部 appId，则可通过 account 指定子门店数据；如果传的是子门店 appId，account 应与当前门店一致。

签名规则

普通开放接口统一使用轻量签名，便于门店快速接入。

stringToSign = appId + "|" + requestId + "|" + timestamp + "|" + appKey
sign = md5(stringToSign).toUpperCase()

• appId 取请求头 X-App-Id。
• requestId 取请求头 X-Request-Id。
• timestamp 取请求头 X-Timestamp。
• 签名结果放入请求头 X-Sign。

平台校验规则

• 校验 appId 是否存在且可用。
• 校验 timestamp 是否在允许时间范围内，默认要求与平台时间相差不超过 5 分钟。
• 校验 requestId 是否重复；同一 appId 下，requestId 必须唯一。
• 校验 X-Sign 是否正确。

Java 签名示例

String appId = "yourAppId";
String requestId = "550e8400-e29b-41d4-a716-446655440000";
String timestamp = String.valueOf(System.currentTimeMillis() / 1000);
String appKey = "yourAppKey";

String raw = appId + "|" + requestId + "|" + timestamp + "|" + appKey;
String sign = md5(raw).toUpperCase();

公共响应格式

接口统一使用公司标准返回对象 cn.zdwl.base.dto.ApiResponseDTO。

通用响应外层

{
  "status": "success",
  "errorCode": 0,
  "result": {
  }
}

分页接口响应字段

以下字段仅适用于查询查询类接口，如商品、会员、销售单据的 increment-page 接口。

{
  "status": "success",
  "errorCode": 0,
  "result": {
    "list": [],
    "hasMore": true,
    "nextLastId": "123"
  }
}

失败响应

{
  "status": "error",
  "errorCode": 4004,
  "messages": [
    "签名错误"
  ]
}

计费规则

平台统一按 appId 计费。主动调用接口时，按请求头中的 X-App-Id 归集费用；接收回调通知时，按实际订阅并接收该回调的 appId 归集费用。请求体中的 account 仅用于指定目标门店，不作为计费依据。

计费归属

• OpenAPI 调用：requestAppId 传谁，就记到谁对应账户的 Token 消耗。
• 回调通知：哪个 appId 配置并订阅了回调，就记到哪个 appId 对应账户的 Token 消耗。
• 连锁总部使用总部 appId 调用或订阅时，费用归总部账户。
• 子门店如拥有独立 appId，则调用或订阅时费用归子门店自己的账户。
• 子门店如没有独立 appId，则相关费用归实际使用的上级 appId 账户。

扣费时机

联调与正式计费说明

• 首次登录赠送：首次登录开放平台控制台时，系统会自动赠送 10000 Token 到当前 appId 对应计费账户，便于完成接口联调。
• 接口调试：控制台内的接口调试属于真实 OpenAPI 调用，会进入正式链路，记录调用日志，并按标准规则计费，可优先使用首次登录赠送的 Token。
• 回调测试：控制台内的回调测试属于模拟联调能力，仅向指定回调地址发送测试消息，不进入正式回调任务队列，不计费。
• 正式回调：业务系统触发的正式回调推送会进入正式任务队列，并按订阅方 appId 计费。

计费示例

当账户欠费且超过宽限期后，平台会暂停该 appId 的正式 OpenAPI 调用与正式回调发送； 但控制台登录、充值、日志查看、回调测试等管理与排障能力不受影响，方便客户先排查再完成充值恢复服务。

费用评估

本表展示各接口单次调用的 Token 消耗。范围查询通常用于分页同步数据，精准查询通常用于按 UID、ID、编号、单号、条码等条件查询指定数据。 实际总消耗由调用次数决定，调用次数取决于客户业务数据量、同步频率和查询方式。

基础换算为 10000 Token ≈ 1 元；充值越多，赠送比例越大，实际可用 Token 会更多。以下规则用于前期报价评估，实际消耗以控制台调用日志和 Token 明细为准。

OpenAPI 调用 Token 表

回调 Token 表

正式业务回调按事件类型计费；控制台回调测试不计费。

计算规则

单次消耗 = 基础 Token + 扩展 Token
扩展 Token = 已开启扩展项数量 × 单个扩展 Token
总消耗 = 单次消耗 × 调用次数

分页查询调用次数通常 = 数据量 ÷ 单次返回上限，向上取整。

估算示例

以下示例只用于演示计算方法，不代表行业默认用量。可把门店数、商品数、单据数、扩展项和同步频率替换成自己的实际数据。

示例一：定时同步商品 查看商品接口

假设 1 家门店有 1000 个商品；每次返回商品基础数据、商品图片和扩展条码。商品分页查询接口单次最多返回 100 个商品。

单次消耗：100 + 20 + 20 = 140 Token/次
单店调用次数：1000 / 100 = 10 次
单店商品同步消耗：140 * 10 = 1400 Token，约 0.14 元

示例二：定时同步销售单据 查看销售单据接口

假设 1 家门店每天有 200 笔销售单据；按范围查询同步销售单据基础数据，并开启销售商品明细。销售单据分页查询接口单次最多返回 100 笔销售单据。

单次消耗：800 + 50 = 850 Token/次
单店调用次数：200 / 100 = 2 次
单店销售单据同步消耗：850 * 2 = 1700 Token，约 0.17 元

示例三：小程序订单推送到银豹网单 查看新增网单接口

假设客户有自己的小程序，需要把小程序订单推送到银豹收银系统，通过银豹完成接单、厨打、配送、收银等完整业务流程；小程序每天有 150 笔订单，每天调用 150 次新增网单接口。

单次消耗：200 Token/次
每日调用次数：150 次
新增网单每日消耗：150 * 200 = 30000 Token，约 3 元

示例四：实时监听门店商品库存变动 查看商品回调说明

库存每发生一次变化，就会产生一次商品变更回调。例如商品 A 库存从 80 变到 78，再变到 70，再变到 50，会产生 3 次变动。假设一家门店每天有 2000 次商品库存变动，每次商品变更回调消耗 20 Token。

单次消耗：20 Token/次
每日回调次数：2000 次
商品变更回调每日消耗：2000 * 20 = 40000 Token，约 4 元

表格中的“单次返回上限”只表示一次接口调用最多返回的数据量，不代表客户每日业务量。客户可按自己的商品数、单据数、会员数、同步频率自行代入公式估算。

常见错误码

回调说明

开放平台支持业务事件回调，客户可在控制台配置回调地址、订阅事件，并通过回调日志查看发送结果。

回调能力与配置方式

• 配置入口：登录控制台后，在“回调地址配置”中维护。
• 每条回调地址可配置 callbackUrl、callbackSecret、订阅事件。
• callbackSecret 可为空；为空时按空字符串参与签名。
• 正式业务回调按事件类型消耗 Token，按实际订阅并接收该回调的 appId 计费；控制台回调测试不计费。

当前支持的事件

回调请求方式与请求头

请求方法固定为 POST。测试回调时会额外带上 X-Test-Callback: true。

回调请求体

{
  "eventId": "evt_4f1c7d8a9b6e4b8baf6c8c3d1a2e9f10",
  "eventType": "product.change",
  "account": "store001",
  "eventTime": "2026-04-07 10:30:00",
  "data": {
    "uid": 900000001,
    "barcode": "6901234567890",
    "name": "可乐",
    "sellPrice": 3.5,
    "stock": 120,
    "enable": 1,
    "sysUpdateTime": "2026-04-07 10:30:00"
  }
}

data 字段说明

不同 eventType 的 data 字段结构不同，客户系统应按事件类型解析。

product.change 商品变更

当商品资料发生新增、修改、上下架、价格、库存等任意变更时，平台会触发 product.change 回调。

回调 data 中仅包含商品基础识别信息及部分常用字段，不代表只有这些字段变更才会回调。客户如需获取商品完整信息，请根据 data.uid 或 data.barcode 调用查询商品接口获取最新商品详情。

customer.change 会员变更

当会员资料、积分、储值、启用状态等任意变更时，平台会触发 customer.change 回调。

回调 data 中仅包含会员基础识别信息及部分常用字段，不代表只有这些字段变更才会回调。客户如需获取会员完整信息，请根据 data.uid 或 data.number 调用查询会员接口获取最新会员详情。

ticket.change 销售单据变更

当销售单新增、退款、反结账等任意变更时，平台会触发 ticket.change 回调。

回调 data 中仅包含销售单基础识别信息及部分常用字段，不代表只有这些字段变更才会回调。客户如需获取销售单完整信息，请根据 data.uid、data.sn 或 data.webOrderNo 调用查询销售单据接口获取最新单据详情。

productOrder.change 网单变更

当网单新增、修改、状态变化等任意变更时，平台会触发 productOrder.change 回调。

回调 data 中仅包含网单基础识别信息及部分常用字段，不代表只有这些字段变更才会回调。客户如需获取网单完整信息，请根据 data.orderNo 调用查询网单接口获取最新订单详情。

回调签名规则

回调签名规则与开放接口调用签名规则不同，使用回调地址配置中的 callbackSecret 参与计算。

stringToSign = callbackSecret + "|" + eventId + "|" + timestamp
sign = md5(stringToSign).toUpperCase()

• timestamp 取请求头 X-Timestamp。
• eventId 取请求头 X-Event-Id。
• callbackSecret 取客户在控制台回调配置中设置的回调密钥。
• 建议客户同时校验平台出口 IP 白名单、timestamp 有效期以及 eventId 是否重复处理。

成功判定

• 客户接口返回 HTTP 200，平台即视为回调成功。
• 非 200、超时、网络异常等，均视为回调失败。
• 当前版本不解析客户返回体内容，响应体仅用于日志记录。

重试机制

首次发送会立即执行；单个任务最大总尝试次数为 8 次，即 1 次首次发送 + 最多 7 次失败重试。

对接建议

• 建议客户回调接口先完成验签和接收，再快速返回 HTTP 200。
• 具体业务处理建议在客户系统内部异步执行，避免因耗时过长被平台判定为失败。
• 如未收到回调，请优先检查是否已配置回调地址、是否订阅了对应事件、客户接口是否正确返回 HTTP 200。