# 支持与数据完整性

> 当前的数据涵盖什么、不涵盖什么，API 如何做版本管理，以及怎样找到一个真人。

Source: https://developers.backresto.com/zh/docs/support

## 把完整性这件事直说

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

这件事比听上去更要紧：

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

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

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

## 版本管理

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

这在实践中意味着：

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

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

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

## 健康检查

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

| 端点 | 含义 |
| --- | --- |
| `GET /health/live` | 进程正在运行。 |
| `GET /health/ready` | 进程能连上它的数据库并对外提供服务。 |

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

## 获取帮助

写信到 [contact@backresto.com](mailto:contact@backresto.com)。什么能让答复来得快：

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

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

## 提更多需求

这里存在的东西之所以存在，是因为有人开口要过。加热与冷却温度、清洁计划、标签，
还有一个托管的 MCP 端点，几个月前都还在这份清单上；如今它们是
[集合](https://developers.backresto.com/zh/docs/collections)和[一个端点](https://developers.backresto.com/zh/docs/mcp)。

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

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