API REST de Partehotel: integra tu motor de reservas y automatiza los partes de viajeros

¿Qué es la API REST de Partehotel?

Muchos hoteles y hostales tienen ya su propia web con motor de reservas, o trabajan con un desarrollador que gestiona sus reservas online. Hasta ahora, esas reservas había que introducirlas a mano en Partehotel para generar el check-in digital y el parte de viajeros. Con la API REST de Partehotel eso desaparece: el motor de reservas crea directamente la reserva en Partehotel, la plataforma notifica a SES.hospedajes y devuelve un enlace de check-in listo para enviárselo al huésped.

El resultado es que el huésped nunca sabe que el proceso pasa por Partehotel, el propietario cumple con la obligación legal de enviar el parte de viajeros de forma automática y el desarrollador integra el cumplimiento legal en el flujo de reservas con unas pocas llamadas a la API.

Cómo funciona la integración paso a paso

Paso 1: generación de la clave API

Desde el panel de Partehotel, en Mi cuenta → API REST, el propietario genera su clave API. La clave tiene el formato ph_live_… y se muestra una única vez; hay que copiarla y entregársela al desarrollador. Si se revoca, se genera una clave nueva y la anterior queda inútil de inmediato.

Paso 2: consulta de disponibilidad (opcional pero recomendada)

Antes de crear la reserva, el motor de reservas puede preguntar a la API si la habitación solicitada está disponible en las fechas elegidas:

GET /api/v1/hotel/rooms/availability?room_id=42&check_in=2026-09-01&check_out=2026-09-05
Authorization: Bearer ph_live_…

La respuesta indica si hay solapamiento con otra reserva existente, evitando conflictos antes de intentar crear la reserva.

Paso 3: creación de la reserva

El motor de reservas envía los datos de la reserva con un POST:

POST /api/v1/hotel/reservations
Authorization: Bearer ph_live_…
Idempotency-Key: res-booking-20260901-42

{
  "rooms": [{"room_id": 42, "board_plan": "ad", "adults": 2, "children": 1}],
  "check_in": "2026-09-01",
  "check_out": "2026-09-05",
  "guest": {
    "first_name": "María",
    "last_name": "García",
    "last_name2": "López",
    "email": "maria@example.com",
    "phone": "+34600000000"
  },
  "send_email": false
}

Partehotel crea la reserva, la envía a SES.hospedajes y responde con un JSON que incluye el campo checkin_url: el enlace directo al formulario de check-in del huésped. El motor de reservas puede incluir ese enlace en el email de confirmación que envía al huésped desde su propia plataforma.

Paso 4: el huésped completa el check-in

El huésped accede al enlace, que le lleva al formulario de Partehotel disponible en 6 idiomas. Desde el móvil fotografía su documento de identidad, la IA extrae los datos, los revisa, firma digitalmente y envía el parte. Todo sin instalar ninguna app.

Paso 5: la estancia sigue su ciclo normal

En el panel de Partehotel, la reserva aparece en el cuadro sinóptico y el calendario como cualquier otra. El propietario puede alojarlo, modificarla o cancelarla. Al finalizar la estancia se emite automáticamente el recibo al huésped.

El modo transparente: integración sin marca visible

Si el propietario activa el modo transparente (Mi cuenta → API REST), Partehotel no envía ningún email al huésped: ni el enlace de check-in ni el recibo de fin de estancia. El desarrollador se encarga de enviar el enlace checkin_url dentro de sus propios emails de confirmación, manteniendo la identidad visual del hotel en toda la comunicación.

El envío del parte a SES.hospedajes se realiza siempre, independientemente del modo transparente. El propietario sí recibe la copia del recibo si tiene activadas las notificaciones de copia.

Idempotencia: reintentos sin duplicados

