Ir al contenido

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.

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

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 que limit, incluso ninguna, y aun así tener next_cursor: sigue hasta que sea null.

El resto de esta página trata la lista de locales y las métricas.

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.

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
}
}

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.

Ventana de terminal
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.

GET /v1/metrics/summary devuelve llamadas, duración, llamantes, intenciones de reserva, transferencias, reservas, comensales, cancelaciones, visitas, valor y ROI. Para restaurantes y hoteles.

Ventana de terminal
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 en currency; cost está en cost_currency (EUR).
  • estimated_value = booking_diners × avg_ticket_price.

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.

Ventana de terminal
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_revenue está en la currency del resumen.

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:

Ventana de terminal
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_reason suma total_calls; en restaurantes solo se cuentan los tipos de intención, así que puede sumar menos.
  • by_language siempre suma el total (UNKNOWN cuando no se detectó el idioma).

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.

Ventana de terminal
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_rate va de 0 a 100, y es null si no hay reservas cumplidas.
  • No admite channels.

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:

Ventana de terminal
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=day da 400 granularity_not_supported.
  • Pagina con limit y meta.next_cursor hasta que sea null.
  • No admite channels.
  • Los días se cortan en tu zona horaria. Un día va de 00:00 a 24:00 en timezone y 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 en data.total.
  • Visitas frente a reservas. En el resumen, bookings y booking_diners cuentan las reservas hechas en el rango; visits y el endpoint de reservas cuentan las reservas cuya visita cae en el rango.
  • Dinero con venue_ids. currency, avg_ticket_price, estimated_value y recovered_revenue se calculan sobre los locales pedidos. cost, cost_currency, roi, revenue_per_euro y net_profit_per_euro son null: 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.