让业务系统连接星火跃迁。

总部系统按门店授权调用 API，业务事件通过签名 Webhook 推送。

快速开始

准备已授权的商家账号和公网 HTTPS 接收地址。将下方占位符替换为你自己的网关地址、JWT、主体 ID 和 Webhook 密钥。

1. 配置接收服务。保留原始请求体，支持验签、事件幂等并返回 2xx。
2. 保存并启用配置。测试接口要求已有启用的 Webhook 配置。
3. 发送测试事件。返回 queued: true 表示入队，随后在同步日志中确认投递结果。

curl --request PUT "$API_ORIGIN/api/erp-integration" \
  --header "Authorization: Bearer $MERCHANT_JWT" \
  --header "Content-Type: application/json" \
  --data '{
    "subjectId": 42,
    "integrationType": "webhook",
    "providerName": "My ERP",
    "webhookUrl": "https://erp.example.com/webhooks/xinghuo",
    "webhookSecret": "REPLACE_WITH_YOUR_OWN_SECRET",
    "enabledEvents": ["order.created", "order.completed"],
    "syncDirection": "push",
    "status": "active"
  }'

curl --request POST "$API_ORIGIN/api/erp-integration/test" \
  --header "Authorization: Bearer $MERCHANT_JWT" \
  --header "Content-Type: application/json" \
  --data '{"subjectId":42,"eventType":"order.created"}'

选择已订阅的事件。不提供 orderNo 时发送带 testOnly:true 的联调数据，库存事件使用 inventory 结构；提供订单号仅支持订单事件，服务端检查订单所属主体。

人员职责与经营关系，分别管理

直营、加盟、合伙描述总部与门店的经营关系，不是人员角色。店长身份也不自动等于门店所有者；确认加入和授予系统 API 权限由有权代表门店的所有者完成。

配置接口携带 Authorization: Bearer <JWT>。Webhook 查询需要 settings:view 和 chain:branch:view；配置、测试和重试需要 settings:manage 和 chain:branch:manage。服务端校验当前账号和资源范围，角色名称本身不能扩权。

登录令牌仅保存在页面内存。门店加入总部、系统授权与资金安排分别确认，邀请中的分成只是合作意向。

总部系统，按门店授权调用

菜单采用“总部发布、店长选用、本店定价”。总部在商家端编辑来源门店菜品，发布适用全部门店或指定城市的模板；店长自行选择并核价上架。已有本店价格、库存和自有菜品保留。查看模板库接口与选用规则。

总管在控制台创建应用，保存仅展示一次的密钥。门店所有者登录自己的账号，核对总部与应用，选择权限及 1–365 天有效期。创建应用和确认经营关系都不会自动产生 API 授权。

门店列表与商品目录支持 afterId 游标及 limit（1–200，默认 100），返回 nextCursor；为空时表示本次列表结束。机器调用携带 X-Chain-App-Key，不要使用商家登录密码，也不要把密钥放到网址或浏览器代码中。接口每次检查应用、门店关系、授权范围及有效期，撤销应用或授权后停止访问。

curl "$API_ORIGIN/api/openapi/chain/v1/stores" \
  --header "X-Chain-App-Key: $CHAIN_APP_KEY"

店长选用模板时，保留本店已有菜品的定价、库存、上架状态和自有菜品；新菜品以库存 0、下架状态导入。总部更新不会自动覆盖分店，店长须预览版本并确认选用。

门店所有者可通过 PUT /api/chain-workspace/store-content/authorization 提交 {"authorized":false} 撤销统一内容授权：立即解除内容绑定，保留本店当前内容，并阻断总部发布与机器写入。提交 {"authorized":true} 只记录内容同意，不会恢复已停用的批量发布或机器写入。

当前可申请权限为 stores:read、catalog:read，外卖另支持 marketing:read；已停用的 content:write 不可申请。付款、分账和个人敏感资料不在应用权限范围内。

创建总部应用 · 门店授权管理 · 下载邀请与系统 API 契约 · 下载 OpenAPI 3.0 JSON

电商订单，按变化持续同步

电商总部在控制台创建应用，由门店所有者单独授予 ecommerce:orders:read。已有门店与商品授权不会自动获得订单访问权。所有接口检查应用、门店关系、经营类型和授权期限，仅返回已付款及退款后的订单，金额单位为分。

上述路径统一加前缀 /api/openapi/chain/v1/stores/{id}，携带 X-Chain-App-Key。每个应用的订单读取共享每分钟 1,200 次额度；超限返回 429 和 Retry-After，还需遵守平台网关限流。

首次接入与断点续传

1. 保存分区游标。以应用、门店、分区为键保存 64 个游标，初始均为字符串 "0"。
2. 只处理有变化的分区。先读取 sync-state，再拉取对应 changes；按订单号更新本地记录。订单版本不回退。
3. 数据和游标一起落库。处理成功后保存 nextAfterRevision；hasMore 为 true 时继续读取，失败则重试原游标。

