Widgets de Solnow

Los widgets de Solnow son Web Components que podés incrustar en cualquier web externa con solo dos líneas de HTML. Funcionan con Shadow DOM (sin conflictos de CSS), se comunican con la API de Solnow, y gestionan todo el flujo de reserva de principio a fin.

Los 3 widgets disponibles

Widget	Tag HTML	Para qué sirve
Booking Engine	`<solnow-booking-engine>`	Catálogo completo de experiencias con buscador y filtros
Experience Detail	`<solnow-experience-detail>`	Vista completa de una sola experiencia (fotos, descripción, calendario, checkout)
Experience Selector	`<solnow-experience-selector>`	Widget compacto de reserva para una experiencia específica (calendario + checkout sin descripción)

Instalación básica

Cada widget tiene su propio archivo JS. Incluís el <script> antes del tag HTML del widget.

Booking Engine (catálogo completo)

html

<script src="https://app.solnow.io/widgets/solnow-booking-engine.js?organizationId=TU_ORG_ID"></script>

<solnow-booking-engine
  lang="es"
  primary-color="#0066cc"
></solnow-booking-engine>

Experience Detail (detalle de una experiencia)

html

<script src="https://app.solnow.io/widgets/solnow-experience-detail.js?organizationId=TU_ORG_ID"></script>

<!-- Por ID numérico -->
<solnow-experience-detail experience-id="42" lang="es"></solnow-experience-detail>

<!-- O por slug -->
<solnow-experience-detail slug="velero-privado-ibiza" lang="es"></solnow-experience-detail>

Experience Selector (reserva directa)

html

<script src="https://app.solnow.io/widgets/solnow-experience-selector.js?organizationId=TU_ORG_ID"></script>

<solnow-experience-selector
  experience-id="42"
  lang="es"
></solnow-experience-selector>

Configuración del script tag

El tag <script> acepta parámetros en la URL para configurar el widget:

Parámetro	Descripción	Ejemplo
`organizationId`	ID de tu organización en Solnow (recomendado)	`?organizationId=12`
`origin`	Dominio de tu web (si no usás `organizationId`)	`?origin=miempresa.com`
`apiBase`	URL base de la API (solo para desarrollo)	`?apiBase=https://api.dev.solnow.io`

Identificación automática

Si no pasás organizationId, el widget intenta identificar tu organización por el dominio de la web donde está incrustado. Ese dominio debe estar registrado en Solnow. Si tenés el mismo widget en varias webs, usá siempre organizationId para evitar ambigüedades.

Atributos de los widgets

Atributos comunes (todos los widgets)

Atributo	Tipo	Default	Descripción
`lang`	`string`	idioma del navegador	Idioma de la UI: `es`, `en`, `de`, etc.
`primary-color`	`string`	color de la marca	Color principal en hex: `#0066cc`
`background-color`	`string`	`#ffffff`	Color de fondo
`text-color`	`string`	`#111827`	Color del texto
`font-family`	`string`	sistema	Fuente: `'Inter', sans-serif`
`book-now-button-color`	`string`	igual a `primary-color`	Color del botón "Reservar ahora"
`hide-branding`	`boolean`	`false`	Oculta el logo de Solnow si es `"true"`

`<solnow-booking-engine>` — atributos adicionales

Atributo	Tipo	Descripción
`initial-experience-id`	`number`	Abre directamente el detalle de esta experiencia al cargar
`page-size`	`number`	Resultados por página (1–100, default: 20)
`transparent-bg`	`boolean`	Elimina fondo, sombra, borde y padding del widget
`hide-pagination`	`boolean`	Oculta los controles de paginación

Filtros fijos (`fixed-*`)

Estos atributos fijan un filtro que el usuario no puede cambiar desde la UI. Útil para incrustar el widget en una página específica de tu producto.

Atributo	Tipo	Descripción
`fixed-boat-types`	`string`	Tipos de embarcación separados por coma: `"velero,catamaran"`
`fixed-tags`	`string`	IDs de tags separados por coma: `"3,7,12"`
`fixed-city`	`string`	Ciudad fija: `"Ibiza"`
`fixed-manufacturer`	`string`	Fabricante fijo: `"Beneteau"`
`fixed-exclusivity-type`	`string`	`"private"` o `"shared"`
`fixed-with-captain`	`string`	`"required"`, `"optional"` o `"excluded"`
`fixed-booking-type`	`string`	`"packaged"` o `"rental"`
`fixed-min-capacity`	`number`	Capacidad mínima de pasajeros
`fixed-min-budget`	`number`	Precio mínimo en €
`fixed-max-budget`	`number`	Precio máximo en €

Ejemplo — widget que muestra solo veleros privados en Ibiza:

html

<solnow-booking-engine
  fixed-boat-types="velero"
  fixed-exclusivity-type="private"
  fixed-city="Ibiza"
  lang="es"
></solnow-booking-engine>

