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

# Ciclo de vida de las reservas

> Estados de las reservas, permisos del invitado y del establecimiento, limitaciones de los proveedores y el plano de sala en vivo.

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

| Estado | Significado |
| - | - |
| `requested` | El establecimiento debe aceptar o rechazar la solicitud |
| `confirmed` | La reserva está aceptada |
| `seated` | El grupo está sentado |
| `completed` | El servicio terminó |
| `declined_by_venue` | El establecimiento rechazó la solicitud |
| `cancelled_by_guest` | El invitado, o un socio que actúa en su nombre, canceló |
| `cancelled_by_venue` | El establecimiento canceló |
| `cancelled_unattributed` | Un proveedor informó la cancelación sin identificar quién la hizo |
| `no_show` | El grupo no llegó |

`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:

| Sufijo del endpoint en `/v1/bookings/{id}` | Transición permitida |
| - | - |
| `/confirm` | `requested` → `confirmed` |
| `/decline` | `requested` → `declined_by_venue` |
| `/seat` | `confirmed` → `seated` |
| `/complete` | `seated` → `completed` |
| `/no_show` | `confirmed` → `no_show` |

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.

```json theme={null}
{ "expected_version": 1, "idempotency_key": "<unique cancellation key>" }
```

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"`:

```json theme={null}
{
  "party_size": 2,
  "guest": { "first_name": "Alex", "last_name": "Quinn", "phone": "+12125551234" },
  "notes": "High chair",
  "idempotency_key": "<unique walk-in key>"
}
```

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](/es/developer-api/guides/run-the-waitlist). `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](/es/developer-api/webhook-events) 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](/es/developer-api/guides/run-the-waitlist).

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


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