支持与数据完整性

把完整性这件事直说

合作方 API 开放的是在该餐厅启用这项功能之后采集的记录，每一个集合都是如此。它并不声称持有一家餐厅的完整 历史，也不会去补齐一份。收货记录是唯一的例外：它们的两个集合带着开通时应用里仍 保有的历史。

这件事比听上去更要紧：

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

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

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

版本管理

每一条路径都以 /v1 为前缀，而且这个 API 正处在封闭测试阶段。 密钥是手工 发放的，只给少数几家集成方，API 的形状也还没有定下来。这句话请照字面理解：在 /v1 之内，只要封闭测试还在继续，一个端点就可能改变形状，也可能被撤下，我们不 作相反的承诺。

这在实践中意味着：

• 请宽容地解析。 忽略你不认识的字段，而不是在它们上面失败；字段会经常增加。
• 留意已经撤销的端点。 专用的收货端点，以及打开它们照片的那个权限范围，都已经 没有了：收货记录和其他所有记录类型一样，按集合来读。见下文。
• 请让我们知道你的存在。 我们知道哪些密钥调用过我们、在什么时候调用的。如果 你那一把正在使用，我们会在动它下面的东西之前联系你，不是因为封闭测试要求我们 这么做，而是因为让一个正在运转的集成毫无预警地断掉，是一种很糟糕的做法。

等封闭测试结束，这一节会变成通常的那个承诺：一个版本之内只做增量式的改动，其余 一切都放到 /v2 后面。现在还不是这样，而把这一点说出来，对你比一个我们日后不得 不收回的保证更有用。

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

健康检查

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

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

获取帮助

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

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

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

提更多需求

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

收货记录曾是这份清单上的最后一项。 它们是这个 API 最早提供的东西，通过自己的 端点来读，有自己的形状，用的是时间区间而不是游标。如今它们是两个集合，deliveries 和 delivery-pictures，和其他所有记录类型一样，通过同一个信封、同一套分页和同一个 GET .../collections/{collection}/records 来读，而旧的端点已经撤销，没有留在旁边继续 可用。让一条记录只有一种读法，正是这次改动的意义所在。如果你之前是基于旧端点来做 的，收货记录展示了新的形状，我们也很乐意帮你迁移过来。

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