Cómo integrar SES Hospedajes con tu PMS: el web service por dentro

«SES Hospedajes tiene API» es verdad a medias. Tiene un servicio web SOAP pensado para que los sistemas de gestión comuniquen el parte de viajeros sin entrar al portal. Funciona, está documentado y se puede automatizar de principio a fin. Pero no se parece nada a una API REST moderna, y las decisiones que tomes al integrarlo determinan si aguanta en producción o te da guerra cada noche.

Esto es lo que aprendimos construyendo esa integración: qué necesitas antes de escribir código, cómo es el servicio por dentro y las cuatro decisiones de diseño que importan.

Lo que necesitas antes de escribir código

Nada de esto se resuelve programando, así que conviene tenerlo resuelto antes:

Cómo es el servicio por dentro

Tres rasgos que condicionan la integración:

1. SOAP, y el XML va comprimido

No mandas JSON: construyes un XML con la estructura del parte y lo envías dentro de un sobre SOAP, comprimido. Si vienes de integrar APIs REST, el primer día se va en montar el sobre y en descubrir que el error de «XML inválido» puede venir de un carácter de más.

2. Cada viajero es una comunicación independiente

Un parte no es un bloque monolítico: dentro del lote va un bloque comunicacion por persona. Esto es la mejor característica del servicio y la que más se ignora, porque tiene dos consecuencias muy útiles:

• El documento erróneo de un viajero no bloquea el registro de los demás.
• Puedes enviar un parte parcial con quien se haya registrado y comunicar a los rezagados después, sin duplicar a los que ya iban.

3. La confirmación es asíncrona

El envío devuelve un número de lote, no una confirmación. El resultado real —un código de comunicación por viajero, o los errores— llega al consultar el lote después. Una integración que no vuelve a preguntar no sabe si está cumpliendo.

Las cuatro decisiones que importan

Cuándo enviar

El plazo son 24 horas desde el inicio del alojamiento. Enviar en cuanto se registra el primer viajero es tentador pero genera muchísimas comunicaciones parciales; esperar al grupo completo se come el plazo cuando alguien no rellena.

A nosotros nos funciona un barrido nocturno el día de la llegada, con lo que haya registrado a esa hora, y una pasada cada hora para lo que llegue después: si los que faltan esperasen a la noche siguiente, a una entrada de las 15:00 se le irían más de 30 horas. Y un botón de «enviar ahora» para el caso puntual.

Qué hacer con los rechazos

Un rechazo no es un error de tu sistema: es un dato mal introducido que hay que corregir y reintentar. Necesitas guardar el error por viajero y que el reintento vuelva a salir solo cuando se corrija, sin intervención manual. Si el operador tiene que acordarse de reenviar, se olvidará.

Dónde validar

Toda validación que puedas hacer en el formulario del huésped te ahorra un viaje al Ministerio y una corrección a mano después. Letra del DNI, número de soporte, segundo apellido, código INE del municipio, código postal que exista de verdad, parentesco de menores. Lo detallamos en el artículo sobre los errores de SES.

Idempotencia

Los reprocesos existen: un timeout, un despliegue a media noche, un reintento manual. Si tu identificador de envío no es determinista, acabarás con partes duplicados o con viajeros contados dos veces. Conviene que el identificador salga de los datos (reserva + viajero) y no de un contador.

El entorno de pruebas

SES tiene un entorno de pruebas, y merece la pena montarlo antes de tocar producción: los errores del Ministerio son crípticos y se aprenden a base de intentos. Solo dos cautelas:

1. Que el entorno sea explícito en el código, no un comentario. Un envío de prueba que acaba en producción es un parte real comunicado a la policía con datos falsos.
2. Que lo enviado en pruebas no cuente en tus métricas ni en lo que factures a un cliente.

Aviso: esto no vale para toda España

Cataluña y País Vasco tienen sistema propio y no usan SES Hospedajes. Si tus alojamientos están allí, la integración es otra —y en el caso de Cataluña, no existe forma automática de conectarse. El resto de comunidades, incluidas Galicia, Madrid, Andalucía, Baleares y Canarias, van por SES.

El atajo, si no quieres construirlo

Todo lo anterior es trabajo real: SOAP, certificados, validaciones, reintentos, deltas y un entorno de pruebas. Tiene sentido asumirlo si el registro de viajeros es tu producto. Si no lo es, existe la opción de llamar a una API REST y que otro se coma esa complejidad.

curl -X POST https://api.kinapi.es/v1/checkins \
  -H "ocp-apim-subscription-key: TU_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "reservationId": "R-2026-0412",
    "listingId": "APT-01",
    "checkInDate": "2026-08-14",
    "checkOutDate": "2026-08-18",
    "numGuests": 2
  }'

A partir de ahí el huésped rellena sus datos ya validados, firma el contrato y el parte sale a SES solo. La guía rápida lo cuenta en cinco minutos.