API de comprobación de precios
Lee desde tu chatbot el veredicto tras el widget de StayParity de un hotel: un GET, el precio en su web y las OTAs que iguala o mejora, nunca una disparidad.
La API de comprobación de precios responde a una pregunta para una noche: ¿cuánto cobra la web del propio hotel y es ese el mejor precio disponible? Lee los mismos datos que el widget de la web del hotel, para que también pueda citarla un bot de WhatsApp, un asistente de chat o un widget que desarrolles tú mismo. Informa del veredicto que encontró la revisión. El sello Best price here del widget es una afirmación del propio hotel, aparece con cada veredicto y no forma parte de la respuesta.
No necesita cuenta ni token de API, solo la clave del hotel, y no dice nada que un visitante de la web del hotel no pudiera ver. Cuando una OTA vende la noche por menos, da solo el precio del hotel, exactamente igual que para una noche que ninguna OTA vende, así que nadie, tampoco tú, puede deducir de su respuesta que hay una disparidad.
Solicitud
Un GET con tres parámetros de consulta:
GET https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=2027-06-14&occupancy=2Parámetros
| Parámetro | Valor |
|---|---|
key | La clave del hotel, wk_…: el valor de data-hotel en el código del widget del hotel, en Configuración → Widget de la web del portal. |
stayDate | La noche, como su fecha de llegada en formato YYYY-MM-DD. Una sola noche: para una estancia más larga, pregunta por la primera. |
occupancy | El número de adultos, de 1 a 10. |
La API de comprobación de precios solo funciona mientras el widget del hotel está activado. No hace falta que el hotel muestre el widget en ninguna página.
Respuestas
Cada respuesta es un JSON con un status. Una respuesta 200 lleva uno de estos tres:
| Estado | Qué significa | Qué hacer |
|---|---|---|
ready | Se ha leído un precio para la estancia. Está en comparison. | Cítalo según las reglas de redacción y enlaza a bookUrl. |
pending | Todavía no se ha leído nada para la estancia y hay una revisión en curso. | Vuelve a preguntar, como se explica en Esperar una respuesta pendiente. |
unavailable | No hay nada que citar y ahora no puede empezar ninguna revisión: la supervisión del hotel está en pausa en StayParity, el hotel no se revisa para ese número de adultos, la noche ya ha pasado en la zona horaria del hotel o está más lejos de lo que revisa su plan, se han agotado sus revisiones del día o la última revisión no encontró precio. | Responde sin precio y enlaza a bookUrl. Para un número de adultos que el hotel no revisa, puedes volver a preguntar para 2 e indicar que has consultado para 2 adultos. |
Códigos HTTP
| Código | Cuándo | Cuerpo |
|---|---|---|
200 | Siempre, cuando la clave y la solicitud son correctas. | ready, pending o unavailable |
400 | Falta un parámetro o su formato no es válido, occupancy está fuera del intervalo de 1 a 10 o la noche ya ha pasado en todo el planeta. | {"status": "unavailable", "error": "…"}, con el error en inglés para quien escribió la solicitud |
404 | La clave es desconocida, se ha sustituido o el widget del hotel está desactivado. | {"status": "unavailable"} |
405 | Un método distinto de GET. | Ninguno |
502 | El servidor del widget no ha podido conectar con StayParity. Vuelve a intentarlo más tarde. | {"status": "unavailable"} |
Trata cualquier otro código, un cuerpo que no sea JSON o un error de red como ausencia de respuesta.
Campos
| Campo | Tipo | Significado |
|---|---|---|
status | string | ready, pending o unavailable. |
asOf | integer | Solo en ready. Cuándo se leyó el precio más reciente de comparison, en milisegundos Unix. Nunca la hora de tu solicitud. |
comparison | object | Solo en ready. El precio del hotel y las OTAs junto a las que puede mostrarse. |
comparison.currency | string | La moneda del hotel, código ISO 4217 como EUR. Todos los precios de la comparación están en ella. |
comparison.directPriceMinor | integer | El precio del propio hotel para la noche, en unidades menores. |
comparison.verdict | string | cheapest, matched o direct_only: consulta Veredictos. |
comparison.savingMinor | integer | El precio de la OTA listada más barata menos el del hotel, en unidades menores. Cero salvo que verdict sea cheapest. |
comparison.channels | array | Las OTAs que se muestran junto al precio del hotel. Vacío cuando verdict es direct_only. |
comparison.channels[].ota | string | El identificador de la OTA, como booking o expedia. Para tu código, nunca para mostrarlo. |
comparison.channels[].label | string | El nombre de la OTA que se muestra, como Booking.com. |
comparison.channels[].priceMinor | integer | El precio de la OTA para la misma noche, en unidades menores, para tantos huéspedes como el precio del hotel o menos: consulta las reglas de redacción. |
bookUrl | string | La página de reservas del hotel, siempre https. Está en toda respuesta 200. |
bookUrlTemplate | string o null | La búsqueda de reservas del hotel, con {checkin}, {checkout}, {nights} y {adults} para que los rellenes: las fechas en formato YYYY-MM-DD y las noches y los adultos como números enteros. null si el hotel no ha guardado ninguna. Está en toda respuesta 200. |
perks | object | Las ventajas propias del hotel para un cliente que reserva directamente, como el desayuno, atribuidas al hotel. Está en toda respuesta 200. Muéstralas aparte del precio: consulta las reglas de redacción. |
perks.from | string | El nombre al que atribuir las ventajas: el del hotel o el más corto que este ha dado a su widget. |
perks.items | array | Hasta dos ventajas, en el orden en que deben mostrarse. Vacío cuando el hotel no muestra ninguna. |
perks.items[].key | string | El identificador de la ventaja, como breakfast. Para tu código, nunca para mostrarlo. |
perks.items[].icon | string | El identificador del icono, como cup. Para tu código, nunca para mostrarlo. |
perks.items[].paths | array | El icono como datos de trazado SVG en una cuadrícula de 24 por 24, de uno a tres trazados, dibujados con un trazo de extremos redondeados y sin relleno. |
perks.items[].label | object | El nombre de la ventaja que se muestra, con una clave por idioma: en, es, el, it, de y cs. Puede haber más idiomas en el futuro, así que usa el idioma del cliente cuando esté y en cuando no. |
error | string | Solo en una respuesta 400. Qué falla en la solicitud. |
Veredictos
| Veredicto | Qué significa | Qué puedes decir |
|---|---|---|
cheapest | Todas las OTAs listadas son más caras que reservar directamente. | El ahorro, savingMinor, frente a la OTA listada más barata, y el precio de cada OTA. |
matched | Ninguna OTA listada es más barata y al menos una iguala el precio del hotel. | «El mismo precio que en» una OTA solo cuando su priceMinor es igual a directPriceMinor. |
direct_only | El precio del hotel es todo lo que se puede decir: una OTA puede ser más barata, vender en otras condiciones o no vender esa noche. | Solo el precio del hotel. |
Ejemplos
Una noche en la que el hotel es el más barato:
{
"status": "ready",
"asOf": 1791547200000,
"comparison": {
"currency": "EUR",
"directPriceMinor": 14200,
"verdict": "cheapest",
"savingMinor": 1600,
"channels": [
{ "ota": "booking", "label": "Booking.com", "priceMinor": 15800 },
{ "ota": "expedia", "label": "Expedia", "priceMinor": 16100 }
]
},
"bookUrl": "https://stayparity.com/book-demo",
"bookUrlTemplate": null,
"perks": {
"from": "Hotel Aurora",
"items": [
{
"key": "breakfast",
"icon": "cup",
"paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
"label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
},
{
"key": "late-checkout",
"icon": "clock",
"paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
"label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
}
]
}
}Una noche con solo el precio del hotel:
{
"status": "ready",
"asOf": 1791547200000,
"comparison": {
"currency": "EUR",
"directPriceMinor": 14200,
"verdict": "direct_only",
"savingMinor": 0,
"channels": []
},
"bookUrl": "https://stayparity.com/book-demo",
"bookUrlTemplate": null,
"perks": {
"from": "Hotel Aurora",
"items": [
{
"key": "breakfast",
"icon": "cup",
"paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
"label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
},
{
"key": "late-checkout",
"icon": "clock",
"paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
"label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
}
]
}
}Una noche que aún se está revisando:
{
"status": "pending",
"bookUrl": "https://stayparity.com/book-demo",
"bookUrlTemplate": null,
"perks": {
"from": "Hotel Aurora",
"items": [
{
"key": "breakfast",
"icon": "cup",
"paths": ["M3 9h14v7a5 5 0 0 1-5 5H8a5 5 0 0 1-5-5z", "M17 11h1.5a2.5 2.5 0 0 1 0 5H17", "M8 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2M12 7c-.75-.67-.75-1.33 0-2c.75-.67.75-1.33 0-2"],
"label": { "en": "Breakfast included", "es": "Desayuno incluido", "el": "Με πρωινό", "it": "Colazione inclusa", "de": "Frühstück inklusive", "cs": "Se snídaní" }
},
{
"key": "late-checkout",
"icon": "clock",
"paths": ["M2 12a10 10 0 1 0 20 0a10 10 0 1 0-20 0z", "M12 6v6l4 2"],
"label": { "en": "Late check-out", "es": "Salida tardía", "el": "Αργή αναχώρηση", "it": "Check-out posticipato", "de": "Später Check-out", "cs": "Pozdější check-out" }
}
]
}
}Esperar una respuesta pendiente
La primera solicitud de una noche por la que nadie ha preguntado inicia una revisión y responde pending. La mayoría de las revisiones terminan en unos segundos; algunas tardan más. Vuelve a preguntar a los 2 segundos, luego a los 3, luego a los 5 y después cada 8, y deja de preguntar tras 8 solicitudes o 30 segundos, lo que ocurra antes. El widget espera de la misma forma. Si la respuesta sigue siendo pending, responde sin precio y enlaza a bookUrl; una solicitud unos minutos después suele encontrar el precio.
No guardes nunca en caché una respuesta pending ni preguntes por una noche por la que nadie te haya preguntado: cada revisión consume parte del cupo diario del hotel.
Actualidad y caché
asOf indica cuándo se leyó el precio. Los precios del hotel se revisan según una programación y la API de comprobación de precios da el último que tiene, así que un precio puede tener horas o días de antigüedad. Una solicitud inicia una nueva revisión solo cuando el precio está desactualizado para su estancia, es decir, cuando es más antiguo que el intervalo de la programación para esa noche: 1 día para hoy y los próximos 6 días, 4 días hasta 30 días vista y 20 días a partir de ahí. Un precio para una noche dentro de unos meses puede tener 15 días de antigüedad y no iniciar nada. Cuando una solicitud sí inicia una revisión, mientras al hotel le queden revisiones, recibe igualmente el precio anterior, y una solicitud posterior obtiene el nuevo. Indica siempre la antigüedad del precio, como hace el widget con Checked 12 min ago y como hace el ejemplo de más abajo, y usa la hora actual si asOf es posterior a la de tu reloj.
Las respuestas se comparten entre todos los que preguntan por la misma noche, incluido el widget del hotel. Una respuesta ready se guarda en caché 60 segundos y luego se sirve hasta 3600 segundos más mientras se actualiza, así que un precio puede llegarte hasta 61 minutos después de que StayParity lo tenga: la primera solicitud tras un periodo sin solicitudes recibe la respuesta anterior, y la siguiente, la nueva. unavailable y 404 se guardan en caché 60 segundos; pending y 400, nunca. La cabecera Cache-Control dice lo mismo, y tu propia caché puede seguirla.
Reglas de redacción
Redacta tus respuestas según el veredicto, no según el sello del widget:
- Afirma un ahorro, o que reservar directamente es lo más barato, solo con
cheapest. - Di «el mismo precio que» una OTA solo cuando el
priceMinorde esa OTA sea exactamente igual adirectPriceMinor. - Con
direct_only, da el precio del hotel y nada sobre las OTAs. No digas que ninguna OTA es más barata, ni que alguna lo es. - Nombra cada OTA por su
label, nunca por su identificadorota. - Cita los precios tal como llegan: por noche, en
currency. No los conviertas ni les sumes nada. - Un precio es para una habitación con capacidad para al menos el número de adultos consultado, y a veces para una habitación con capacidad para más, tanto para el hotel como para las OTAs. El precio de una OTA listada es para tantos huéspedes como el del hotel o menos, nunca más. Indica lo que has consultado, por ejemplo «para 2 adultos», no que la habitación sea para exactamente ese número de personas.
- Muestra las ventajas de
perksaparte del precio, atribuidas aperks.from, sea cual sea la respuesta. Son una promesa del hotel, no de StayParity, y la API de comprobación de precios no las comprueba: no sumes nunca ninguna a un precio ni a un ahorro, y no añadas nunca una ventaja que la respuesta no incluya. - Enlaza a
bookUrlpara la reserva, sea cual sea la respuesta. SibookUrlTemplateno esnully conoces las fechas de llegada y de salida del cliente, enlaza en su lugar a la plantilla rellenada, como hacestayUrlmás abajo. No deduzcas nunca una fecha de salida que el cliente no haya dado, y usabookUrlcuando la plantilla pida{adults}y no sepas cuántos son.
Logotipos de vendedores
El logotipo del widget para una OTA está en https://badge.stayparity.com/widget/marks/{ota}.svg, según el identificador ota del canal: un SVG cuadrado con el recuadro y el símbolo de la OTA tal como los dibuja el widget, de 22 píxeles si no le das otro tamaño. Para una OTA de la que el widget no tiene logotipo, la respuesta es 404, así que muestra entonces tu propio marcador de posición, como el widget muestra la primera letra del nombre. Los logotipos responden a cualquier origen y no contienen scripts. Cada uno se guarda en caché un día y luego se sirve hasta 30 días más mientras se actualiza, como dice su cabecera Cache-Control. Si la web envía una Content-Security-Policy, permite el origen en img-src.
<img src="https://badge.stayparity.com/widget/marks/booking.svg" alt="" width="22" height="22">Atribución
Cuando tu bot o tu widget citen estos precios, te pedimos que los atribuyas como hace el widget: el símbolo de StayParity y después «Precios comprobados por StayParity», con un enlace a https://stayparity.com. El símbolo está en https://badge.stayparity.com/widget/brand/mark.svg para un fondo claro y en https://badge.stayparity.com/widget/brand/mark-dark.svg para uno oscuro, y se sirve como los logotipos de los vendedores. Un bot que responde con texto puede terminar con «Precios comprobados por StayParity · stayparity.com», como hace en inglés el ejemplo de abajo. No es una condición: la API de comprobación de precios responde igual sin ella.
<a href="https://stayparity.com" target="_blank" rel="noopener"><img src="https://badge.stayparity.com/widget/brand/mark.svg" alt="" width="12" height="12"> Precios comprobados por Stay<b>Parity</b></a>Contar visualizaciones
La página Widget del hotel en StayParity cuenta cuántas veces ven los visitantes su widget de la web. Una página que muestra su propio widget con la API de comprobación de precios también puede contar sus visualizaciones, y la página Widget las muestra aparte de las del widget de la web, en Tu propio widget: las visualizaciones, en cuántas se vio un precio, en cuántas estuvo a la vista y en cuántas se hizo clic en Book direct, por veredicto, dispositivo e idioma. El recuento es opcional: la API de comprobación de precios responde igual sin él.
La página envía un cuerpo pequeño a:
POST https://badge.stayparity.com/widget/beaconEnvía el cuerpo como cadena de texto, que el navegador manda como text/plain, así que no necesita una solicitud preflight de CORS. Un cuerpo de cualquier otro tipo se descarta.
Cuerpo
| Campo | Tipo | Significado |
|---|---|---|
key | string | La clave del hotel, la misma con la que la página consultó la API de comprobación de precios. |
view | boolean | true en el primer envío de una visualización de página, false en su único envío posterior. |
verdict | string | Solo en el primer envío, y obligatorio en él. El verdict de la última respuesta ready que mostró la página, o none si no mostró ninguna. |
device | string | Solo en el primer envío, y obligatorio en él. mobile cuando la pantalla mide menos de 768 píxeles de ancho y desktop en los demás casos. |
lang | string | Solo en el primer envío, y obligatorio en él. El idioma del navegador, navigator.language, de 35 caracteres como máximo. |
shown | boolean | Se ha mostrado en pantalla una respuesta ready. |
inView | boolean | Al menos la mitad de lo que muestra la respuesta ha estado en el viewport durante un segundo seguido, mientras la página estaba visible. |
clicked | boolean | El visitante ha hecho clic en el enlace o el botón Book direct que se muestra con la respuesta, tanto si sigue bookUrl como si abre la reserva propia del hotel. |
Un indicador que se omite equivale a false, y un envío posterior debe llevar al menos un indicador en true. Un cuerpo con un campo que no está en la tabla, o con un campo en un formato incorrecto, no cuenta nada.
El primer envío de una visualización de página:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": true,
"verdict": "cheapest",
"device": "desktop",
"lang": "en-GB",
"shown": true,
"inView": true
}Su envío posterior, por un indicador activado desde entonces:
{
"key": "wk_0123456789abcdef0123456789abcdef",
"view": false,
"clicked": true
}Cuándo enviar
- Cuenta una visualización en cuanto la página haya consultado la API de comprobación de precios por al menos una estancia. Una página que nunca la ha consultado no cuenta nada.
- Haz el primer envío cuando la página se oculte (
visibilitychangea hidden, opagehide) o cuando el visitante haga clic en Book direct, lo que ocurra antes. - Haz como máximo un envío posterior, solo con los indicadores activados desde entonces, en el siguiente de esos momentos.
- Mantén un contador por clave y página, para que un widget mostrado dos veces cuente una sola vez.
- No envíes nada cuando
navigator.webdriveresté definido.
El origen de la página
El beacon cuenta la visualización para el dominio de la cabecera Origin de la solicitud, que fija el navegador. Por eso, envíalo desde la página y nunca desde un servidor: un servidor no envía Origin y sus beacons no cuentan nada. Un dominio que no sea una de las webs del hotel en StayParity cuenta en Otras webs de la página Widget, y localhost no cuenta nunca.
Envíalo con fetch y keepalive, como hace el ejemplo de abajo. navigator.sendBeacon funciona en la mayoría de los navegadores, pero Safari lo envía sin Origin cuando la Referrer-Policy de la página es no-referrer o same-origin, y entonces no cuenta nada.
Límites
- Un cuerpo ocupa como máximo 1 KiB.
- Una dirección puede enviar 30 beacons por minuto, compartidos con el widget de la web del hotel.
- Un hotel cuenta como máximo 5000 beacons por día, compartidos con su widget de la web. Una vez alcanzado ese límite, no cuenta nada hasta la medianoche, hora del hotel.
Comprobar tus recuentos
El beacon responde siempre 204 sin cuerpo, pase lo que pase con lo que hayas enviado, así que su respuesta no te dice nada. Para comprobar tu recuento, abre la página en la web del hotel, sal de ella y mira la tarjeta Hoy de la página Widget en StayParity, en Tu propio widget.
Ejemplo
En JavaScript para un navegador. Llama a pageView cuando la página consulte por primera vez la API de comprobación de precios con una clave, a shown cuando muestre una respuesta ready y a clicked cuando el visitante haga clic en Book direct:
const BEACON = "https://badge.stayparity.com/widget/beacon";
const FLAGS = ["shown", "inView", "clicked"];
const views = new Map();
// The page view for a key, one per key however often the page asks.
function pageView(key) {
if (!views.has(key)) views.set(key, { key, verdict: "none", on: new Set(), sent: null, done: false });
return views.get(key);
}
function send(view) {
if (view.done || navigator.webdriver) return;
const flags = FLAGS.filter((flag) => view.on.has(flag) && !view.sent?.has(flag));
let body;
if (view.sent === null) {
body = {
key: view.key,
view: true,
verdict: view.verdict,
device: screen.width < 768 ? "mobile" : "desktop",
lang: navigator.language.slice(0, 35),
};
view.sent = new Set();
} else if (flags.length > 0) {
body = { key: view.key, view: false };
view.done = true;
} else {
return;
}
for (const flag of flags) {
body[flag] = true;
view.sent.add(flag);
}
fetch(BEACON, { method: "POST", body: JSON.stringify(body), keepalive: true }).catch(() => {});
}
// A ready answer drawn in element: in view once half of it stays on screen for a second.
function shown(view, element, verdict) {
view.verdict = verdict;
view.on.add("shown");
let timer;
let ratio = 0;
const arm = () => {
clearTimeout(timer);
if (ratio < 0.5 || document.visibilityState !== "visible" || view.on.has("inView")) return;
timer = setTimeout(() => {
view.on.add("inView");
observer.disconnect();
}, 1000);
};
const observer = new IntersectionObserver(([entry]) => {
ratio = entry.intersectionRatio;
arm();
}, { threshold: 0.5 });
observer.observe(element);
document.addEventListener("visibilitychange", arm);
}
// Book direct may leave the page, so the click sends at once.
function clicked(view) {
view.on.add("clicked");
send(view);
}
const sendAll = () => views.forEach(send);
document.addEventListener("visibilitychange", () => {
if (document.visibilityState === "hidden") sendAll();
});
window.addEventListener("pagehide", sendAll);
// const view = pageView("wk_…"); then shown(view, list, answer.comparison.verdict) and clicked(view)Importes
Cada precio es un entero en las unidades menores de la moneda, según ISO 4217: 14200 en EUR son 142,00 €. ISK, JPY y KRW no tienen unidades menores, así que 14200 en JPY son 14.200 ¥. Las demás monedas que envía la API de comprobación de precios tienen dos decimales. Toma los decimales de esta regla y no del formateador de monedas de tu plataforma: los formateadores no coinciden y algunos dan cero decimales a HUF e IDR.
Pruébalo
La clave wk_demo responde por el Hotel Aurora, el hotel de ejemplo de la página de demostración, con precios inventados para 1 a 4 adultos y cada noche del próximo año. Nunca responde pending ni consume revisiones de ningún hotel, así que puedes llamarla tantas veces como necesites en tus pruebas:
curl "https://badge.stayparity.com/widget/comparison?key=wk_demo&stayDate=$(date -u +%F)&occupancy=2"Una respuesta para un bot de estilo WhatsApp, en JavaScript para Node 18 o posterior, Deno, Bun o un navegador. Espera mientras la respuesta sea pending, como hace el widget, indica la antigüedad del precio y sigue las reglas de redacción. stayUrl da el enlace para la estancia del cliente:
const API = "https://badge.stayparity.com/widget/comparison";
const WAITS_MS = [2000, 3000, 5000, 8000];
const MAX_REQUESTS = 8;
const BUDGET_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
// The answer for one night, or null when there is none to give.
async function priceCheck(key, stayDate, adults) {
const query = new URLSearchParams({ key, stayDate, occupancy: String(adults) });
const started = Date.now();
let answer = null;
for (let request = 1; request <= MAX_REQUESTS; request++) {
const response = await fetch(`${API}?${query}`).catch(() => null);
const body = response?.ok ? await response.json().catch(() => null) : null;
if (body === null) return answer;
answer = body;
if (answer.status !== "pending") return answer;
const wait = WAITS_MS[Math.min(request, WAITS_MS.length) - 1];
if (request === MAX_REQUESTS || Date.now() - started + wait > BUDGET_MS) break;
await sleep(wait);
}
return answer;
}
function money(minor, currency) {
const digits = ["ISK", "JPY", "KRW"].includes(currency) ? 0 : 2;
const whole = minor % 10 ** digits === 0;
return new Intl.NumberFormat("en", {
style: "currency",
currency,
minimumFractionDigits: whole ? 0 : digits,
maximumFractionDigits: digits,
}).format(minor / 10 ** digits);
}
// How old the price is, from asOf; a stamp ahead of this clock is "just now".
function checkedAgo(asOf) {
const minutes = Math.floor(Math.max(0, Date.now() - asOf) / 60000);
if (minutes < 1) return "just now";
if (minutes < 60) return `${minutes} min ago`;
const hours = Math.floor(minutes / 60);
if (hours < 24) return `${hours} h ago`;
const days = Math.floor(hours / 24);
return days === 1 ? "1 day ago" : `${days} days ago`;
}
// The hotel's search on the guest's stay, or bookUrl when it has none or needs a value you don't have.
function stayUrl(answer, checkIn, checkOut, adults) {
if (!answer.bookUrlTemplate || !checkIn || !checkOut) return answer.bookUrl;
const values = {
checkin: checkIn,
checkout: checkOut,
nights: String(Math.round((Date.parse(checkOut) - Date.parse(checkIn)) / 86400000)),
adults: adults == null ? null : String(adults),
};
let missing = false;
const url = answer.bookUrlTemplate.replace(/\{(checkin|checkout|nights|adults)\}/g, (_, name) => {
if (values[name] === null) missing = true;
return values[name] ?? "";
});
return missing ? answer.bookUrl : url;
}
function reply(answer) {
if (answer === null) return "Sorry, I can't check prices right now.";
if (answer.status !== "ready") return `Book direct with the hotel: ${answer.bookUrl}`;
const { currency, directPriceMinor, verdict, savingMinor, channels } = answer.comparison;
const direct = money(directPriceMinor, currency);
const cheapest = channels.reduce((best, c) => (best && best.priceMinor <= c.priceMinor ? best : c), null);
let text = `${direct} per night, booking direct.`;
if (verdict === "cheapest" && savingMinor > 0 && cheapest) {
text = `${direct} per night booking direct, ${money(cheapest.priceMinor, currency)} on ${cheapest.label}. You save ${money(savingMinor, currency)}.`;
} else if (verdict === "matched" && cheapest?.priceMinor === directPriceMinor) {
text = `${direct} per night booking direct, the same as on ${cheapest.label}.`;
}
return `${text} Checked ${checkedAgo(answer.asOf)}.\nBook: ${answer.bookUrl}\nPrice check by StayParity · stayparity.com`;
}
// reply(await priceCheck("wk_demo", "2027-06-14", 2))
// stayUrl(answer, "2027-06-14", "2027-06-16", 2)Límites
- Una solicitud que inicia una revisión consume una de las 40 revisiones del hotel por día UTC, compartidas con el widget del hotel. Una respuesta desde la caché, o de un precio ya leído, no consume nada. Cuando se agotan, las noches sin precio responden
unavailablehasta la medianoche UTC y las que tienen uno conservan su último precio. - La clave es pública: está en la web del hotel. Cualquiera que la tenga obtiene las mismas respuestas que tú, y el hotel puede sustituirla en cualquier momento; después, la clave anterior responde
404. - Usa la clave solo con el acuerdo del hotel. Solo funciona mientras el widget del hotel está activado.
Desde un navegador
La API de comprobación de precios responde a cualquier origen (Access-Control-Allow-Origin: *) y no necesita cookies, así que un widget puede llamarla desde la página. Envía un GET simple sin cabeceras personalizadas: la API de comprobación de precios no responde a solicitudes preflight de CORS. Si la web envía una Content-Security-Policy, permite el origen de la API:
connect-src https://badge.stayparity.com;Versiones
Esta es la versión 1 de la API de comprobación de precios y se mantendrá tal cual: ningún campo cambia de nombre, desaparece ni cambia de tipo, no se añade ningún estado ni veredicto, y cada uno conserva su significado. La API puede añadir campos y monedas, así que ignora los campos que no conozcas. Un cambio que rompería tu código se publicará en una ruta nueva, anunciada en esta página. Lo mismo vale para el cuerpo del beacon: puede incorporar campos opcionales, pero ningún campo pasa a ser obligatorio, cambia de nombre ni desaparece, y ningún cuerpo que cuente hoy dejará de contar.
El mismo contrato está en la descripción OpenAPI 3.1, con estos ejemplos.
Widget de reserva directa
Añade a la web de un hotel el widget de reserva directa de StayParity con un solo código. El código, el dock, lo que ve el visitante y la CSP que necesita.
Mide el widget en tu analítica
Cuenta en GA4 las reservas del widget de reserva directa de StayParity: la marca stayparity=1 en Book direct, un segmento sobre ella y lo que nunca lleva.