Zebra Store 协议

两个斑马小铺之间对接时使用。它是 dujiao-next 协议的升级版，额外提供：

• 连接码：上游生成一串 zsc1_…，下游粘贴即可，不用抄地址和密钥；
• 握手：连接时自动获取对方站点名、结算货币、你的余额和支持的能力，并建议汇率和回调地址；
• 增量同步 + 实时推送：上游改价、补货、下架后几秒内通知下游，下游只拉取变化的部分；
• 报价锁价：下单前先询价并锁定价格 10 分钟，同时告诉你余额够不够；
• 多商品订单：一次采购多个商品；
• 防重复下单：每次采购带一个唯一的请求号，网络重试也不会买两次；
• 卡密加密传输：卡密用 AES-256-GCM 加密后才发给下游；
• 双密钥轮换：换密钥时新旧密钥并行 7 天，不需要两边同时停机。

下面用“A 站（上游，有货）”和“B 站（下游，要进货）”说明。两边都是斑马小铺。

第一步：在 A 站准备进货账号（B 站站长操作）

1. 打开 A 站前台，注册一个账号（这个账号代表 B 站）；
2. 个人中心 → API 对接 → 申请；
3. 等 A 站管理员审核（A 站站长在后台 对接管理 → API 凭证 点 通过）；
4. 在 A 站的 钱包 里充值（或者请 A 站站长在后台给你加款）。之后 B 站每次采购都从这里扣钱。

在 A 站申请 API 凭证

第二步：生成连接码（在 A 站）

A 站个人中心 → API 对接 → 生成连接码 → 确认 → 复制 zsc1_…。

WARNING

连接码里包含密钥，只显示一次。不要发到公开群里。忘了复制就再生成一次（旧的会在 7 天后失效）。

生成连接码

第三步：在 B 站添加连接

B 站后台 → 对接管理 → 连接管理 → 新建连接：

1. 在顶部“一键接入”框里粘贴连接码 → 解析；
2. 系统自动填好地址、Key、Secret，协议选中 Zebra Store，并立即握手。成功后显示： A 站名称、结算货币、你在 A 站的余额、支持的能力、建议汇率、建议回调地址；
3. 点建议汇率和回调地址旁边的 应用；
4. 填写 名称 和 加价百分比（例如 10），保存。

粘贴连接码并握手

保存后连接自动激活，并自动向 A 站注册推送地址（列表里“推送”一列显示 已注册）。

第四步：导入商品

B 站后台 → 对接管理 → 商品映射 → 导入商品 → 选择刚才的连接 → 勾选商品 → 选择本站分类 → 导入。

导入的商品默认下架。检查标题、图片和价格后，在 商品列表 里上架。

第五步：试一单

用一个测试账号在 B 站前台购买刚上架的商品。付款后：

1. B 站自动向 A 站询价（锁价）并下单，从 B 在 A 的余额扣款；
2. A 站发出卡密（加密），B 站解密后放进买家的订单；
3. B 站后台 采购单管理 里这一单显示 已完成。

采购单已完成

日常运行

• 价格和库存：A 站改价、补卡、下架时，几秒内推送给 B 站，B 站立即同步；即使推送失败，定时同步也会兜底；
• 余额不足：A 站会在你的余额低于阈值时推送提醒；采购时余额不够，采购单会进入“已拒绝”，充值后在采购单上点 重试；
• 价格上涨：锁价期内按锁定的价格成交；如果当前价更低，按更低的价格成交。

更换密钥

怀疑密钥泄露，或者想定期更换时：

1. 在 A 站个人中心 重新生成连接码；
2. 在 B 站编辑连接，粘贴新的连接码并保存。

旧密钥在 7 天内仍然有效；B 站第一次用新密钥成功调用后，旧密钥立即作废。 如果需要立刻让旧密钥失效，在 A 站点 重新生成 Secret（旧的立即失效），然后马上更新 B 站。

反过来：别人从你这里进货

角色互换即可：让对方在你的站点注册、申请 API 凭证，你在后台审核，然后对方生成连接码并在他的后台粘贴。

常见问题

解析连接码提示无法识别：复制不完整，连接码很长，确认末尾没有被截断。

握手失败：检查 A 站地址能否从 B 站服务器访问（curl https://A站域名/api/v1/zs/handshake 应返回 401 而不是超时）； 凭证是否已审核、已启用；两台服务器的时间是否准确（误差不能超过 5 分钟）。

推送一列显示“注册失败”：A 站访问不到 B 站的回调地址（例如 B 站在内网）。不影响使用，只是改为定时同步。