Ir al contenido

Locales

Tus locales: la lista de ids, el detalle de cada local y cómo cambiar su nombre, su web o sus datos de contacto.

Los endpoints de locales devuelven tus locales y te permiten cambiar el nombre, la web y los datos de contacto de un local. Para leer hace falta venues:read (la lista también funciona con metrics:read); para cambiar, venues:write.

Endpoint Ruta Permiso
Listar locales GET /v1/venues venues:read o metrics:read
Un local GET /v1/venues/{venue_id} venues:read
Cambiar un local PATCH /v1/venues/{venue_id} venues:write

En los ejemplos, $BASE es https://api.bookline.ai/v1 y $BOOKLINE_API_KEY tu clave, como en los primeros pasos.

GET /v1/venues devuelve en data[] el id y el name de los locales que lee tu clave. Usa esos ids en venue_ids en las demás rutas. Solo admite customer_id.

Ventana de terminal
curl -s -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues"

GET /v1/venues/{venue_id} devuelve el detalle de un local, con una cabecera ETag: la versión que tienes que enviar como If-Match al cambiarlo.

Ventana de terminal
curl -s -i -H "apikey: $BOOKLINE_API_KEY" "$BASE/venues/<venue_id>"
Campo Qué es
id, name El identificador y el nombre del local
type Su tipo: RESTAURANT, HOTEL, CAMPING, APARTMENTS, HOSTEL, TAXI_DISPATCHER, OTHER; pueden aparecer otros
subtype Su subtipo, si tiene
parent_venue_id El local dentro del que está este, p. ej. el restaurante de un hotel
language El idioma del local, como en el portal: SPANISH, CATALAN, ENGLISH…
currency Código ISO 4217, p. ej. EUR
timezone Zona IANA del local
country ISO 3166-1 alfa-2; null si no se conoce
city, street_address, postal_code La dirección
website La web del local
contact_details[] Formas de contactar con el local: channel (PHONE_NUMBER, WHATSAPP_BUSINESS_PHONE, EMAIL, FACEBOOK, INSTAGRAM; pueden aparecer otros) y value

Un local que no es de tu cliente, o fuera de los locales a los que está limitada tu clave, es 404 not_found.

PATCH /v1/venues/{venue_id} cambia los campos que envías y deja el resto como está. Envía al menos uno; un cuerpo vacío {} da 422 validation_failed. Envía el ETag del local como If-Match (consulta Escribir datos).

Campo Reglas
name De 1 a 200 caracteres. Un nombre nuevo sustituye también cómo lo pronuncian los agentes: configura una pronunciación propia en el portal si la necesitas
website Una URL http:// o https://, de hasta 2048 caracteres, o null para quitarla
contact_details Hasta 20 entradas de channel y value (hasta 320 caracteres). channel es PHONE_NUMBER, WHATSAPP_BUSINESS_PHONE, EMAIL, FACEBOOK o INSTAGRAM. Un teléfono tiene que ser un número válido en E.164, empezando por + y el prefijo del país, p. ej. +34600111222; un email, una dirección de email
Ventana de terminal
curl -s -X PATCH "$BASE/venues/<venue_id>" \
-H "apikey: $BOOKLINE_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "<etag>"' \
-d '{"website": "https://www.example.com", "contact_details": [{"channel": "PHONE_NUMBER", "value": "+34910000000"}, {"channel": "EMAIL", "value": "hola@example.com"}]}'

La respuesta es el local tal como queda guardado, con su nuevo ETag.

  • contact_details sustituye la lista. Las entradas que envías sustituyen todas las guardadas en los cinco canales de arriba. Las de otros canales, configuradas en el portal (p. ej. Telegram), se mantienen.
  • Devuelve lo que lees en el formato correcto. Un teléfono guardado en formato nacional o una web guardada sin https:// (posible si se configuraron en el portal) se leen tal como están guardados: al reenviarlos, escribe el teléfono en E.164 y la web con https://.
  • 409 conflict cuando la configuración del local no permite el cambio: se eliminó una integración de reservas que usa, o alguno de sus agentes necesita un teléfono o un email en los datos de contacto. Corrígelo en el portal, o mantén esa entrada en la lista.
  • Endpoints: todas las rutas, y las métricas que admiten venue_ids.
  • Escribir datos: versiones, reintentos y el límite de escritura.