La API acepta una cabecera Idempotency-Key opcional. Si el motor de reservas reintenta una llamada (por timeout de red, por ejemplo) con la misma clave de idempotencia, Partehotel detecta el duplicado y devuelve la respuesta original sin crear una segunda reserva. Basta con usar como clave un identificador único de la reserva en el sistema del hotel.

Cancelaciones y reembolso automático del saldo

Si una reserva API se cancela antes de que el huésped haya completado el parte de viajeros, el importe de gestión se reembolsa automáticamente al saldo del propietario. Esto permite hacer pruebas de integración sin perder dinero: se crea la reserva de prueba y se cancela de inmediato.

Partehotel no tiene sandbox precisamente porque el reembolso al cancelar hace innecesario mantener un entorno separado, y simplifica la integración al trabajar siempre contra el entorno real.

Coste de las reservas creadas por API

El coste por estancia es el mismo que para cualquier reserva gestionada desde el panel: el importe de alta más el importe por noche, con el mismo tope mensual según el tamaño del hotel. No hay ningún recargo por usar la API.

El saldo necesario ya lo tiene el propietario en su cuenta de Partehotel; si en el momento de crear la reserva el saldo es insuficiente, la API devuelve un error 402 con el importe necesario.

Webhooks: recibe los cambios en tu sistema

Además de crear y consultar reservas, Partehotel puede notificar a tu sistema en tiempo real cada vez que algo cambia en el hotel, sin necesidad de hacer polling. La funcionalidad de webhooks está disponible para todas las reservas del hotel — no solo las creadas por API — y se configura en un solo paso desde Mi cuenta → Integraciones: introduces la URL de tu endpoint y Partehotel empieza a enviarle eventos firmados de forma inmediata.

Cada petición incluye la cabecera X-Partehotel-Signature con una firma HMAC-SHA256 que tu sistema verifica para confirmar que el evento procede de Partehotel. Las entregas son at-least-once con reintentos automáticos en backoff; basta con que tu receptor deduplique por el campo id del evento para garantizar la idempotencia.

Eventos disponibles

• reservation.created — nueva reserva registrada en el hotel.
• reservation.status_changed — cambio de estado de una reserva (incluye estado anterior y nuevo).
• reservation.updated — modificación de fechas, régimen u ocupantes.
• reservation.cancelled — cancelación de la reserva desde el panel o la API.
• guest.checked_in — el huésped ha completado el check-in digital y firmado el parte.
• ses.submission_succeeded — el parte ha sido aceptado por SES.hospedajes.
• ses.submission_failed — el envío a SES ha fallado tras todos los reintentos.
• balance.low — el saldo del propietario ha caído por debajo del umbral de alerta.
• receipt.sent — se ha emitido el recibo de fin de estancia al huésped.

Para más detalles sobre el formato del payload, la verificación de la firma y las pruebas de conectividad (ping desde el panel), consulta la documentación técnica de integraciones.

¿Para quién es la API?

• Hoteles con motor de reservas propio: el desarrollador de la web integra la API y las reservas online se tramitan automáticamente en Partehotel sin intervención manual.
• Agencias y desarrolladores web hoteleros: pueden ofrecer a sus clientes la gestión automática del cumplimiento legal sin que el hotelero tenga que aprender a usar otro sistema.
• Propietarios con sistemas de gestión propios: si el hotel ya tiene un sistema de reservas a medida, la API permite integrarlo con la tramitación legal de partes en pocas líneas de código.

Cómo empezar

1. Crea tu cuenta en Partehotel (registro gratuito, sin tarjeta).
2. Configura tus habitaciones, temporadas y tarifas.
3. Ve a Mi cuenta → API REST y genera tu clave API.
4. Consulta la documentación interactiva en Mi cuenta → API REST → Ver documentación interactiva.
5. Comparte la clave y el enlace de documentación con tu desarrollador.

Si tienes dudas técnicas durante la integración, el equipo de soporte de Partehotel está disponible en soporte@partehotel.com o en el teléfono 91 99 33 454.