Administre la lista de espera

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.

1. Lea la cola

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:

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

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.

3. Notifique y siente

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

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:

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