`<solnow-experience-detail>` — atributos adicionales

Atributo	Tipo	Descripción
`experience-id`	`number`	ID numérico de la experiencia (requerido si no usás `slug`)
`slug`	`string`	Slug URL de la experiencia (requerido si no usás `experience-id`)

`<solnow-experience-selector>` — atributos adicionales

Atributo	Tipo	Descripción
`experience-id`	`number`	ID numérico de la experiencia (obligatorio)
`fixed-booking-policy-id`	`number`	Fija la política de reserva (salida), el usuario no puede cambiarla

El objeto Webview de una experiencia

En la app de Solnow, cada experiencia tiene una sección Webview que controla cómo se muestra en los widgets y en tu web. Estos son los campos disponibles:

Campo	Descripción
`url_slug`	Identificador URL amigable de la experiencia (solo minúsculas, números y guiones). Permite referenciar la experiencia por nombre en vez de por ID numérico.
`link_to_website`	URL externa de la experiencia en tu web. Se usa para redirigir al usuario desde el catálogo.
`video`	URL de video (YouTube, Vimeo, etc.) que aparece en la vista de detalle.
`custom_html`	HTML personalizado que se renderiza al pie de la vista de detalle de la experiencia. Útil para FAQs, condiciones especiales, mapas embebidos, etc.
`widget_badge_id`	ID del badge (imagen decorativa) que aparece sobre la card en el catálogo.
`widget_badge_position`	Posición del badge: `top_left`, `top_right`, `bottom_left`, `bottom_right`.
`widget_badge_size`	Tamaño del badge: `small`, `medium`, `large`, `xlarge`.

El slug (`url_slug`)

El slug es el identificador "legible" de una experiencia. En vez de usar el ID numérico, podés referenciar la experiencia con un nombre descriptivo:

html

<!-- Con ID numérico -->
<solnow-experience-detail experience-id="42"></solnow-experience-detail>

<!-- Con slug (más legible, más estable) -->
<solnow-experience-detail slug="velero-privado-ibiza"></solnow-experience-detail>

Reglas del slug:

Solo minúsculas, números y guiones (a-z, 0-9, -)
Máximo 100 caracteres
No puede empezar ni terminar en guión
Ejemplo válido: catamaran-dia-completo-mallorca

El badge es una imagen que aparece superpuesta sobre la card de la experiencia en el catálogo (el <solnow-booking-engine>). Sirve para destacar cosas como "Más vendido", "Nuevo", "Oferta", etc.

json

"widget_config": {
  "badge": {
    "image_url": "https://cdn.solnow.io/badges/bestseller.png",
    "position": "top_right",
    "size": "medium"
  }
}

El objeto widget_config se devuelve en la respuesta de la API cuando consultás el detalle o el listado de experiencias.

