Integración personalizada (API propia)

Si tu hotel trabaja con un sistema desarrollado a medida, o con un PMS o motor que WeSpeak todavía no integra, puedes conectarlo por API. Tu equipo técnico publica dos endpoints con el formato de WeSpeak y, desde ahí, el asistente consulta precios y disponibilidad en vivo en tu sistema y carga ahí las reservas que se cierran por chat.

ℹ️ No es lo mismo que WeSpeak Rates sin PMS ni Channel Manager: ahí WeSpeak es tu sistema. Aquí tu sistema sigue mandando y WeSpeak lo consulta.

En este artículo

• Qué necesitas
• Cómo se conecta, paso a paso
• El contrato: disponibilidad (GET)
• El contrato: reservas (POST)
• Antes de abrir la venta
• Qué no hace
• Errores frecuentes
• Preguntas frecuentes

Qué necesitas

💡 Si tu PMS o tu Channel Manager ya está integrado con WeSpeak, no necesitas esto: pídele a tu asesor la conexión nativa. Mira Conoce WeSpeak Rates.

Cómo se conecta, paso a paso

1. Pide la activación a tu asesor. El equipo de WeSpeak activa la Integración personalizada en tu propiedad y te aparece la sección en tu panel.
2. Carga tus endpoints en Configuración → Integración personalizada: la URL de disponibilidad, la URL de reservas y la API key. Cada campo se guarda solo al salir de él.
3. Prueba desde la misma pantalla. Probar disponibilidad consulta tu endpoint en vivo y te marca, campo por campo, qué no cumple el formato. Probar creación de reserva envía una reserva de prueba que tu sistema no debe crear.
4. Haz una cotización real por chat y compara los precios con los de tu sistema.
5. Valida las reservas con la lista de Antes de abrir la venta.

En la misma pantalla, Ver formato esperado muestra el contrato con ejemplos: es el mismo de este artículo.

🛠️ ¿Dudas técnicas sobre el contrato? Tu equipo de desarrollo puede escribirle directamente al nuestro a tecnologia@wespeak.pro.

El contrato: disponibilidad (GET)

Cada vez que el asistente necesita cotizar, WeSpeak llama a tu URL agregando estos parámetros:

GET https://api.tuhotel.com/wespeak/availability?channel=custom&username=tu-hotel&channelPass=&checkinDate=2026-11-10&checkoutDate=2026-11-12&currency=USD&persons=2&adults=2&kids=1&childrenAge=8
X-API-Key: tu-api-key

Tu endpoint responde con este JSON:

{
  "available": true,
  "rooms": [
    {
      "name": "Doble Superior",
      "code": "DBL",
      "currency": "USD",
      "bookable": true,
      "unitsLeft": 3,
      "minStay": 2,
      "maxStay": 14,
      "rates": [
        { "name": "Tarifa Flexible", "code": "FLEX", "totalPrice": "300.00" },
        { "name": "No Reembolsable", "code": "NR", "totalPrice": "260.00" }
      ]
    }
  ]
}

Reglas que conviene respetar desde el primer día:

• "Sin disponibilidad" no es un error. Responde 200 con available: false. Deja los códigos 4xx y 5xx para fallas reales, como una clave inválida o tu sistema caído.
• Aplica tus restricciones a las fechas pedidas. Si una habitación no se puede reservar, devuélvela con bookable: false en lugar de omitirla. Si ninguna se puede reservar, responde available: false.
• Responde en la moneda de tu sistema. Si el huésped pidió otra, WeSpeak convierte el precio.
• El precio tiene que corresponder a la ocupación pedida, niños incluidos.
• Devuelve solo las tarifas que quieras vender por chat. El asistente ofrece todas las que vengan en rates, y el huésped ve rates[].name: si dos tarifas difieren en reembolso o en forma de pago, que el nombre lo diga, por ejemplo "No reembolsable" o "Flexible, pago en el hotel".
• Cada tarifa tiene que aceptar la forma de cobro que configuraste en WeSpeak Payments. Si una tarifa exige el pago total y el hotel cobra seña o pago en el hotel, la reserva va a fallar.
• Cada consulta llega en vivo. No guardamos en caché, y antes de cobrar volvemos a consultar para confirmar precio y cupo. Si una consulta falla, la repetimos.
• Responde rápido. Lo ideal es menos de 5 segundos. La prueba del panel corta a los 15.
• Responde siempre un JSON válido. Si tu endpoint falla o responde otro formato, el asistente deja de cotizar y le avisa al equipo de WeSpeak, para no darle al huésped un precio equivocado.
• Deja pasar las llamadas de WeSpeak. Si usas Cloudflare u otro firewall con bloqueo de bots, exceptúa estas rutas: WeSpeak llama desde servidores, no desde un navegador.

