支持与数据完整性

把完整性这件事直说

合作方 API 开放的是在该餐厅启用这项功能之后采集的记录——收货记录和 集合一样如此。它并不声称持有一家餐厅的完整历史，也不会去补齐 一份。

这件事比听上去更要紧：

• 一个空结果，不是什么都没发生过的证据。它可能只是意味着这家餐厅当时还没有 启用，或者某台设备还没上传。
• 来自这个 API 的一个计数不是合规数字。不要把它印在一份读起来像审计的报告上。
• 如果你需要知道一家餐厅的启用日期，问我们或者问客户。它目前没有通过 API 开放 ——如果你需要它成为一个字段，告诉我们，它就会变成一个字段。

集合在自己的响应里就把这一点说了出来：stateKind 是 received-shadow-snapshot， 意思是这个 API 收到的那个状态，而不是餐厅的应用里持有的那个状态。通常情况下两者 一致，而它们分岔的时刻，恰恰是某台设备还没上传的时候。

一家餐厅一旦启用，记录就会可靠地到达，包括那些在设备离线时采集的：它们会在设备 重新联网时上传，这也是为什么增量轮询应当有重叠，以及为什么 capturedAt 和 receivedAt 在每条记录上都有。

版本管理

每一条路径都以 /v1 为前缀。在这个版本之内，我们会：

• 往一个响应里增加字段，以及
• 增加端点和可选参数。

两者都是向后兼容的，也都不会作为破坏性变更来公告——所以请宽容地解析：忽略你不 认识的字段，而不是在它们上面失败。

在 /v1 之内，我们不会删除某个字段、不会改它的类型、不会改变某个已有字段的含义， 也不会把一个可选参数变成必填。任何非这么做不可的改动，都会以 /v2 的形式出现， 与 /v1 并存，并提前通知。

OpenAPI 文档是从正在运行的服务生成的， 所以它是对此刻部署内容的权威描述。如果本文档与那份文档说法不一致，以那份文档为 准，而我们有一个页面要修——请告诉我们。

健康检查

两个公开端点，不需要认证：

如果你要监控我们，/health/ready 是该轮询的那一个。成功的探测不会记入审计日志， 所以一个监控不会带来噪音。

获取帮助

写信到 contact@backresto.com。什么能让答复来得快：

• problem 文档里的 requestId，或者你自己发出的那个 X-Request-ID；
• 你那把密钥的公开前缀——点号前 brp_… 的那一半，绝不要发密钥串；
• 环境、端点，以及大致的时间。

绝不要把密钥串发给我们——公开前缀就能毫不含糊地标识它。如果一个密钥串去到了它不 该去的地方，请在主题行里说明并附上前缀：吊销是立即的，而它就是全部的补救。密钥 生命周期的其余部分见获取密钥。

提更多需求

这里存在的东西之所以存在，是因为有人开口要过。加热与冷却温度、清洁计划、标签， 还有一个托管的 MCP 端点，几个月前都还在这份清单上；如今它们是 集合和一个端点。

还留在清单上的是：用 webhook 取代轮询、集合上的一个增量游标、餐厅上的一个启用 日期，以及给那些不肯接受密钥的 MCP 客户端用的 OAuth 登录。下一块究竟是哪一块， 由谁开口来决定。所以，开口吧。