El widget de Booking Engine gestiona su estado interno a través de la URL. En modo web component usa hash routing (#/?param=valor) para no interferir con la URL de tu página.

Los parámetros disponibles son:

Parámetro	Tipo	Descripción
`experienceId`	`number`	Abre directamente el detalle de esta experiencia
`view`	`string`	Vista activa: `"list"` o `"detail"`
`bookingPolicyId`	`number`	Política de reserva preseleccionada
`adults`	`number`	Número de adultos preseleccionado
`children`	`number`	Número de niños preseleccionado
`startDate`	`string`	Fecha inicio en formato `YYYY-MM-DD`
`startTime`	`string`	Hora inicio en formato `HH:mm`
`endDate`	`string`	Fecha fin en formato `YYYY-MM-DD`
`endTime`	`string`	Hora fin en formato `HH:mm`
`extraIds`	`string`	IDs de extras en CSV: `"1,2,3"`
`autoCheckout`	`boolean`	Si es `true`, va directo al checkout
`customerName`	`string`	Nombre del cliente (pre-rellena el formulario)
`customerEmail`	`string`	Email del cliente (pre-rellena el formulario)
`customerPhone`	`string`	Teléfono del cliente (pre-rellena el formulario)
`token`	`string`	Token de sesión de reserva activa
`organizationId`	`string`	Override del organization ID

Ejemplo — enlace directo a una experiencia con datos pre-cargados:

https://muweb.com/charter#/?experienceId=42&adults=4&startDate=2025-07-15&autoCheckout=true

Los widgets emiten Custom Events que podés escuchar desde tu web para reaccionar a las acciones del usuario.

javascript

const widget = document.querySelector('solnow-booking-engine')

// Usuario seleccionó una experiencia
widget.addEventListener('experience-selected', (event) => {
  console.log('Experiencia:', event.detail.experienceId, event.detail.experience)
})

// Usuario realizó una búsqueda
widget.addEventListener('search', (event) => {
  console.log('Filtros:', event.detail.filters)
  console.log('Resultados:', event.detail.total)
})

// Vista cambió (list / detail)
widget.addEventListener('view-change', (event) => {
  console.log('Vista activa:', event.detail.view)
})

// Error
widget.addEventListener('error', (event) => {
  console.error('Error en el widget:', event.detail.message)
})

Para solnow-experience-detail y solnow-experience-selector:

javascript

const widget = document.querySelector('solnow-experience-detail')

// Reserva completada
widget.addEventListener('booking-complete', (event) => {
  console.log('Datos de la reserva:', event.detail)
})

// Error de configuración
widget.addEventListener('error', (event) => {
  console.error(event.detail.message)
})

Ejemplo completo de integración

html

<!DOCTYPE html>
<html lang="es">
<head>
  <title>Mi empresa de charter</title>
</head>
<body>

  <!-- 1. Script del widget -->
  <script src="https://app.solnow.io/widgets/solnow-booking-engine.js?organizationId=12"></script>

  <!-- 2. El widget -->
  <solnow-booking-engine
    id="mi-widget"
    lang="es"
    primary-color="#1a56db"
    fixed-city="Mallorca"
    page-size="12"
  ></solnow-booking-engine>

  <!-- 3. Escuchar eventos -->
  <script>
    const widget = document.getElementById('mi-widget')
    
    widget.addEventListener('experience-selected', (e) => {
      // Por ejemplo: actualizar la URL de tu web
      history.pushState({}, '', `/barco/${e.detail.experienceId}`)
    })

    widget.addEventListener('booking-complete', (e) => {
      // Tracking, analytics, etc.
      gtag('event', 'purchase', { value: e.detail.total })
    })
  </script>

</body>
</html>

API pública — endpoints del booking engine

El widget consume estos endpoints públicos (sin autenticación). También los podés usar directamente si estás construyendo tu propia UI.

Método	Endpoint	Descripción
`GET`	`/api/website/config`	Configuración pública (form de checkout, ajustes)
`POST`	`/api/website/search`	Buscar experiencias con filtros
`GET`	`/api/website/experiences/detail?id=X`	Detalle de una experiencia por ID
`GET`	`/api/website/experiences/detail?slug=X`	Detalle de una experiencia por slug
`GET`	`/api/website/experiences/{id}/availability?year=Y&month=M`	Disponibilidad mensual de una experiencia
`GET`	`/api/website/filter-options`	Opciones de filtro disponibles (tipos de barco, tags, ciudades…)
`POST`	`/api/website/calculate-price`	Calcular precio de una reserva
`POST`	`/api/website/initiate-payment`	Iniciar el pago de una reserva
`POST`	`/api/website/booking-session`	Crear sesión de reserva
`GET`	`/api/website/booking-session?token=X`	Recuperar sesión de reserva por token

La organización se identifica por el header Origin o Referer de la petición, o pasando organization_id como query param.

Entorno de producción

La URL base de la API es: https://api.solnow.io/api

Widgets de Solnow

Los 3 widgets disponibles

Instalación básica

Booking Engine (catálogo completo)

Experience Detail (detalle de una experiencia)

Experience Selector (reserva directa)

Configuración del script tag

Atributos de los widgets

Atributos comunes (todos los widgets)

`<solnow-booking-engine>` — atributos adicionales

Filtros fijos (`fixed-*`)

`<solnow-experience-detail>` — atributos adicionales

`<solnow-experience-selector>` — atributos adicionales

El objeto Webview de una experiencia

El slug (`url_slug`)

El widget badge

Parámetros URL del widget

Eventos del widget

Ejemplo completo de integración

API pública — endpoints del booking engine

Widgets de Solnow ​

Los 3 widgets disponibles ​

Instalación básica ​

Booking Engine (catálogo completo) ​

Experience Detail (detalle de una experiencia) ​

Experience Selector (reserva directa) ​

Configuración del script tag ​

Atributos de los widgets ​

Atributos comunes (todos los widgets) ​

<solnow-booking-engine> — atributos adicionales ​

Filtros fijos (fixed-*) ​

<solnow-experience-detail> — atributos adicionales ​

<solnow-experience-selector> — atributos adicionales ​

El objeto Webview de una experiencia ​

El slug (url_slug) ​

El widget badge ​

Parámetros URL del widget ​

Eventos del widget ​

Ejemplo completo de integración ​

API pública — endpoints del booking engine ​

Widgets de Solnow

Los 3 widgets disponibles

Instalación básica

Booking Engine (catálogo completo)

Experience Detail (detalle de una experiencia)

Experience Selector (reserva directa)

Configuración del script tag

Atributos de los widgets

Atributos comunes (todos los widgets)

`<solnow-booking-engine>` — atributos adicionales

Filtros fijos (`fixed-*`)

`<solnow-experience-detail>` — atributos adicionales

`<solnow-experience-selector>` — atributos adicionales

El objeto Webview de una experiencia

El slug (`url_slug`)

El widget badge

Parámetros URL del widget

Eventos del widget

Ejemplo completo de integración

API pública — endpoints del booking engine