El contrato: reservas (POST)

Cuando el huésped confirma la reserva con WeSpeak Payments, ya sea con pago online, transferencia o pago en el hotel, WeSpeak envía la reserva a tu URL:

{
  "weSpeakReservationId": "8f2c1a7e-4b1d-4c55-9a51-2f6c0d9e1b3a",
  "username": "tu-hotel",
  "checkinDate": "2026-11-10",
  "checkoutDate": "2026-11-12",
  "currency": "USD",
  "currencyConversion": null,
  "rooms": [
    {
      "name": "Doble Superior",
      "code": "DBL",
      "rateName": "Tarifa Flexible",
      "rateCode": "FLEX",
      "adults": 2,
      "kids": 1,
      "kidAges": [8],
      "priceAmount": "300.00"
    }
  ],
  "totalPrice": 300,
  "amountPaid": 90,
  "amountToPay": 210,
  "depositAmount": 90,
  "paymentMethod": "...",
  "paymentDetails": {
    "orderId": "...",
    "gateway": { "name": "..." }
  },
  "customerName": "Ana",
  "customerSurname": "Pérez",
  "customerEmail": "ana@example.com",
  "customerPhone": "+5491100000000",
  "customerCountry": "AR",
  "reservationNote": "Llega tarde, cerca de las 23 h"
}

Tu endpoint responde:

{
  "success": true,
  "reservationId": "ABC123",
  "status": "confirmed",
  "message": "Reserva creada"
}

Reglas del POST:

• Cada elemento de rooms es una habitación. Una reserva de dos habitaciones trae dos elementos, cada uno con su ocupación y su priceAmount.
• Ignora los campos que no uses. El cuerpo puede sumar campos nuevos con el tiempo: no rechaces la reserva por un campo que no conoces.
• Los códigos vuelven tal cual. rooms[].name, code, rateName y rateCode son los que tu sistema devolvió en el GET. Si no enviaste un código, llega como null.
• El code es el identificador. Todo lo que tu sistema necesite para reservar, por ejemplo una promoción, tiene que poder deducirse del code de la habitación y de la tarifa. El nombre viaja como referencia.
• No dupliques reservas. Si tu endpoint no responde o responde con un error HTTP, reintentamos una vez con el mismo weSpeakReservationId. Si ese id ya existe en tu sistema, devuelve la reserva ya creada en lugar de crear otra. Un rechazo también tiene que repetirse igual, y el mismo id con datos distintos se rechaza.
• Modo prueba. Si el cuerpo trae "isTest": true, valida el formato y responde como siempre, pero no crees la reserva. Es lo que usa el botón de prueba del panel.
• Descuenta el cupo en el mismo momento. Dos huéspedes pueden pagar la última habitación casi a la vez: tu sistema tiene que aceptar una sola reserva.
• Si la reserva quedó creada, responde success: true, aunque falle algo secundario como registrar el pago en tu sistema. Ese paso lo resuelves de tu lado.
• Para rechazar, responde 200 con success: false y un message que explique el motivo, por ejemplo que el precio cambió o que ya no hay cupo. La reserva queda en Reservas de WeSpeak como no sincronizada, para que tu equipo la resuelva.
• Si no sabes si la reserva quedó creada, no respondas success: true. Responde success: false explicándolo y escríbenos a tecnologia@wespeak.pro, para revisarla antes de cargarla a mano y no duplicarla.
• reservationId es el número de la reserva en tu sistema. Lo guardamos para que tu equipo la encuentre.

Montos y moneda:

