# 快速上手

> 从一把密钥到你的第一批记录和一张收货照片，五分钟，用 curl 完成。

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

你只需要一样东西：一把合作方密钥。它已经知道自己被授予了哪些餐厅，API 会告诉你。

## 1. 拿到一把密钥

发邮件到 [contact@backresto.com](mailto:contact@backresto.com?subject=Partner%20API%20key%20request)，
写上你的公司、你需要的餐厅和你想要的权限范围。我们与餐厅确认之后，把密钥发给你
指定的技术联系人。[获取密钥](https://developers.backresto.com/zh/docs/access) 是完整的清单。一次把它写全，是让这趟
往返只花一封邮件而不是四封的原因。

一把密钥长这样：

```
brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i
```

点号前的那一半是公开前缀：它在那个页面的密钥列表里和支持沟通中标识这把密钥，
写下来是安全的。点号后的那一半是密钥串，它只在那一个屏幕上出现过，别处都没有。

## 2. 存好它

把整个值作为一个字符串放进你的密钥管理器，然后删掉它到达时的那封邮件。绝不要放进
代码仓库，绝不要放进 URL，绝不要放进日志行。我们只保存密钥串的摘要，所以密钥一旦
丢失，就意味着一次吊销加一把新密钥。写信给我们，两件事都在当天完成。

```bash
export BACKRESTO_PARTNER_API_KEY='brp_…'
```

## 3. 找到你的餐厅

问这把密钥它能触及哪些餐厅，以及各自带有哪些权限范围：

```bash
curl "https://api.backresto.com/v1/restaurants" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"
```

```json
{
  "data": [
    {
      "restaurantId": "restaurant-1",
      "scopes": ["deliveries:read", "delivery-pictures:read", "temperature-records:read"]
    }
  ]
}
```

大多数密钥只触及一家餐厅。把它的标识符留着，下面的调用会用到：

```bash
export RESTAURANT_ID='restaurant-1'
```

## 4. 看看这把密钥打开了哪些集合

每一种记录类型，包括收货记录，都是一个[集合](https://developers.backresto.com/zh/docs/collections)。问这把密钥它能
触及哪些：

```bash
curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"
```

```json
{
  "data": [
    {
      "collection": "deliveries",
      "readScope": "deliveries:read",
      "description": "Received shadow snapshots for deliveries; not complete primary-store history.",
      "stateKind": "received-shadow-snapshot",
      "payloadVersion": 1
    }
  ]
}
```

一个空的 `data` 意味着这把密钥还没有任何集合授权。
[去申请你需要的那些](https://developers.backresto.com/zh/docs/access)。

## 5. 走一遍收货记录

一个集合用一个不透明的游标一页一页地走完。时间戳是**以字符串表示的 Unix 毫秒时间
戳**：这是整个 API 通用的约定，绝不是秒，也绝不是 ISO 8601。

```bash
curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/deliveries/records" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  --get --data-urlencode "limit=100"
```

```json
{
  "data": [
    {
      "id": "8f2c1b04-0d5a-4b7e-9f31-6ad2c0e77a51",
      "restaurantId": "restaurant-1",
      "collection": "deliveries",
      "deleted": false,
      "capturedAt": "1787932805120",
      "receivedAt": "1787932911004",
      "sequence": "88",
      "data": {
        "timestamp": "1787932800000",
        "isCompliant": false,
        "supplierDeliveriesId": "supplier-7",
        "temperatureRecords": [
          { "product": "Poulet fermier", "lotNumber": "L2291", "value": 6.4, "unit": "C" }
        ],
        "nonComplianceReasons": ["Température trop élevée"],
        "correctiveActions": ["Produit refusé"],
        "commentary": null
      }
    }
  ],
  "nextCursor": null
}
```

温度始终是摄氏度。这里没有时间区间：你走完这个集合，想要一周的话就按
`data.timestamp` 过滤，并留着 `id`，好在下一次遍历时对账。其他集合（温度、冷却、
清洁、标签）也完全按同样的方式走。

## 6. 取一次收货的照片

照片就是 `delivery-pictures` 这个集合。每条记录在 `data.deliveryId` 里点出它的收货
记录，字节内容则来自它的附件：

```bash
curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/delivery-pictures/records" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
  --get --data-urlencode "limit=100"

curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/delivery-pictures/records/$PICTURE_ID/assets" \
  -H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"
```

第二次调用返回有效期十五分钟的签名 URL；下载字节内容时不带 `Authorization` 请求头。
它需要 `delivery-pictures:read` 权限范围。如果你的密钥只有 `deliveries:read`，收货
记录会正常返回，而照片返回 `403`。这正是授权在起作用，解决办法是让客户签发一把两个
权限范围都有的密钥。

## 7. 处理你真正会遇到的那两种失败

**`404`**：这家餐厅不在你的密钥上，或者这条记录不存在。两者被有意做成无法
区分：API 不会向一个看不到某家餐厅的调用方确认它存在。

**`403`**：这家餐厅在你的密钥上，但这个端点需要的那个权限范围不在。

每一个错误都是[一份 problem 文档](https://developers.backresto.com/zh/docs/errors)，绝不会是 HTML 页面，并且带有一个
`requestId`，写信给我们时值得把它附上。

## 接下来看什么

- [获取密钥](https://developers.backresto.com/zh/docs/access)：申请清单，以及日后如何变更一把密钥。
- [认证](https://developers.backresto.com/zh/docs/authentication)：权限范围、轮换，一把密钥能做什么、不能做什么。
- [分页](https://developers.backresto.com/zh/docs/pagination)：游标，以及如何让一份副本保持最新。
- [收货记录](https://developers.backresto.com/zh/docs/deliveries)：一次收货查验及其照片的每一个字段。
- [集合与记录](https://developers.backresto.com/zh/docs/collections)：全部二十六种记录类型，以及它们共用的那个信封。
- [MCP](https://developers.backresto.com/zh/docs/mcp)：在 AI 客户端里用上同一份数据，大约三分钟。