Skip to main content
Una reserva es la mesa que se aparta para un grupo en un local. Su status registra el ciclo de vida; service_state es un detalle aparte del servicio en sala y puede ser null. Use los verbos del ciclo de vida en lugar de escribir cualquiera de los dos campos directamente.

​
Estados y permisos

bookings:write autoriza retenciones (holds), creación, cambios y la cancelación del lado del invitado. No autoriza acciones del establecimiento, cancelaciones del lado del establecimiento ni clientes sin reserva (walk-ins). Una app con bookings:read puede leer todas las reservas de los locales que se le otorgaron, no solo las que creó. Las notas internas del establecimiento nunca se incluyen.

​
Actúe en nombre del establecimiento

Estos endpoints requieren bookings:manage y un permiso sobre el local: Envíe POST con {} o { "expected_version": 3 }. Cada respuesta es la reserva completa y actualizada. Una versión obsoleta responde 409 stale_version; una transición no permitida responde 409 illegal_transition con details.from_status. La auditoría registra a la app que actúa en nombre del establecimiento en el canal api_partner. El cliente no puede elegir su propio actor ni elevar los privilegios de una solicitud con bookings:write. OpenTable no admite estas escrituras de vuelta del establecimiento. Responde 422 capability_unsupported; revise las capacidades del perfil del local antes de ofrecer una acción del establecimiento. Resy y SevenRooms no cuentan con pasarelas de reservas.

​
Cancelar como el establecimiento

POST /v1/bookings/{id}/venue_cancel (bookings:manage) cancela una reserva requested o confirmed en nombre del establecimiento y la devuelve como cancelled_by_venue; está pensado para apps de recepción (host stand) y de POS. POST /v1/bookings/{id}/cancel (bookings:write) es la cancelación del invitado y siempre termina como cancelled_by_guest, sin importar los alcances (scopes) que tenga la app.
El plazo de cancelación del invitado no se aplica al establecimiento. Una versión obsoleta responde 409 stale_version; una reserva ya sentada o terminada responde 409 not_cancellable con details.reason. La clave se limita a su app, así que un reintento después de perder la respuesta repite la cancelación. Por ahora solo para reservas nativas de Maple: las demás responden 422 capability_unsupported.

​
Sentar a un cliente sin reserva (walk-in)

POST /v1/locations/{locationId}/walk_ins (bookings:manage) sienta a un grupo que acaba de llegar y devuelve la nueva reserva con status: "seated" y channel: "walk_in":
Maple elige la primera mesa disponible en la que cabe el grupo en ese momento, igual que la recepción del propio establecimiento; no existe una reserva forzada. Cuando no hay mesa libre, la solicitud responde 409 slot_unavailable y su mensaje indica la próxima disponibilidad; agregue al grupo a la lista de espera. phone debe ser un número al que Maple pueda enviar SMS. La clave se limita a su app en todos sus locales: un reintento con la misma clave y la misma solicitud devuelve la misma reserva aunque su mesa ya esté ocupada, y la misma clave con una solicitud o un local distintos responde 409 idempotency_key_reused. Solo para locales nativos de Maple (en los demás, 422 capability_unsupported).

​
Lea el plano de sala en vivo

GET /v1/locations/{locationId}/booking_floor requiere bookings:read y solo está disponible en locales nativos de Maple habilitados que tengan geometría definida. La respuesta contiene as_of, time_zone, tables, areas y summary. Las mesas informan su estado actual (free, reserved, held, seated o maintenance), el grupo que la ocupa en current y su próxima reserva dentro de las siguientes 24 horas en next.
  • Una reserva futura no hace que la mesa esté ocupada ahora: puede estar free con un next que no es nulo.
  • current.guest contiene nombre y apellido por separado y phone_last_four, nunca el teléfono completo ni las notas del establecimiento. Siga booking_id para leer la reserva cuando lo necesite.
  • Las retenciones (holds) no tienen ID de reserva. Su booking_id es null; los ID internos de las retenciones no se exponen en el plano.
  • ends_at es null cuando un grupo sentado se pasó de su tiempo de mesa planeado; la API no promete cuándo se irá.
  • listed: false mantiene visible una mesa ocupada después de que se quitó del plano actual. Esos grupos se suman a off_plan_parties.
  • Los límites de asientos o la capacidad del área son null cuando no se conocen. El grupo de una combinación cuenta una vez en la ocupación del área, no una vez por mesa.
Consulte a pedido o sondee a intervalos de al menos 15 segundos. Use los webhooks de reservas como señal de cambio y el plano de sala como lectura de conciliación. En esta versión no hay un webhook del plano de sala. La cola de clientes sin reserva tiene sus propios endpoints; consulte Administre la lista de espera.

​
Los eventos describen cambios; las cargas útiles describen el estado al momento del envío

Cada transición de una reserva tiene su propia identidad de evento estable por app destinataria y entorno. La reserva incluida es su estado más reciente cuando el evento se registra por primera vez para ese destinatario, no una instantánea histórica de la transición. Por ejemplo, un evento booking.created retrasado puede incluir una reserva que ya está cancelada. En esta versión, previous_status es null. Elimine duplicados de las entregas por ID de evento. Concilie el estado de la reserva por id y version; no deduzca el estado histórico solo a partir del nombre del evento ni suponga un orden de entrega.