> ## 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. # Tomar reservas > Descubra un local, busque disponibilidad, retenga capacidad y cree o modifique una reserva. Las reservas usan los **permisos de local (location grants)** de su aplicación, no su conexión con el POS. Una integración de reservas puede convivir con otra aplicación que reciba pedidos en el mismo local. Esta función se habilita local por local; pida a Maple que active primero su local de prueba. Defina `MAPLE_BASE` con la URL base de su entorno, incluido `/v1`, y `MAPLE_KEY` con una credencial correspondiente. Consulte [Entornos](/es/developer-api/concepts/environments). 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 ```bash theme={null} curl "$MAPLE_BASE/locations/$LOCATION_ID/booking_profile" \ -H "Authorization: Bearer $MAPLE_KEY" ``` Revise `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: ```bash theme={null} curl --get "$MAPLE_BASE/locations/$LOCATION_ID/booking_availability" \ -H "Authorization: Bearer $MAPLE_KEY" \ --data-urlencode 'party_size=2' \ --data-urlencode "start=${BOOKING_DATE}T18:00" \ --data-urlencode "end=${BOOKING_DATE}T21:00" ``` Cada entrada de `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: ```bash theme={null} curl --get "$MAPLE_BASE/locations/$LOCATION_ID/booking_availability" \ -H "Authorization: Bearer $MAPLE_KEY" \ --data-urlencode 'party_size=2' \ --data-urlencode "start=${BOOKING_DATE}T18:00" \ --data-urlencode "end=${BOOKING_DATE}T21:00" \ --data-urlencode 'experience_id=1771' ``` Reserve un horario de experiencia como cualquier otro: su `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 ```http theme={null} POST /v1/booking_holds Content-Type: application/json { "slot_token": "" } ``` Guarde `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 ```http theme={null} POST /v1/bookings Content-Type: application/json { "hold_id": "", "guest": { "first_name": "Alex", "last_name": "Quinn", "phone": "+12125551234", "email": "alex@example.com" }, "notes": "Window table if possible", "idempotency_key": "" } ``` La respuesta es el recurso `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. Un tiempo de espera agotado o un `409 operation_in_progress` no significa que el proveedor haya rechazado la reserva. Reintente con la **misma clave y el mismo cuerpo**, nunca con una clave nueva. Maple registra el comando pendiente antes de la E/S con el proveedor y concilia los resultados inciertos usando la misma identidad de solicitud al proveedor. Si `details.reason` es `replay_window_expired`, detenga los reintentos automáticos y comuníquese con Maple con `details.operation_id`. Consulte [Seguridad de repetición](/es/developer-api/concepts/idempotency). ## 5. Modifique o cancele Para un cambio nativo, busque de nuevo con `changing_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`. ```http theme={null} POST /v1/bookings/{bookingId}/change Content-Type: application/json { "notes": "High chair, please", "expected_version": 1, "idempotency_key": "" } ``` ```http theme={null} POST /v1/bookings/{bookingId}/cancel Content-Type: application/json { "expected_version": 0, "idempotency_key": "" } ``` Una cancelación del socio queda como `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](/es/developer-api/concepts/booking-lifecycle)). 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: ```http theme={null} GET /v1/bookings?location_id={locationId}&phone=(415)%20555-0142 GET /v1/bookings?location_id={locationId}&confirmation_code=4815162 ``` El teléfono se normaliza antes de comparar, y una búsqueda sin `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](/es/developer-api/api-reference). 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. Un `429` 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](/es/developer-api/webhook-events). Use `GET /v1/bookings/{id}` para el estado actual, o la [lista incremental](/es/developer-api/api-reference) 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](/es/developer-api/concepts/booking-lifecycle). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.