快速上手
从一把密钥到你的第一批记录和一张收货照片，五分钟，用 curl 完成。
你只需要一样东西：一把合作方密钥。它已经知道自己被授予了哪些餐厅，API 会告诉你。
1. 拿到一把密钥
发邮件到 contact@backresto.com， 写上你的公司、你需要的餐厅和你想要的权限范围。我们与餐厅确认之后，把密钥发给你 指定的技术联系人。获取密钥 是完整的清单。一次把它写全，是让这趟 往返只花一封邮件而不是四封的原因。
一把密钥长这样：
brp_hV8kZ2pQ.tW3nR7yL9cF1sB4xJ6mA8dK0gN5vE2uP7hQ3rT1zY6i
点号前的那一半是公开前缀：它在那个页面的密钥列表里和支持沟通中标识这把密钥， 写下来是安全的。点号后的那一半是密钥串，它只在那一个屏幕上出现过，别处都没有。
2. 存好它
把整个值作为一个字符串放进你的密钥管理器，然后删掉它到达时的那封邮件。绝不要放进 代码仓库，绝不要放进 URL，绝不要放进日志行。我们只保存密钥串的摘要，所以密钥一旦 丢失，就意味着一次吊销加一把新密钥。写信给我们，两件事都在当天完成。
export BACKRESTO_PARTNER_API_KEY='brp_…'
3. 找到你的餐厅
问这把密钥它能触及哪些餐厅，以及各自带有哪些权限范围：
curl "https://api.backresto.com/v1/restaurants" \
-H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"
{
"data": [
{
"restaurantId": "restaurant-1",
"scopes": ["deliveries:read", "delivery-pictures:read", "temperature-records:read"]
}
]
}
大多数密钥只触及一家餐厅。把它的标识符留着，下面的调用会用到：
export RESTAURANT_ID='restaurant-1'
4. 看看这把密钥打开了哪些集合
每一种记录类型，包括收货记录，都是一个集合。问这把密钥它能 触及哪些：
curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections" \
-H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY"
{
"data": [
{
"collection": "deliveries",
"readScope": "deliveries:read",
"description": "Received shadow snapshots for deliveries; not complete primary-store history.",
"stateKind": "received-shadow-snapshot",
"payloadVersion": 1
}
]
}
一个空的 data 意味着这把密钥还没有任何集合授权。
去申请你需要的那些。
5. 走一遍收货记录
一个集合用一个不透明的游标一页一页地走完。时间戳是以字符串表示的 Unix 毫秒时间 戳：这是整个 API 通用的约定，绝不是秒，也绝不是 ISO 8601。
curl "https://api.backresto.com/v1/restaurants/$RESTAURANT_ID/collections/deliveries/records" \
-H "Authorization: Bearer $BACKRESTO_PARTNER_API_KEY" \
--get --data-urlencode "limit=100"
{
"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 里点出它的收货
记录，字节内容则来自它的附件：
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 文档，绝不会是 HTML 页面，并且带有一个
requestId，写信给我们时值得把它附上。