Pon un panel de reputación en tu propia web

Al terminar tendrás un panel de reputación en tu propia web: una nota construida con todas las OTAs en las que está tu hotel, el reparto de sentimiento que hay detrás, qué categorías se están moviendo y las reseñas — todo tras un proxy que mantiene tu API key en privado.

Qué necesitas: la API Feed · Reputation instalada y activa, el hotel dado de alta y un import terminado.

Lo que cuesta: nada por visita. Las lecturas Feed no se facturan por petición — los créditos se van en los imports que recogen los datos.

1. Prepara el hotel

Da de alta el hotel en Accommodations y mira Profiles Found: las OTAs que se detecten ahí son las que este widget puede mezclar. Un hotel con Booking, Google y Tripadvisor da un panel mucho mejor que uno solo con Google, y leerlo cuesta lo mismo.

Después ve a Reputation → Accommodations y lanza un import con todas las OTAs que quieras en la media seleccionadas, no solo una. Pon un schedule ya que estás; con una ejecución diaria el widget nunca enseña reseñas de más de 24 horas. El icono de copiar junto al hotel te da el slug con el que lo identifica la API.

2. Pide todas las OTAs de una vez

El error que conviene evitar pronto: provider es opcional tanto en reputation como en reviews. Si filtras por él te llevas una OTA. Si lo omites te las llevas todas en una sola llamada — accommodation vuelve como lista, con una entrada por OTA.

GET /v2/feed/accommodation/{slug}/reputation
GET /v2/feed/accommodation/{slug}/reviews?include_competitors=false&limit=200

Dos cosas sobre esa segunda línea:

• include_competitors viene a true por defecto. Si lo olvidas, tu propia web empieza a enseñar las reseñas de tu competencia.
• limit topa en 200. Pide 500 y recibes un 400 con el código 226. Dos ventanas de 28 días caben de sobra en las 200 reseñas más recientes.

Pruébalo en el Playground antes de escribir código. En un hotel real, la llamada de reputación respondió tres fuentes a la vez:

[
  { "provider": "booking",     "review_score": 8.5, "review_count": 2468 },
  { "provider": "google",      "review_score": 9.0, "review_count": 1691 },
  { "provider": "tripadvisor", "review_score": 8.8, "review_count": 437 }
]

3. Lo que te da la API y lo que tienes que calcular tú

Esta es la parte que decide si el panel merece la pena. La API devuelve puntuaciones, recuentos, notas por categoría y texto. No devuelve un campo de sentimiento, y no devuelve "la limpieza sube un 12 %".

Así que el widget deriva cuatro cosas, y guarda todos los umbrales en un solo fichero (insights.mjs) para que las decisiones se vean en vez de quedar enterradas:

Pondera la nota principal. En el hotel de arriba, la media simple de 8,5, 9,0 y 8,8 es 8,77. Ponderada por número de reseñas es 8,71 — Booking tiene 2.468 reseñas y merece tirar más que las 437 de Tripadvisor. Una media sin ponderar deja que una OTA con nueve reseñas grite tan alto como una con dos mil.

Protege las tendencias o te mentirán. Los dos umbrales de esa tabla salieron de datos reales, y los dos se añadieron después de ver al widget decir algo falso:

• cleanliness tenía 5 puntuaciones en la ventana actual contra 2 en la anterior. Da para escribir un "−4 %" y no da ni de lejos para sostenerlo. Un huésped tuvo una mala mañana.
• location tenía unas sanas 47 contra 23 muestras y se movió un −0,3 %. Redondeado, la tarjeta pintaba un solemne "↓0 %" — una flecha apuntando a nada, que un hotelero lee como un problema donde no lo hay.

Una categoría que no pasa alguna de las dos guardas sigue enseñando su nota. Simplemente no le crece una flecha.

