ConnectWiz + API 与 Webhook
已上线的集成我们卖的那套 API，就是我们自己在用的那套
整个平台由同一份 OpenAPI 契约定义，我们自己的面板和手机 App 都是从它生成的——没有影子接口，文档也不会跑偏。在它之上：带范围的 Commerce API 密钥、加固过的 Webhook 触发器，以及会回调你系统的流程。
开发者
它到底能做什么
唯一作数的那份契约
一份 OpenAPI 3 文档定义了整个平台；我们自己的 TypeScript 客户端就是从它生成的——文档不可能和现实脱节，因为现实就是按文档造出来的。
Commerce API 密钥
由租户签发、权限范围写明的密钥——商品目录读、订单读、订单写——让你自己的店面或 App 跑在同一套订单引擎上，价格始终由服务端算定。
入站 Webhook，已加固
每一个流程的 Webhook 触发器都有自己的 URL 和密钥，对原始报文体做 HMAC 校验，并带重放保护。载荷可以指名道姓提到某个人；但它绝不能左右流程的内部逻辑。
出站走流程
REST 步骤会在你在画布上画出的那个时刻回调你的系统——下单成功、拿到同意、预约成立。
技术细节
API 的设计立场，写明在此
价格绝不来自客户端
一个下单请求只说买什么、买几件——名称和价格由服务端当场从商品目录里读出来，作为快照写进订单行。被篡改的请求编不出一个折扣。
先看能力，再发调用
每一个集成面都会公布一份能力契约——能不能按手机号匹配？能不能列出访客订单？能不能创建订单？——明确写着“不能”的调用会立刻抛错，而不是在深处某个地方悄悄失败。
有意义的报错
传输层会区分“未授权”和“服务挂了”——所以“连不上商店”永远不会被显示成“这个客户从没买过东西”。有名字的错误，正是 API 和猜谜游戏之间的区别。
防重放的 Webhook
每一个入站事件在处理之前，都要先在幂等台账里占一个唯一键——重试或重放的投递在数据库层就死掉，不会跑到你的自动化里去。
密钥只存哈希，权限只给必要的
API 密钥以哈希形式存放，门口只能解析出哈希和权限范围——一行泄露的数据库记录既说不出是哪个工作区，也打不开权限范围之外的任何东西。
草稿还是确认，明着说
创建订单要带一个显式的 confirm 参数——公开 API 默认为已确认，面板里的流程可以先攒草稿——所以“这单是真的吗”是一个字段，而不是一条默契。
接入设置
连接方式
签发一个密钥
在面板里创建一个带范围的 Commerce API 密钥；吊销起来同样简单。
接上一个 Webhook
建一个以 Webhook 为触发器的流程；用它的密钥给请求签名。
再回调出去
在你的系统需要得到消息的地方，加上 REST 步骤。
搭配更好用
能与什么搭配
安全与保证
无聊但管用的保证
对原始报文体做 HMAC
Webhook 校验用每个触发器各自的密钥对原始请求体签名，并以恒定时间比对——先拿到证明，才开始解析。
载荷是数据，绝不是命令
Webhook 载荷可以引用某个人；但它绝不能左右流程的内部逻辑、改写提示词或调用工具。数据和指令之间的这道界限是架构层面的，不是靠行为约束的。
每一道门都有限流
公开接口走标准限流，读取上限由服务端强行夹住——不守规矩的客户端拖垮的是它自己，不是平台。
不加粉饰的细则
边界，写清楚
暂时还没有全量事件流
那种“订阅一切”的通用 Webhook 事件流还没做——目前的出站事件都通过流程步骤发出。写在这里，省得哪次销售电话里要含糊其辞。
读取有上限，这是设计如此
一次读取最多返回 100 行，配合游标翻页——这套 API 是为业务集成造的，不是为批量导出造的。批量需求可以聊，但不该靠钻空子。