Endpoints
Todas las rutas de la API de Bookline con su método y permiso, más los locales y los cinco recursos de métricas: parámetros, ejemplos de petición y qué devuelve cada uno.
Todas las rutas cuelgan de https://api.bookline.ai/v1. En los ejemplos, $BASE es esa URL y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.
Todas las rutas
Sección titulada «Todas las rutas»| Ámbito | Método y ruta | Qué hace | Permiso |
|---|---|---|---|
| Métricas | GET /v1/metrics/summary |
Las cifras principales | metrics:read |
GET /v1/metrics/conversion-funnel |
De las llamadas a las reservas confirmadas | metrics:read |
|
GET /v1/metrics/calls-breakdown |
Llamadas por motivo, idioma y país | metrics:read |
|
GET /v1/metrics/reservations |
Reservas y comensales por día de visita (restaurantes) | metrics:read |
|
GET /v1/metrics/survey-ratings |
Respuestas a encuestas, una por fila (restaurantes) | metrics:read |
|
| Locales | GET /v1/venues |
Tus locales y sus ids | venues:read o metrics:read |
GET /v1/venues/{venue_id} |
El detalle de un local | venues:read |
|
PATCH /v1/venues/{venue_id} |
Cambiar su nombre, web o datos de contacto | venues:write |
|
| Llamadas | GET /v1/calls |
Las llamadas que atendieron tus agentes en un rango | calls:read |
GET /v1/calls/{call_id} |
Una llamada con su transcripción | calls:read |
|
| Chats | GET /v1/chats |
Las conversaciones de WhatsApp iniciadas en un rango | chats:read |
GET /v1/chats/{chat_id} |
Una conversación con sus mensajes | chats:read |
|
| Reservas | GET /v1/bookings |
Las reservas cuya fecha cae en un rango | bookings:read |
GET /v1/bookings/{booking_id} |
Una reserva | bookings:read |
|
| Contactos | GET /v1/contacts |
Tus contactos | contacts:read |
GET /v1/contacts/{contact_id} |
Un contacto | contacts:read |
|
POST /v1/contacts |
Añadir un contacto | contacts:write |
|
PATCH /v1/contacts/{contact_id} |
Cambiar un contacto | contacts:write |
|
| Agentes | GET /v1/agents |
Tus agentes | bots:read |
GET /v1/agents/{agent_id} |
Un agente | bots:read |
|
PATCH /v1/agents/{agent_id} |
Cambiar el nombre de un agente | bots:write |
|
| Bases de conocimiento | GET /v1/knowledge-bases |
Tus bases de conocimiento | knowledge_bases:read |
GET /v1/knowledge-bases/{knowledge_base_id} |
Una base de conocimiento | knowledge_bases:read |
|
POST /v1/knowledge-bases |
Crear una base de conocimiento de texto | knowledge_bases:write |
|
PATCH /v1/knowledge-bases/{knowledge_base_id} |
Cambiar una base de conocimiento de texto | knowledge_bases:write |
|
DELETE /v1/knowledge-bases/{knowledge_base_id} |
Eliminar una base de conocimiento de texto | knowledge_bases:write |
|
| Campañas | GET /v1/campaigns |
Tus campañas | notifications:read |
GET /v1/campaigns/{campaign_id} |
Una campaña | notifications:read |
|
PATCH /v1/campaigns/{campaign_id} |
Pausar una campaña | notifications:write |
|
GET /v1/campaigns/{campaign_id}/runs |
Las ejecuciones de una campaña | notifications:read |
|
GET /v1/campaigns/{campaign_id}/runs/{run_id} |
Una ejecución | notifications:read |
|
| Números de teléfono | GET /v1/numbers |
Tus números de teléfono | numbers:read |
GET /v1/numbers/{number_id} |
Un número | numbers:read |
|
| Integraciones | GET /v1/integrations |
Las integraciones que instalaste | integrations:read |
GET /v1/integrations/{integration_id} |
Una integración | integrations:read |
|
| Equipo | GET /v1/users |
Tu equipo y su acceso | users:read |
GET /v1/users/{user_id} |
Un miembro del equipo | users:read |
|
PATCH /v1/users/{user_id} |
Sustituir el acceso de un miembro del equipo | users:write |
|
DELETE /v1/users/{user_id} |
Quitar a un miembro del equipo | users:write |
|
| Facturación | GET /v1/billing/accounts |
Tus cuentas de facturación | billing:read |
GET /v1/billing/accounts/{account_id} |
Una cuenta de facturación | billing:read |
|
GET /v1/billing/invoices |
Tus facturas y facturas rectificativas | billing:read |
|
GET /v1/billing/invoices/{invoice_id} |
Una factura | billing:read |
|
GET /v1/billing/services |
Los servicios que contrataste | billing:read |
La página de cada ámbito tiene sus parámetros, campos y reglas; las escrituras (POST, PATCH, DELETE) comparten las reglas de Escribir datos. La lista completa de campos, con su descripción, está en la referencia interactiva.
Listas y paginación
Sección titulada «Listas y paginación»Las listas responden {"data": [...], "meta": {"limit": ..., "next_cursor": ...}}. Para leer la página siguiente, envía meta.next_cursor como cursor, con los mismos filtros y el mismo limit; para cuando next_cursor sea null. Un cursor usado con otros filtros, otro limit u otro cliente da 400 invalid_query.
- Las listas que crecen mientras paginas (llamadas, chats, reservas, contactos, ejecuciones de campañas) nunca repiten una fila por culpa de las nuevas. Un contacto añadido mientras paginas puede quedar fuera: aparecerá en el siguiente listado.
- Las demás listas (agentes, bases de conocimiento, campañas, números, integraciones, equipo, facturación) pueden repetir una fila creada mientras paginas: quédate con una por
id. Una página puede traer menos filas quelimit, incluso ninguna, y aun así tenernext_cursor: sigue hasta que seanull.
El resto de esta página trata la lista de locales y las métricas.
Parámetros de consulta
Sección titulada «Parámetros de consulta»Toda petición de métricas necesita from y to; el resto son opcionales. Para varios valores, repite el parámetro de lista: ?venue_ids=A&venue_ids=B.
| 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 |
granularity |
total | day |
total |
day añade una fila por día; rango de 31 días como máximo (day) o 92 días (total) |
timezone |
nombre IANA | UTC |
p. ej. Europe/Madrid; su desfase con UTC debe ser de horas enteras durante todo el rango (Asia/Kolkata se rechaza) |
venue_ids |
UUID, repetible | todos tus locales | 100 como máximo; ids de GET /venues |
channels |
repetible | todos los canales | PHONE, WHATSAPP, TERMINAL, INSTAGRAM, WEB; no se admite en reservations ni en survey-ratings |
industry |
RESTAURANTS | LODGING |
deducido | Solo hace falta si el cliente tiene agentes de restaurante y de hotel |
customer_id |
UUID | el cliente de la clave | Consulta qué lee cada clave |
limit |
de 1 a 5000 | 500 | Solo survey-ratings: filas por página |
cursor |
texto | ninguno | Solo survey-ratings: meta.next_cursor de la página anterior |
Qué parámetros admite cada endpoint:
| Endpoint | Parámetros |
|---|---|
| venues | customer_id |
| summary, conversion-funnel, calls-breakdown | from, to, granularity, timezone, venue_ids, channels, industry, customer_id |
| reservations | from, to, granularity, timezone, venue_ids, industry, customer_id |
| survey-ratings | from, to, timezone, venue_ids, industry, customer_id, limit, cursor |
Un parámetro que el endpoint no admite da 400 invalid_query (por ejemplo, channels en reservations o una errata como venue_id). Los parámetros desconocidos nunca se ignoran en silencio.
Formato de las respuestas
Sección titulada «Formato de las respuestas»Las respuestas de métricas comparten el mismo formato: data.total contiene las cifras del rango, data.days una entrada por día (solo con granularity=day; si no, null) y meta describe la petición.
{ "data": { "total": { ... }, "days": [{ "date": "2026-10-01", ... }] }, "meta": { "customer_id": "...", "industry": "RESTAURANTS", "from": "2026-10-01", "to": "2026-10-31", "timezone": "Europe/Madrid", "granularity": "day", "api_version": "v1", "generated_at": "...", "next_cursor": null }}Locales
Sección titulada «Locales»GET /v1/venues devuelve en data[] el id y el name de los locales que lee tu clave. Usa esos ids en venue_ids. Solo admite customer_id.
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues"{ "data": [ { "id": "...", "name": "..." } ]}GET /v1/venues/{venue_id} devuelve el detalle de un local, y PATCH lo cambia: consulta Locales.
Resumen
Sección titulada «Resumen»GET /v1/metrics/summary devuelve llamadas, duración, llamantes, intenciones de reserva, transferencias, reservas, comensales, cancelaciones, visitas, valor y ROI. Para restaurantes y hoteles.
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/summary?from=2026-10-01&to=2026-10-31&granularity=day&timezone=Europe/Madrid"- Los campos de reservas y de dinero son solo para restaurantes.
- Los campos de valor (
estimated_value,roi, …) están encurrency;costestá encost_currency(EUR). estimated_value=booking_diners×avg_ticket_price.
Embudo de conversión
Sección titulada «Embudo de conversión»GET /v1/metrics/conversion-funnel devuelve las sesiones por etapa del embudo, los llamantes únicos, los comensales recuperados y los ingresos. Para restaurantes y hoteles.
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/conversion-funnel?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid"- Las etapas que no aplican a tu sector son
null. recovered_revenueestá en lacurrencydel resumen.
Desglose de llamadas
Sección titulada «Desglose de llamadas»GET /v1/metrics/calls-breakdown devuelve total_calls, by_reason y by_language, y by_country en el total. Para restaurantes y hoteles.
Por ejemplo, limitado a dos locales y solo a las llamadas telefónicas:
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/calls-breakdown?from=2026-10-01&to=2026-10-31&venue_ids=<venue-1>&venue_ids=<venue-2>&channels=PHONE"- En hoteles,
by_reasonsumatotal_calls; en restaurantes solo se cuentan los tipos de intención, así que puede sumar menos. by_languagesiempre suma el total (UNKNOWNcuando no se detectó el idioma).
Reservas
Sección titulada «Reservas»GET /v1/metrics/reservations devuelve las reservas y los comensales por fecha de visita, los no-shows y la tasa de no-show. Solo para restaurantes.
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/reservations?from=2026-10-01&to=2026-10-31&timezone=Europe/Madrid"- Cuenta las reservas aún válidas en el TPV cuya visita cae en el rango, no las reservas hechas en él.
no_show_rateva de 0 a 100, y esnullsi no hay reservas cumplidas.- No admite
channels.
Valoraciones de encuestas
Sección titulada «Valoraciones de encuestas»GET /v1/metrics/survey-ratings devuelve en data.rows[] cada respuesta a la encuesta posterior a la visita, de la más reciente a la más antigua, con rated_at, phone, score, min_score, max_score, bot_id y venue_id. Solo para restaurantes.
Recorre las valoraciones página a página:
curl -s -H "apikey: $BOOKLINE_API_KEY" \ "$BASE/metrics/survey-ratings?from=2026-10-01&to=2026-10-31&limit=500"# repite con &cursor=<meta.next_cursor> hasta que next_cursor sea null- Solo
granularity=total;granularity=dayda 400granularity_not_supported. - Pagina con
limitymeta.next_cursorhasta que seanull. - No admite
channels.
Reglas de los datos
Sección titulada «Reglas de los datos»- Los días se cortan en tu zona horaria. Un día va de 00:00 a 24:00 en
timezoney se construye con datos por horas; por eso la zona necesita un desfase de horas enteras. Los días sin actividad se devuelven a cero. - Totales frente a días.
days[]solo lleva los campos que se pueden sumar entre días. Las cifras que no se suman, como los llamantes distintos, los llamantes únicos,by_country, las visitas, los no-shows y todos los campos de dinero, solo aparecen endata.total. - Visitas frente a reservas. En el resumen,
bookingsybooking_dinerscuentan las reservas hechas en el rango;visitsy el endpoint de reservas cuentan las reservas cuya visita cae en el rango. - Dinero con
venue_ids.currency,avg_ticket_price,estimated_valueyrecovered_revenuese calculan sobre los locales pedidos.cost,cost_currency,roi,revenue_per_euroynet_profit_per_eurosonnull: el coste de la suscripción es de toda la cuenta, no de un local. - Agentes que pasaron a tu cuenta. Si uno de tus agentes perteneció antes a otro cliente de Bookline, solo cuenta desde la hora en que pasó a ti (redondeada a la siguiente hora en punto, UTC). Nunca se devuelve nada de lo que hizo para el propietario anterior. Si todos los agentes llegaron después de tu rango, la API responde 404 con
available_from, la primera fecha con datos. - API frente a dashboard. La API usa las mismas métricas que el dashboard del portal, así que las cifras coinciden para el mismo rango y los mismos filtros. La única diferencia: el dashboard sigue mostrando todo el historial de un agente que cambió de cuenta.