这是订单最新状态同步，同一订单的多次变化会合并，不是支付流水或逐次事件审计；visible:false 时移除本地可操作订单。所有 ID 和版本按字符串保存，避免整数精度损失。当前订单 API 不含客户收件资料和发货写入权限，发货仍通过商家端履约模块完成；电商订单也不混入外卖 ERP Webhook。

日单量 100 万相当于平均每秒约 11.6 单，促销峰值、商品行数与库存竞争需要单独压测。使用增量分区和批量查询，避免下载全部历史订单或用页码翻到几十万页。下载接口定义与完整字段 · 下载接入与容量说明

连锁推广与活动数据

总部可向全部门店、指定城市或门店发布点击推广、满减和优惠券。店长确认费用与数据共享后参与，并保留本店自主运营能力。加入连锁不等于授权扣款。

总部系统新增只读权限 marketing:read，由门店所有者独立勾选。可查询总部计划、门店参与状态以及授权门店的推广汇总。已有商品和门店授权不会自动升级。

汇总包含获授权门店的本店与总部推广，不可当作单一总部计划的效果；所有查询按当前门店授权过滤。推广消耗、成交归因与实际结算分别核算。

下载完整 Markdown 契约与调用示例 · 下载 OpenAPI JSON · 控制台数据预览

选择接口查看请求字段。可下载接入说明，或在已部署在线契约的网关查看机器可读文档。

本页列出当前有效的接口。业务请求以 /api 开头，按文档携带对应身份凭证。

订阅业务事件

正式订单事件来自外卖与即时零售配送订单；inventory.updated 来自商家仓库库存。邮寄电商与酒店民宿的订单、售后和房态尚未接入此事件通道。保存 Webhook 或完成测试，不代表这些业务事件已经接通。

事件携带 eventId、eventType、subjectId 与 merchantId。正式订单事件还包含 externalStoreCode，可用于对齐 ERP 门店编号。

Webhook 验签

平台发送 X-Subject-Id、X-Timestamp（Unix 秒）、X-Nonce 和 X-Signature。签名结果是十六进制小写字符串。

使用原始请求体字节验签，不要先解析并重新序列化 JSON。接收方校验时间窗口、nonce 和签名后，再处理事件。

import { createHmac, timingSafeEqual } from 'node:crypto';

// rawBody 为 HTTP 接收层保留的原始 Buffer。
export function verifySignature(rawBody, headers, secret) {
  const timestamp = headers['x-timestamp'];
  const nonce = headers['x-nonce'];
  const signature = headers['x-signature'];
  if (!timestamp || !nonce || !/^[a-f0-9]{64}$/.test(signature)) {
    return false;
  }
  const expected = createHmac('sha256', secret)
    .update(`${timestamp}\n${nonce}\n`)
    .update(rawBody)
    .digest();
  return timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}

该示例仅实现签名比较。接收服务还需自行校验时间窗口、记录 nonce，并以事件 ID 做业务幂等。

投递与重试

平台等待接收方响应最多 5 秒，任意 2xx 表示投递成功。同步日志提供 syncStatus、responseStatus、retryCount 与 nextRetryAt。查询返回该主体最近 100 条记录。

修复接收方后，可通过日志 ID 重试失败投递。重试仍可能收到同一业务事件，请以 eventId 幂等处理；Webhook 返回成功前，先完成可靠落库或持久化入队。

从总部邀请到门店确认

1. 总部先认证。可独立申请，也可同时提交首店，申报规模不自动创建门店。
2. 总管创建邀请。选择直营、加盟或合伙，设置有效期、可加入数量及合作意向。
3. 门店本人确认。已有门店用自己的所有者账号确认；新门店验证负责人手机后登记，再补齐资质。
4. 分别开通能力。经营资格按审核结果开通，统一商品与装修须明确同意，系统 API 另行授权。收款与分账仍有独立流程。

直营新店可由服务端复用已审总部企业与法人资料；加盟和合伙店提交自己的主体资料。加入总部不迁移原门店的法律或结算主体。

Webhook 继续按经营主体配置接收地址与密钥，用 subjectId、merchantId 和 externalStoreCode 对齐事件；总部邀请不会自动合并各主体的事件或财务数据。

申请总部或单店 · 受邀新店登记 · 进入控制台 · 下载申请契约

当前能力与使用范围

申请、主体管理与系统连接各自校验权限。请按已开通的能力进行联调。

邀请支持外卖与电商逐店确认经营关系；新店仍需补齐资质审核。即时零售可使用已有授权门店的目录接口，当前不提供即时零售邀请登记。酒店与民宿支持申请、审核和总部目录，尚未开放总部应用密钥、房型映射、按日房态房价和预订同步。邮寄电商目前没有订单、发货、售后机器接口。仓库库存事件不等于住宿库存。

自研与委托开发资料在申请时登记并随总部资质审核；委托服务商没有独立登录身份或跨品牌权限。当前没有独立的应用审核、沙箱转生产和应用上架状态机：认证总部创建应用后，仍须由门店所有者逐店授权才能读取数据。技术测试通过不替代经营资质审核。