MAPLE_BASE con la URL base de su entorno, incluido /v1, y MAPLE_KEY con una credencial correspondiente. Consulte Entornos. Necesita bookings:read para descubrimiento y lectura, y bookings:write para retenciones y escrituras del lado del huésped.
1. Lea el perfil de reservas
enabled, provider y capabilities. Los locales nativos tienen un hold_ttl_seconds de 300 de forma predeterminada. Los locales administrados por un proveedor informan null porque el proveedor controla la expiración; use siempre el expires_at de la retención.
2. Busque disponibilidad
start y end son horas locales del establecimiento, no instantes UTC. Elija una ventana futura de no más de 31 días:
data contiene un slot_token opaco, starts_at en UTC, starts_at_local y, si aplica, la política de cancelación cotizada. Los tokens expiran a los 15 minutos. Guarde el token seleccionado sin cambios; nunca lo reconstruya a partir de la hora mostrada.
Un 422 es un resultado de negocio, no una respuesta vacía: revise code y details para ver los límites de tamaño del grupo, las restricciones de la ventana de reserva o el contacto para consultas de grupos grandes.
Experiencias
Algunos establecimientos venden experiencias: un menú fijo, una degustación, un turno con boleto. Cuando el local las ofrece (booking_profile.capabilities.experiences), la disponibilidad las lista junto con los horarios estándar, en orden de inicio. Un horario de experiencia indica su experience: id, name, description y prepayment_required. Los horarios estándar tienen experience: null.
Para mostrar los horarios de una sola experiencia, pase su id:
slot_token está vinculado a la experiencia, por lo que la retención y la reserva son para ella, y la experience de la reserva la nombra. OpenTable puede mover una reserva de experiencia a otra hora de la misma experiencia, pero no a una experiencia distinta ni a una mesa estándar: ese cambio responde 422 capability_unsupported, así que cancele y reserve el nuevo horario. Maple aún no puede cobrar pagos, por lo que retener un horario cuya experiencia tiene prepayment_required: true responde 422 payment_instrument_required. Muestre esas experiencias, pero ofrezca un horario estándar para reservar. Los locales nativos de Maple aún no ofrecen experiencias: capabilities.experiences es false y experience_id responde 422 capability_unsupported.
3. Retenga el horario
id como el ID de la retención. La retención reserva capacidad hasta expires_at; cree la reserva antes de esa hora. Si el huésped abandona el flujo, libere una retención nativa con DELETE /v1/booking_holds/{holdId}. Una retención ya consumida responde 409 hold_consumed en lugar de indicar que su capacidad fue liberada.
Cada aplicación puede tener diez retenciones activas por local, aplicado de forma atómica entre solicitudes concurrentes. Cuentan las retenciones nativas y las del proveedor, incluidas las adquisiciones del proveedor que aún esperan un resultado. Otra aplicación no puede liberar ni consumir su retención, aunque ambas tengan permiso sobre el local; esas solicitudes devuelven 404.
Si se pierde la respuesta de una retención del proveedor, la reserva de cuota tiene una cuarentena conservadora de 24 horas después del último intento posible con el proveedor. Al vencer ese plazo, deja de consumir cuota. La operación original permanece registrada y no puede reiniciarse después de su ventana de repetición; esto no resuelve una operación incierta de creación, cambio o cancelación de una reserva.
Todos los IDs de retención de socios usan bkh_…. Repetir el mismo slot_token devuelve su retención activa en lugar de adquirir otro bloqueo. La liberación en OpenTable sigue siendo una operación sin efecto: el bloqueo del proveedor y su uso de cuota permanecen hasta que expiren o se consuman. Revise booking_profile.capabilities.hold_release antes de prometer una liberación anticipada.
4. Cree la reserva
booking completo. En los locales nativos, su estado inicial es confirmed o requested, según la política de aceptación del establecimiento. Guarde su id y version. El teléfono del huésped es obligatorio; el servicio actual acepta números norteamericanos marcables.
La retención persistida aporta la cotización autoritativa tanto para las reservas nativas como para las administradas por un proveedor. Puede omitir slot_token; se sigue aceptando como campo opcional para las integraciones existentes.
5. Modifique o cancele
Para un cambio nativo, busque de nuevo conchanging_booking_id=<booking id>. Esto excluye la reserva de capacidad actual de la reserva. Envíe el token elegido a POST /v1/bookings/{id}/change, con un nuevo idempotency_key y, opcionalmente, expected_version.
Los locales administrados por un proveedor rechazan changing_booking_id con 422 capability_unsupported. Su ruta de cambio directo toma un token de una búsqueda de disponibilidad ordinaria. OpenTable admite cambios de hora o de tamaño del grupo y notes, que reemplazan la solicitud especial de la reserva. Si OpenTable no confirma la nota, el cambio devuelve 422 capability_unsupported en lugar de informar que se guardó; un cambio de hora o de tamaño del grupo enviado junto con ella podría haberse aplicado, así que vuelva a leer la reserva. OpenTable no acepta intake_answers estructuradas; devuelven 422 capability_unsupported en lugar de descartarse en silencio.
Para cambiar solo la nota del huésped, envíe notes sin slot_token. La reserva conserva su hora, tamaño de grupo y mesa, por lo que no hay cotización que tomar, y un plazo límite de reprogramación o un bloqueo posterior del día no lo impide. "" borra la nota. Un cambio de nota del lado del huésped se rechaza una vez que la reserva ya comenzó. En OpenTable, la nota es la solicitud especial de la reserva. Enviar ni slot_token ni notes responde 400 change_required.
cancelled_by_guest; una aplicación de recepción (host stand) con bookings:manage cancela por el establecimiento con POST /v1/bookings/{id}/venue_cancel (consulte Cancelar como el establecimiento). Una versión obsoleta responde 409 stale_version con details.expected y details.actual. Las escrituras respaldadas por un proveedor reclaman la reserva reflejada antes de la E/S con el proveedor; una escritura concurrente puede responder 409 operation_in_progress mientras esa reclamación esté activa. Una repetición exitosa se ejecuta antes de la verificación de versión, por lo que su expected_version original no impide la repetición.
Vuelva a leer la reserva antes de decidir si enviará un cambio distinto. Los rechazos por política de cancelación y reprogramación incluyen un reason en details. Las reclamaciones de versión serializan las escrituras a través de Maple; no bloquean los cambios hechos directamente en las herramientas propias del proveedor.
Encontrar la reserva de un huésped
Cuando un huésped llama o envía un mensaje sobre su reserva, búsquela por el teléfono con el que reservó o por el código de confirmación que recibió, en lugar de recorrer el día página por página:start/end encuentra reservas de cualquier fecha, ordenadas por inicio del horario. Devuelve recursos booking ordinarios, listos para un cambio o una cancelación. location_id es obligatorio. Consulte Listado de reservas.
En un local administrado por un proveedor (OpenTable), una búsqueda que incluye phone consulta primero al proveedor, por lo que también encuentra una reserva que el huésped hizo directamente en OpenTable. OpenTable busca las reservas solo por teléfono: una búsqueda solo con confirmation_code encuentra las reservas del proveedor que Maple ya conoce, así que incluya el teléfono cuando lo tenga.
Límites de solicitudes
Los presupuestos predeterminados por aplicación y por entorno son 60 búsquedas de disponibilidad por minuto y 300 otras solicitudes de reservas por minuto. Los presupuestos son independientes y aplican a todos los locales con permiso. Las rutas existentes de pedidos y menús no se incluyen. Un429 incluye tanto un encabezado Retry-After como retry_after en su cuerpo JSON; espere antes de reintentar. Maple puede ajustar estos presupuestos a nivel de implementación.
Siga los cambios
Suscríbase a los webhooks de reservas. UseGET /v1/bookings/{id} para el estado actual, o la lista incremental para ponerse al día después de una interrupción. Las operaciones del establecimiento y la lectura del piso en vivo se describen en Ciclo de vida de las reservas.