> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maple.inc/llms.txt
> Use this file to discover all available pages before exploring further.

# 管理候位

> 读取散客队列、报价等待时间、添加客人组，并通知、安排入座或移除他们。

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

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

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

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

请按 [接受预订](/zh/developer-api/guides/take-bookings) 中的方式设置 `MAPLE_BASE` 和 `MAPLE_KEY`。

## 1. 读取队列

```bash theme={null}
curl "$MAPLE_BASE/locations/$LOCATION_ID/waitlist" \
  -H "Authorization: Bearer $MAPLE_KEY"
```

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

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

```bash theme={null}
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`）开启它。

```bash theme={null}
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`。见[幂等性](/zh/developer-api/concepts/idempotency)。

## 3. 通知与安排入座

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

```bash theme={null}
curl -X POST "$MAPLE_BASE/waitlist_entries/$ENTRY_ID/notify" \
  -H "Authorization: Bearer $MAPLE_KEY"
```

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

客人到达时，安排入座：

```bash theme={null}
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`。

## 保持数据最新

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.