Mezclar es lo que hace que las categorías valgan la pena. Los nombres llegan ya normalizados —location significa lo mismo venga de Google o de Tripadvisor— pero cada OTA expone un subconjunto distinto. Tripadvisor devuelve cleanliness, value_for_money y sleep_quality; Google devuelve service, location y rooms. Mezcladas, te quedan siete categorías donde un widget de una sola OTA tiene tres.

4. El proxy

La Connect API acepta peticiones cross-origin —devuelve access-control-allow-origin: *— así que tu página podría llamarla directamente desde el navegador. No lo hagas. La petición lleva tu veetal-api-key, y cualquiera que abra las devtools se va con ella y puede leer toda tu cuenta.

La API key no sale nunca de tu servidor. El widget habla con tu dominio; tu dominio habla con Veetal.

export async function build() {
  const [reputation, reviews] = await Promise.all([
    // Sin filtro de provider: una entrada por OTA, que es lo que convierte esto
    // de un widget de Google en un widget de reputación.
    veetalOptional(`/feed/accommodation/${SLUG}/reputation`),
    veetal(`/feed/accommodation/${SLUG}/reviews?include_competitors=false&limit=200`),
  ]);

  const own = (reputation && reputation.accommodation) || [];
  const all = reviews.reviews || [];

  const sources = own.map((entry) => ({
    provider: entry.provider,
    score: entry.review_score ?? null,
    count: entry.review_count ?? null,
  }));

  return {
    name: (own[0] && own[0].accommodation_name) || null,
    window_days: WINDOW_DAYS,
    headline: headline(sources),   // ponderada entre OTAs
    sources,
    sentiment: sentiment(all),     // todas las reseñas con nota, tengan texto o no
    categories: categories(all).slice(0, 6),
    reviews: all
      .filter((r) => r.text && r.text.trim())  // el 27 % trae nota y ningún texto
      .slice(0, 12)
      .map(toCard),
  };
}

Fíjate en qué población alimenta a qué: el sentimiento y las tendencias usan todas las reseñas con nota, incluido ese 27 % sin texto. La lista visible usa lo contrario. La misma carga, dos preguntas distintas.

El endpoint que va encima cachea quince minutos y, si un refresco falla, sirve la última carga buena — una página que funcionaba hace un minuto no puede quedarse en blanco porque haya fallado una llamada.

5. El panel

El widget se renderiza en un Shadow DOM, así que la página anfitriona no puede colarse dentro ni él puede salirse. Todo se construye con textContent, nunca con innerHTML: son textos escritos por desconocidos pintados sobre una web comercial.

La nota se lleva el espacio que merece, la línea de meta dice de qué está hecha —media, tres fuentes, 28 días— y la barra de sentimiento es una sola regla apilada en vez de una librería de gráficas. Debajo, las categorías: dos con movimiento real y cuatro enseñando su nota porque su muestra era demasiado fina para comparar. Service ↓3 % y Rooms ↓3 % son las dos únicas afirmaciones que los datos sostienen, y son las dos sobre las que un revenue manager debería actuar.

Sigue el esquema de color del sistema, y lo sigue también si el visitante lo cambia con la página abierta:

6. Empótralo

<div id="reviews"></div>

<script src="/veetal-reviews-widget.js"
        data-endpoint="/reviews-widget.json"
        data-target="#reviews"
        data-limit="5"
        data-locale="es"
        data-panel="full"
        data-theme="auto"></script>

data-panel decide cuánto se ve: full es nota + sentimiento + temas + reseñas, summary es solo el panel (va bien en una barra lateral), list son solo las reseñas. data-locale elige el idioma de las etiquetas —es o en— y formatea los números, así que la nota se lee 4,36 en español y 4.36 en inglés.

Si algo sale mal

Qué viene después

• Añade schema.org/AggregateRating para que la nota combinada salga en los propios resultados de Google.
• Sigue la nota principal en el tiempo llamando a /reputation con import_date y pinta un sparkline al lado.
• Parte la barra de sentimiento por OTA — al mismo hotel se le suele leer muy distinto en Booking y en Tripadvisor, y ese hueco es en sí mismo un hallazgo.