• rooms[].priceAmount es el total de la estadía de esa habitación, en la moneda de currency.
• totalPrice, amountPaid, amountToPay y depositAmount van en la moneda en que pagó el huésped. Si es distinta de currency, currencyConversion trae esa moneda y la tasa, por ejemplo { "currency": "ARS", "conversionRate": 1450 }. Para pasar esos montos a la moneda de currency, divídelos por la tasa.
• amountPaid + amountToPay = totalPrice. amountPaid es lo que se cobró por chat y amountToPay lo que cobra el hotel según su política. depositAmount es la seña que pide la política, no lo cobrado.
• Impuestos: la suma de priceAmount coincide con totalPrice si no hubo conversión y tus precios ya incluyen impuestos. Si en WeSpeak se configuran impuestos que se suman al precio, totalPrice los incluye y priceAmount no. Lo más simple es devolver precios finales y no sumar impuestos en WeSpeak.
• paymentDetails trae las referencias de la pasarela y llega vacío si no hubo cobro online. Si paymentDetails.gateway.name es Zru Token, es una garantía con tarjeta: todavía no se cobró nada, aunque amountPaid traiga un monto.

Antes de abrir la venta

Así validamos con los partners que ya se conectaron. Conviene empezar con las URL de tu ambiente de pruebas y una propiedad de prueba, y cambiarlas por las de producción al final:

• Disponibilidad: fechas con cupo, fechas sin cupo, con niños y para un grupo grande.
• Seguridad: una clave inválida y el username de otra propiedad, que tu endpoint rechaza con 401 o 403.
• Reserva nueva, el mismo envío repetido, que debe devolver la misma reserva, y el mismo id con otros datos, que debe rechazarse.
• Precio que cambió o cupo que se agotó entre la cotización y el pago: tu sistema la rechaza con un motivo claro.
• Reserva de varias habitaciones, con pago total, con depósito y sin pago.
• Última unidad: dos reservas simultáneas, y solo una se confirma.
• Limpieza: cancela las reservas de prueba, porque ocupan cupo.
• Una reserva controlada en producción en una sola propiedad, que después cancelas, antes de abrir la venta en el resto.

Qué no hace

• No envía modificaciones ni cancelaciones. Si una reserva cambia en WeSpeak, tu equipo la actualiza en tu sistema a mano.
• No escribe precios ni disponibilidad en tu sistema. Solo los consulta y, al reservar, envía la reserva.
• No trae fotos ni descripciones. Se cargan una vez en WeSpeak, en cada habitación. Tu endpoint aporta solo lo que cambia: precio, cupo y si se puede reservar.

Errores frecuentes

Preguntas frecuentes

¿Necesito WeSpeak Payments para cotizar?
No. Payments solo hace falta para que la reserva entre a tu sistema. Sin él, el asistente cotiza con tus precios y tu equipo carga las reservas.

¿Sirve para varias propiedades?
Sí. Cada propiedad tiene su configuración, y el parámetro username le dice a tu endpoint de qué hotel se trata.

¿Puedo usar WeSpeak Rates encima?
Sí. La disponibilidad sale de tu endpoint y las tarifas que crees en Rates se aplican encima. Para eso necesitas los code de habitación y de tarifa.

¿Qué pasa si mi sistema se cae?
El asistente deja de cotizar y avisa al equipo de WeSpeak, para no darle al huésped un precio equivocado. Cuando tu endpoint vuelve a responder, todo sigue igual.

¿Tengo que enviarles la disponibilidad o avisos de cambios?
No. Consultamos tu endpoint en vivo cada vez, y lo único que enviamos es la reserva.

¿Cómo les paso la API key?
No la envíes por correo: la cargas tú en Configuración → Integración personalizada y no vuelve a mostrarse.

¿Puedo usar HTTP o una IP interna?
No. Solo se aceptan URLs con HTTPS que se puedan alcanzar desde internet.

¿A quién le escribo si algo no funciona?
Para dudas técnicas del contrato o de tus endpoints, a nuestro equipo de desarrollo: tecnologia@wespeak.pro. Para activar la integración o WeSpeak Payments, a tu asesor.