> ## 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.

# Administre la lista de espera

> Lea la cola de clientes sin reserva, cotice esperas, agregue grupos y notifíquelos, siéntelos o retírelos.

La lista de espera es la cola de clientes sin reserva de un local autorizado. Usa el mismo acceso que las reservas: la **autorización de local** de su app, el lanzamiento de reservas por local y los alcances (scopes) `bookings:*`. Está disponible solo en locales nativos de Maple; un local administrado por un proveedor responde `422 capability_unsupported`.

**Maple envía todos los mensajes de texto a los huéspedes.** Notificar a un grupo envía el SMS de mesa lista de Maple e inicia la ventana de respuesta del establecimiento. Usted nunca escribe directamente a los huéspedes de la lista de espera.

| Alcance | Qué permite |
| - | - |
| `bookings:read` | Leer la cola, una entrada y los tiempos de espera estimados. |
| `bookings:write` | Agregar un grupo y cancelar una entrada en nombre del huésped. |
| `bookings:manage` | Actuar como el establecimiento: notificar, sentar y retirar grupos, y abrir o cerrar la lista de espera. |

Una app para huéspedes normalmente necesita `bookings:read` y `bookings:write`. Una app de recepción o de POS también necesita `bookings:manage`.

Defina `MAPLE_BASE` y `MAPLE_KEY` como en [Tome reservas](/es/developer-api/guides/take-bookings).

## 1. Lea la cola

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

La `waitlist` lista primero las entradas activas, en orden de fila, y `open` indica si pueden unirse grupos remotos. Cada `waitlist_entry` incluye su `position`, el `quoted_wait` que se le dio y los datos de contacto del huésped.

Para cotizar una espera antes de que un grupo se una:

```bash theme={null}
curl --get "$MAPLE_BASE/locations/$LOCATION_ID/waitlist_estimate" \
  -H "Authorization: Bearer $MAPLE_KEY" \
  --data-urlencode 'party_size=2'
```

Una espera siempre es un rango: `parties_ahead` cuenta los grupos que compiten por las mismas mesas y `wait_minutes` da un rango `min`–`max`. Los grupos de más de 50 responden `422 party_size_out_of_bounds`.

## 2. Agregue un grupo

Los grupos remotos solo pueden unirse a una lista de espera abierta. El establecimiento la abre con `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` es obligatorio: es la única forma en que Maple puede avisar al huésped que su mesa está lista. Maple lo guarda normalizado en E.164 (los números de EE. UU. pueden omitir `+1`). Un número al que Maple no puede enviar texto, como uno con extensión, responde `400`.
* Una lista de espera cerrada responde `409 waitlist_closed`.
* `idempotency_key` funciona como en las escrituras de reservas: reintente una respuesta perdida con la misma clave y el mismo cuerpo para obtener la misma entrada, incluso si la lista de espera se cerró entretanto. La clave se limita a su app en todos sus locales: la misma clave con un cuerpo distinto, o enviada a otro local, responde `409 idempotency_key_reused`. Consulte [Idempotencia](/es/developer-api/concepts/idempotency).

## 3. Notifique y siente

Cuando una mesa está por liberarse, notifique al grupo:

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

La entrada pasa a `notified`. Si el huésped no responde dentro de la ventana de respuesta del establecimiento, vence como `expired_no_response`. Notificar una entrada que ya no está en espera la devuelve sin cambios. Un local donde Maple no envía mensajes a los huéspedes responde `422 guest_messaging_unavailable`: los mensajes a huéspedes aún no están habilitados allí, o el establecimiento los desactivó. Siente o retire al grupo.

Cuando el grupo llega, siéntelo:

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

Maple sienta al grupo en la primera mesa donde quepa en este momento, igual que la recepción del establecimiento sienta a un cliente sin reserva. La entrada regresa como `seated` con un `booking_id`. Esa reserva de cliente sin reserva (`channel: walk_in`) se lee con `GET /v1/bookings/{bookingId}` y aparece en las listas de reservas como cualquier otra reserva.

* Si no hay mesa libre ahora, responde `409 slot_unavailable`; notifique o espere, y vuelva a intentar.
* Una entrada que ya salió de la cola responde `409 illegal_transition`.

## 4. Retire a un grupo de la fila

| Llamada | Alcance | Resultado |
| - | - | - |
| `POST /v1/waitlist_entries/{entryId}/cancel` | `bookings:write` | El huésped se fue: `removed_by_guest`. |
| `POST /v1/waitlist_entries/{entryId}/remove` | `bookings:manage` | El establecimiento lo retiró: `removed_by_venue`. |

Ambas devuelven la entrada. Una entrada que ya salió de la cola, ya sea sentada, retirada o vencida, se devuelve sin cambios.

`POST /v1/locations/{locationId}/waitlist/close` impide que se unan grupos remotos. Los grupos que ya esperan se quedan en la fila.

## Estados de las entradas

| Estado | Significado |
| - | - |
| `waiting` | En la fila. |
| `notified` | Maple avisó por texto al huésped que su mesa está lista. |
| `on_my_way` | Reservado para un huésped que responde que va en camino. Maple todavía no lo establece; trátelo como `notified`. |
| `seated` | Sentado; `booking_id` indica la reserva de cliente sin reserva. |
| `removed_by_guest` | El huésped salió de la cola. |
| `removed_by_venue` | El establecimiento retiró al grupo. |
| `expired_no_response` | El huésped no respondió después de ser notificado. |

`position` tiene valor mientras una entrada está activa (`waiting`, `notified`, `on_my_way`) y es `null` después.

## Manténgase al día

Suscríbase a los [eventos de lista de espera](/es/developer-api/webhook-events) (`waitlist_entry.created`, `.notified`, `.seated`, `.removed`, `.expired`) para enterarse de los cambios que hagan el establecimiento u otras apps. Cada evento incluye el estado más reciente de la entrada. Para reconciliar tras un periodo sin conexión, lea `GET /v1/locations/{locationId}/waitlist`; evite consultarlo con más frecuencia que cada 15 segundos. Las llamadas de lista de espera comparten el presupuesto de reservas de 300 solicitudes por minuto por app y entorno; consulte [Límites de frecuencia](/es/developer-api/api-reference).


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