# 介绍

> BackResto 合作方 API 今天开放了什么、有意不开放什么，以及由谁来决定。

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

BackResto 是餐饮团队在营业中填写的 HACCP 合规应用：收货查验、加热与冷却温度、
清洁计划、标签。**合作方 API** 把这份记录交给你的客户已经在运行的软件，比如 ERP、
供应商门户、质量看板、AI 助手。

它是一个只读的 HTTP API，只有一种认证方式和一种错误结构，并由一份
[OpenAPI 文档](https://api.backresto.com/openapi.json) 从头到尾描述，你可以直接把它
加载进客户端生成器或 LLM 的工具定义。如果你想要的是提问而不是写一个客户端，同一份
数据也可以在 `https://api.backresto.com/mcp` 上通过 [MCP](https://developers.backresto.com/zh/docs/mcp) 拿到，用的是
同一把密钥和同样的权限。

## 由餐厅决定你能看到什么

这一段值得读两遍，因为它和你将要对接的大多数 API 都不一样。

没有自助注册。密钥由人工签发，限定到指定餐厅和指定权限范围，且只有在相关餐厅
同意之后才会签发。发邮件申请即可（[获取密钥](https://developers.backresto.com/zh/docs/access) 就是那份清单），密钥
会送到你指定的技术联系人手上。

由此带来的结果很硬：一把密钥只能触及授予它的那些餐厅，此外别无其他。
`restaurant-3` 不会因为 `restaurant-1` 和 `restaurant-2` 在同一把密钥上就冒出来，
你发得出的任何请求都无法扩大这个范围。增加一个门店是另一场对话，对话的对象是
数据的主人。

这一小步人工流程的好处在于，吊销同样直接：一封邮件，这把密钥在下一个请求时就
已经失效。

## 数据里有什么

| 资源 | 是什么 |
| --- | --- |
| [收货记录](https://developers.backresto.com/zh/docs/deliveries) | 两个集合：每次收货查验一条记录（供应商、合规判定、不合规原因、纠正措施、自由文本备注、每个产品的一条温度读数，始终以摄氏度表示），以及收货时拍下的照片。 |
| [集合与记录](https://developers.backresto.com/zh/docs/collections) | 另外二十四种记录类型，共用同一个信封，并按领域分开记录：[温度](https://developers.backresto.com/zh/docs/temperatures)、[冷却与食品处理流程](https://developers.backresto.com/zh/docs/food-processes)、[清洁](https://developers.backresto.com/zh/docs/cleaning)、[炸锅](https://developers.backresto.com/zh/docs/fryers)、[表面采样](https://developers.backresto.com/zh/docs/surface-analyses)、[追溯标签](https://developers.backresto.com/zh/docs/traceability-labels)、[文档](https://developers.backresto.com/zh/docs/drive-files)、[基础目录](https://developers.backresto.com/zh/docs/catalogue)，以及它们背后的[场所与人员](https://developers.backresto.com/zh/docs/facilities)。 |

这一切都是只读的。一把合作方密钥能调用的任何东西都不会写入餐厅的记录。合规数据
在应用里创建，由为之负责的那个人创建。

## 目前还没有的东西

把边界说清楚，能替你省下一个下午：

- **没有历史数据回填。** 一家餐厅的记录，从为这家餐厅开启采集的那一刻起才对本 API
  可见。在那之前的东西在应用里，不在这里，收货记录除外，它们带着应用里仍保有的历史。不要
  把一次空的遍历当作什么都没发生的证据。见[支持](https://developers.backresto.com/zh/docs/support)。
- **没有写入，没有 webhook。** 你靠轮询。如果你需要被推送，告诉我们；这是需求问题，
  不是原则问题。
- **集合上没有增量游标。** 刷新一个集合，意味着把它再走一遍，并按 `id` 对账。
- **暂不支持使用 BackResto 账户登录。** 伙伴密钥仍是访问凭据。Claude、ChatGPT 等
  只要求提供 URL 的 [MCP](https://developers.backresto.com/zh/docs/mcp) 客户端可以通过 OAuth 连接：在打开的 BackResto
  页面中粘贴密钥即可。访问权限仍由这把密钥决定。

## 基础 URL

| 环境 | 源地址 |
| --- | --- |
| 生产环境 | `https://api.backresto.com` |
| 预生产环境 | `https://api-preprod.backresto.com` |
| 开发环境 | `https://api-dev.backresto.com` |

一把密钥只在一个环境中开通，在其他环境里毫无意义：密钥、授权和数据都是按环境
分开的。下文的一切都使用生产环境的源地址。

准备好了？[发出你的第一个请求](https://developers.backresto.com/zh/docs/quickstart)。