GET /hotel/rooms/availability
Consulta previa: devuelve si la habitación está libre en el rango de fechas antes de intentar crear la reserva.
Para desarrolladores · Hoteles con web propia
API REST: tu motor de reservas
API REST: tu motor de reservas
→ partes de viajeros automáticos
Tu web ya toma reservas. Con la API REST de Partehotel, cada reserva online genera el parte de viajeros, notifica a SES.hospedajes y devuelve al huésped el enlace de check-in con escaneo IA — sin trabajo manual en recepción.
Sin tarjeta · sin coste adicional · soporte en español
En resumen
- Llama a
POST /api/v1/hotel/reservationscon los datos de la reserva. - Partehotel envía la notificación a SES.hospedajes y devuelve
checkin_url. - Incluye ese enlace en tu email de confirmación al huésped.
- El huésped firma el parte. Tú cumples el RD 933/2021 sin tocar nada.
Referencia rápida
Seis endpoints, todo resuelto
POST /hotel/reservations
Crea la reserva, envía a SES.hospedajes y devuelve checkin_url para incluirla en el email al huésped.
GET /hotel/reservations/{id}
Estado completo de la reserva: estado del parte, checkin_url, fechas, habitación y titular.
PUT /hotel/reservations/{id}
Modifica fechas, régimen o número de ocupantes mientras la reserva aún no ha sido alojada.
POST /hotel/reservations/{id}/cancel
Cancela y reembolsa el importe al saldo si el huésped no ha completado el parte. Anula también en SES.hospedajes.
GET /hotel/rooms
Lista todas las habitaciones con su id, categoría, ocupación y plazas para construir el selector de habitación.
GET /hotel/reservations/{id}/info-sheet
Descarga en PDF la hoja de información de la reserva (datos de la estancia, huéspedes, medio de pago y QR). Disponible en estados E, I u O.
Integración en 4 pasos
De la reserva online al parte enviado, sin intervención
1
Genera la clave API
En Mi cuenta → API REST genera el token ph_live_… y entrégalo a tu desarrollador.
Se muestra una sola vez; si se pierde se revoca y genera uno nuevo.
2
Conecta tu motor de reservas
Al confirmar una reserva online, tu sistema llama a POST /api/v1/hotel/reservations
con los datos del titular, habitación, fechas y régimen. Añade un Idempotency-Key
para que los reintentos de red no generen duplicados.
3
Partehotel envía a SES y devuelve el enlace
Partehotel notifica a SES.hospedajes con las credenciales del hotel
y responde con checkin_url: el enlace de check-in para el huésped.
En caso de fallo de SES, el scheduler reintenta cada 2 horas sin que tengas que hacer nada.
4
El huésped completa el check-in
Incluyes checkin_url en tu email de confirmación. El huésped escanea su
documento con la IA, firma en pantalla y el parte queda enviado. Tú cumples el
RD 933/2021 sin abrir el panel.
Integración invisible
Modo transparente: tu marca, no la nuestra
Con el modo transparente activo, Partehotel no envía ningún email al
huésped. Eres tú quien incluye el enlace checkin_url en tu propio email de
confirmación: el huésped ve solo tu dominio y tu marca en todo el proceso.
El envío del parte a SES.hospedajes se realiza siempre.
- Sin emails de Partehotel al huésped (ni check-in ni recibo final).
- La copia al propietario sigue llegando si está activada.
- Se activa en un solo clic desde Mi cuenta → API REST.
Referencia técnica
Lo que necesita saber tu desarrollador
Autenticación
Cabecera Authorization: Bearer ph_live_…. Una clave activa por cuenta.
Compatible con cualquier lenguaje o framework que soporte HTTP.
Idempotencia
Cabecera opcional Idempotency-Key. Reintentar la misma llamada con la
misma clave devuelve la respuesta original sin crear reservas duplicadas.
Sin sandbox
La API trabaja en producción. Cancelar una reserva de prueba antes de que el huésped complete el parte reembolsa el importe al saldo automáticamente.
Errores uniformes
Todos los errores siguen el formato {"error":{"codigo","mensaje"}}
con códigos semánticos: insufficient_balance, room_unavailable,
room_not_found, etc.
Novedad · Integraciones
Webhooks: tu PMS, siempre sincronizado
Cada cambio de estado de cualquier reserva del hotel — no solo las creadas por API —
dispara automáticamente un HTTP POST firmado a la URL que configures en
Mi cuenta → Integraciones. Tu PMS o sistema propio recibe el evento, verifica
la firma X-Partehotel-Signature y actualiza su estado en tiempo real,
sin necesidad de hacer polling.
El ciclo de vida de una reserva
Toda reserva avanza por estos estados. El evento
reservation.status_changed se emite en todas las
transiciones (con los campos from y to): es la señal fiable
para seguir el ciclo completo. El envío del parte a SES depende de la configuración
del propietario — ocurre en el acto al completar el huésped
(P→E, envío automático) o tras su revisión manual
(F→E, envío manual).
G→P→F→E→I→O
(+ C = cancelada)
| Estado | Qué significa | Evento(s) al entrar |
|---|---|---|
G | Guardada — reserva registrada, envío a SES pendiente (transitorio). | reservation.created |
P | Parte pendiente — el huésped tiene el enlace de check-in pero aún no ha completado el parte. | reservation.created / status_changed |
F | El huésped completa y firma el parte. En modo envío manual queda aquí, listo para que el propietario lo revise antes de enviarlo a SES. | status_changed (P→F) + guest.checked_in |
E | Parte enviado a SES.hospedajes / Mossos. Se llega automáticamente al completar el huésped (P→E, envío automático) o tras la revisión del propietario (F→E, envío manual). | status_changed (→E) + ses.submission_succeeded |
I | Huésped alojado en el hotel. | status_changed (E→I) |
O | Estancia finalizada. | status_changed (I→O) + receipt.sent |
C | Reserva cancelada. | status_changed (→C) + reservation.cancelled |
reservation.status_changed
Se emite en cada transición de estado (G→P, P→F, P→E, F→E, E→I, I→O…). Incluye from y to: es la señal universal del ciclo de vida.
guest.checked_in
El huésped ha completado y firmado el parte (paso a estado F): documento escaneado y datos revisados. Con envío automático la reserva salta P→E (sin pasar por F) y este evento no se emite: detéctalo con status_changed.
ses.submission_failed
El envío a SES.hospedajes ha fallado tras todos los reintentos. Actúa antes de la próxima inspección.
receipt.sent
Se ha emitido el recibo de fin de estancia al huésped. Útil para sincronizar tu sistema de facturación.
reservation.cancelled
Una reserva ha sido cancelada, ya sea desde el panel o por la API. Incluye motivo y estado de reembolso.
balance.low
El saldo del propietario ha caído por debajo del umbral de alerta. Integra una recarga automática en tu sistema.
Seguridad: firma HMAC-SHA256
Cada entrega incluye la cabecera X-Partehotel-Signature: t=<ts>,v1=<hash>.
Recalcula la firma con tu secreto y compárala antes de procesar el evento.
Fiabilidad: reintentos automáticos
Al-least-once con reintentos en backoff exponencial. Deduplica por el campo id
del evento para garantizar la idempotencia en tu receptor.
Preguntas frecuentes
Dudas de desarrolladores y propietarios
¿En qué lenguajes puedo usar la API?
En cualquiera que soporte HTTP: PHP, Python, JavaScript/Node, Ruby, Go, Java… Solo necesitas
hacer llamadas HTTP con la cabecera Authorization: Bearer ph_live_… y procesar
el JSON de respuesta.
¿La API envía los partes de viajeros a SES.hospedajes automáticamente?
Sí. Al crear la reserva, Partehotel envía la notificación de reserva a SES.hospedajes con las credenciales del propietario antes de confirmar la respuesta. Si SES no responde, la reserva queda en estado guardado y el scheduler reintenta el envío cada 2 horas sin que tengas que intervenir.
¿Funciona para hoteles de Cataluña (Mossos d'Esquadra)?
Sí. Partehotel detecta automáticamente si el hotel es catalán por su código postal. Para Mossos, el fichero TXT oficial se genera y envía al propietario por email para que lo suba al portal MossosHotels, igual que con las reservas del panel.
¿Qué pasa si el saldo es insuficiente al crear una reserva por API?
La API devuelve un error 402 insufficient_balance con el importe requerido
y el saldo actual. La reserva no se crea. El propietario debe recargar saldo desde el
panel (Tarifas → Saldo) antes de volver a intentarlo.
¿Puedo crear reservas con varias habitaciones (grupos, familias)?
Sí. Incluye varias habitaciones en el array rooms de POST /hotel/reservations.
Todas las reservas del grupo compartirán el group_id de la respuesta. Todas las
reservas del grupo comparten un único parte de viajeros y un único check-in.
¿El propietario puede seguir usando el panel con la API activa?
Sí. Las reservas creadas por API aparecen en el cuadro sinóptico y el calendario del panel exactamente igual que las creadas manualmente. El propietario puede modificarlas, alojar a los huéspedes o cancelarlas desde el panel en cualquier momento.
¿Partehotel notifica los cambios de estado de las reservas en tiempo real?
Sí. Con los webhooks de Integraciones, Partehotel envía una notificación HTTP POST a la URL que configures cada vez que una reserva cambia de estado (creada, check-in del huésped, parte enviado a SES, alojado, finalizada o cancelada), así como avisos de saldo bajo y recibo emitido. Aplica a todas las reservas del hotel, no solo a las creadas por API.
¿Cómo se verifica la autenticidad de un webhook de Partehotel?
Cada entrega incluye la cabecera X-Partehotel-Signature con una firma
HMAC-SHA256 (formato t=timestamp,v1=hash) calculada con el secreto que
generas en Mi cuenta → Integraciones. Tu sistema recalcula la firma sobre el
cuerpo recibido y la compara para confirmar que el evento procede de Partehotel.
Empieza a integrar hoy
Crea tu cuenta, genera la clave API
Crea tu cuenta, genera la clave API
y envía el primer parte en minutos
Regístrate gratis, configura tus habitaciones y consulta la documentación interactiva de la API. Saldo de bienvenida incluido, sin tarjeta.
Sin tarjeta · sin cuota mensual · soporte en español
Siga explorando
También le interesa
Más recursos para la gestión de su hotel y el cumplimiento del RD 933/2021
Preguntas frecuentes
Resuelva sus dudas sobre precios, funcionamiento, SES.hospedajes y soporte.
Ver todas las FAQ →Partes automáticos
Envío automático de partes de viajeros a SES.hospedajes y Mossos d'Esquadra.
Conocer más →Precios
Pago por uso transparente, sin suscripciones ni permanencias.
Ver precios →Gestión hotelera
Habitaciones, cuadro sinóptico, tarifas por temporada y optimizador de ocupación.
Descubrir →¿Listo para empezar?
Regístrate gratis y recibe 5€ de saldo para probar sin compromiso.
Comenzar gratis →