管理候位

候位是已授权门店的散客排队列表。它使用与预订相同的访问方式：您的应用的门店授权、按门店逐步开放的预订功能，以及 bookings:* 权限范围。它仅适用于 Maple 原生门店；由第三方管理的门店会返回 422 capability_unsupported。

所有客人短信都由 Maple 发送。 通知一组客人会发送 Maple 的“餐桌已备好”短信，并开始计算门店的响应时间窗口。您无需自己给候位客人发消息。

权限范围	允许的操作
bookings:read	读取队列、单个条目和等待时间估算。
bookings:write	添加客人组，并代客人取消条目。
bookings:manage	以门店身份操作：通知、安排入座和移除客人组，以及开启或关闭候位。

面向客人的应用通常需要 bookings:read 和 bookings:write。前台接待或 POS 应用还需要 bookings:manage。

请按 接受预订 中的方式设置 MAPLE_BASE 和 MAPLE_KEY。

1. 读取队列

curl "$MAPLE_BASE/locations/$LOCATION_ID/waitlist" \
  -H "Authorization: Bearer $MAPLE_KEY"

waitlist 按排队顺序先列出有效条目，open 表示远程客人是否可以加入。每个 waitlist_entry 带有其 position、给出的 quoted_wait，以及客人的联系方式。

在客人加入之前报价等待时间：

curl --get "$MAPLE_BASE/locations/$LOCATION_ID/waitlist_estimate" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  --data-urlencode 'party_size=2'

等待时间始终是一个区间：parties_ahead 统计争用同类餐桌的前面客人组数，wait_minutes 给出 min–max 范围。超过 50 人的组会返回 422 party_size_out_of_bounds。

2. 添加客人组

远程客人只能加入已开启的候位。门店通过 POST /v1/locations/{locationId}/waitlist/open（bookings:manage）开启它。

curl -X POST "$MAPLE_BASE/waitlist_entries" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "location_id": "'"$LOCATION_ID"'",
    "party_size": 2,
    "guest": { "first_name": "Alex", "last_name": "Quinn", "phone": "+12125551234" },
    "idempotency_key": "'"$JOIN_KEY"'"
  }'

• phone 为必填：这是 Maple 通知客人餐桌已备好的唯一途径。Maple 会将其规范化为 E.164 格式存储（美国号码可省略 +1）。Maple 无法发短信的号码（例如带分机号的号码）会返回 400。
• 候位已关闭会返回 409 waitlist_closed。
• idempotency_key 的工作方式与预订写入相同：用相同的密钥和请求体重试丢失的响应，即可得到同一个条目，即使候位此后已关闭。该密钥的范围是您的应用在其所有门店中：相同的密钥搭配不同的请求体，或发送到另一个门店，会返回 409 idempotency_key_reused。见幂等性。

3. 通知与安排入座

当一张桌子即将空出时，通知该客人组：

curl -X POST "$MAPLE_BASE/waitlist_entries/$ENTRY_ID/notify" \
  -H "Authorization: Bearer $MAPLE_KEY"

条目会变为 notified。如果客人在门店的响应时间窗口内没有回应，条目会以 expired_no_response 过期。通知一个已不在等待中的条目，会原样返回该条目。Maple 不向客人发短信的门店会返回 422 guest_messaging_unavailable：该门店尚未开通客人短信，或门店已将其关闭。请改为安排入座或移除该组客人。

客人到达时，安排入座：

curl -X POST "$MAPLE_BASE/waitlist_entries/$ENTRY_ID/seat" \
  -H "Authorization: Bearer $MAPLE_KEY"

Maple 会把这组客人安排在现在最早能容纳他们的桌位，方式与门店前台安排散客入座相同。条目返回时为 seated，并带有 booking_id。这个散客预订（channel: walk_in）可通过 GET /v1/bookings/{bookingId} 读取，并像其他预订一样出现在预订列表中。

• 现在没有空桌会返回 409 slot_unavailable；请先通知客人或再等一会儿，然后重试。
• 已经离开队列的条目会返回 409 illegal_transition。

4. 让客人组离开队列

调用	权限范围	结果
POST /v1/waitlist_entries/{entryId}/cancel	bookings:write	客人离开：removed_by_guest。
POST /v1/waitlist_entries/{entryId}/remove	bookings:manage	门店将其移除：removed_by_venue。

两者都会返回该条目。已经离开队列的条目（无论是已入座、已移除还是已过期）会原样返回。

POST /v1/locations/{locationId}/waitlist/close 会阻止远程客人加入。已在等待的客人组仍留在队列中。

条目状态

状态	含义
waiting	在排队中。
notified	Maple 已发短信告知客人餐桌已备好。
on_my_way	保留给客人回复“正在赶来”的情况。Maple 目前不会设置它；请按 notified 处理。
seated	已入座；booking_id 指向该散客预订。
removed_by_guest	客人离开了队列。
removed_by_venue	门店移除了该客人组。
expired_no_response	客人在收到通知后没有回应。

条目处于有效状态（waiting、notified、on_my_way）时会设置 position，之后为 null。

保持数据最新

订阅候位事件（waitlist_entry.created、.notified、.seated、.removed、.expired），了解门店或其他应用所做的变更。每个事件都内嵌该条目的最新状态。若要在出现间断后对账，请读取 GET /v1/locations/{locationId}/waitlist；请避免以短于 15 秒的间隔轮询。候位相关调用共享预订的额度，即每个应用和环境每分钟 300 次请求；见速率限制。