Reservas
Las reservas de tu cuenta por fecha de la reserva: quién, cuándo, para cuántos y en qué estado.
Los endpoints de reservas devuelven las reservas de tu cuenta: para cuándo es la reserva, para cuántas personas, su estado, los datos del cliente y el agente que la tomó. Necesitan el permiso bookings:read.
| Endpoint | Ruta | Permiso |
|---|---|---|
| Listar reservas | GET /v1/bookings |
bookings:read |
| Una reserva | GET /v1/bookings/{booking_id} |
bookings:read |
En los ejemplos, $BASE es https://api.bookline.ai/v1 y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.
Listar reservas
Sección titulada «Listar reservas»GET /v1/bookings devuelve las reservas cuya fecha de reserva cae en un rango de días, de la más próxima a la más lejana. El rango es sobre el momento para el que es la reserva, no sobre cuándo se hizo.
| Parámetro | Tipo | Por defecto | Reglas |
|---|---|---|---|
from |
fecha YYYY-MM-DD |
obligatorio | Primer día del rango, incluido, en timezone |
to |
fecha YYYY-MM-DD |
obligatorio | Último día, incluido; no puede ser anterior a from; 31 días como máximo |
timezone |
nombre IANA | UTC |
p. ej. Europe/Madrid; los días empiezan y terminan en esa zona |
venue_ids |
UUID, repetible | todos tus locales | 100 como máximo; solo las reservas que tomaron los agentes de esos locales |
agent_ids |
texto, repetible | todos tus agentes | 100 como máximo; solo las reservas que tomaron esos agentes |
limit |
de 1 a 100 | 50 | Reservas por página |
cursor |
texto | ninguno | meta.next_cursor de la página anterior, con los mismos filtros y el mismo limit |
customer_id |
UUID | el cliente de la clave | Consulta qué lee cada clave |
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/bookings?from=2026-11-01&to=2026-11-30&timezone=Europe/Madrid"# repite con &cursor=<meta.next_cursor> hasta que next_cursor sea null{ "data": [ { "id": "…", "status": "confirmed", "reservation_at": "2026-11-14T20:30:00Z", "diners": 4, "guest_name": "Ana García", "guest_phone": "+34600111222", "guest_email": null, "language": "SPANISH", "comments": "", "contact_id": "…", "agent_id": "…", "venue_id": "…", "created_at": "2026-11-10T11:02:44Z", "updated_at": "2026-11-10T11:02:51Z" } ], "meta": { "limit": 50, "next_cursor": "…" }}| Campo | Qué es |
|---|---|
id |
El identificador de la reserva |
status |
En qué punto está: confirmed, pending (esperando al local), pending_user_data, pending_propagation, submitted_to_backend (esperando al sistema de reservas), no_availability, propagation_failed, contacted, client_cancelled (cancelada por el cliente) o source_cancelled (cancelada por el local o su sistema de reservas); pueden aparecer otros |
reservation_at |
Para cuándo es la reserva |
diners |
Para cuántas personas es |
guest_name, guest_phone, guest_email |
El nombre, el teléfono (E.164) y el email del cliente |
language |
El idioma en que reservó el cliente: SPANISH, CATALAN, ENGLISH… |
comments |
Lo que pidió el cliente, con sus palabras. Puede contener datos de salud |
contact_id |
El contacto del cliente, si el teléfono coincide con uno |
agent_id |
El agente que la tomó; null si se hizo sin agente o la tomó un agente que no es tuyo |
venue_id |
El local de ese agente, si atiende un solo local |
created_at, updated_at |
Cuándo se hizo la reserva y cuándo cambió por última vez |
Una reserva
Sección titulada «Una reserva»GET /v1/bookings/{booking_id} devuelve los mismos campos de una reserva. Una reserva que no es de tu cliente, o fuera de los locales a los que está limitada tu clave, es 404 not_found.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/bookings/<booking_id>"Reglas de los datos
Sección titulada «Reglas de los datos»- Qué reservas son tuyas. Una reserva del libro de reservas de Bookline de tu cuenta es tuya, la tomara el agente que la tomara. Cualquier otra reserva es tuya si la tomó uno de tus agentes: la cuenta propietaria del agente cuando se hizo la reserva. Si un agente pasa a otra cuenta de Bookline, sus reservas anteriores se quedan con el propietario anterior.
agent_idyvenue_idsolo mientras el agente es tuyo. Sonnullsi el agente que tomó la reserva no es tuyo, o ya no lo es.- El rango es sobre la fecha de la reserva. Una reserva hecha hoy para el mes que viene aparece en el rango del mes que viene. Para seguir sus cambios, vuelve a leerla:
statusyupdated_atcambian con ella. - Claves limitadas a algunos locales. La clave lista solo las reservas que tomaron los agentes de esos locales, y un
venue_idsfuera de ellos da 403insufficient_scope. - Solo lectura. Las reservas no se cambian a través de la API.
Relacionado
Sección titulada «Relacionado»- Contactos: los clientes detrás de las reservas.
- Endpoints: número de reservas y comensales por día.
- Errores y límites de uso.
