# checkin-online.es — Referencia completa de API REST > Portal matriz del registro automático de viajeros en España. > Tres APIs REST especializadas por tipo de alojamiento para PMS, channel managers y desarrolladores. > Las APIs permiten crear reservas automáticamente en las plataformas y entregar el link de check-in > al huésped de forma transparente desde el sistema del propietario. ## Qué hace la API y qué no hace La API permite que una aplicación de terceros (PMS, channel manager, motor de reservas) cree reservas automáticamente en la plataforma correspondiente (Partes de Viajeros, Partehotel o AutoSES) sin que el propietario del alojamiento tenga que entrar al panel manualmente para cada nueva reserva. La plataforma sigue siendo necesaria para: gestionar y modificar reservas, consultar el estado de envío a SES.hospedajes, y configurar el establecimiento. El huésped nunca ha interactuado con la plataforma directamente. Siempre actúa a través del link de check-in (parte de viajeros) que recibe por email o por cualquier otro canal que el propietario elija. Con la API activada: el PMS crea la reserva → la plataforma envía el parte a SES.hospedajes → el PMS puede entregar el link de check-in al huésped directamente (modo transparente) o dejarlo a la plataforma. ## Las tres APIs ### API para apartamentos turísticos, VUT, pisos turísticos y casas rurales - Plataforma: partesdeviajeros.com - Prefijo de API key: `pw_live_` - Base URL: `https://partesdeviajeros.com/api/v1/establishments/{establishment_id}/` - Documentación OpenAPI: `https://partesdeviajeros.com/api/v1/docs` - Modelo: multi-establecimiento (un gestor, N establecimientos, una sola cuenta y API key) - Registro: https://partesdeviajeros.com/registro ### API para hoteles, hostales y pensiones - Plataforma: partehotel.com - Prefijo de API key: `ph_live_` - Base URL: `https://partehotel.com/api/v1/hotel/` - Documentación OpenAPI: `https://partehotel.com/api/v1/docs` - Modelo: single-hotel (una cuenta = un hotel; el PMS mantiene una API key por cliente) - Registro: https://partehotel.com/registro ### API para campings, bungalows y glamping - Plataforma: autoses.com - Prefijo de API key: `as_live_` - Base URL: `https://autoses.com/api/v1/camping/` - Documentación OpenAPI: `https://autoses.com/api/v1/docs` - Modelo: single-camping (una cuenta = un camping; el PMS mantiene una API key por cliente) - Registro: https://autoses.com/registro ## Quickstart — Crear una reserva ### Partehotel (hotel, hostal, pensión) ```bash curl -X POST https://partehotel.com/api/v1/hotel/reservations \ -H "Authorization: Bearer ph_live_a1b2c3d4e5f6..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \ -d '{ "establishment_id": 42, "room_id": 7, "check_in": "2026-09-01", "check_out": "2026-09-05", "board_plan": "ad", "adults": 2, "children": 1, "holder": { "name": "María", "surname": "García López", "email": "maria@ejemplo.com", "phone": "+34666123456" }, "send_checkin_email": false }' ``` Respuesta 201: ```json { "id": 1038, "status": "P", "ses_sent": true, "checkin_link": "https://partehotel.com/c/abc123", "cost_eur": 0.90 } ``` ### Partes de Viajeros (apartamento turístico, VUT, casa rural) ```bash curl -X POST https://partesdeviajeros.com/api/v1/establishments/15/reservations \ -H "Authorization: Bearer pw_live_x9y8z7w6v5u4..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6ba7b810-9dad-11d1-80b4-00c04fd430c8" \ -d '{ "accommodation_id": "hab-01", "check_in": "2026-09-01", "check_out": "2026-09-03", "num_adults": 2, "num_children": 0, "channel": "booking", "holder": { "name": "Carlos", "surname": "Martínez", "email": "carlos@ejemplo.com", "phone": "+34677654321" }, "send_checkin_email": false }' ``` Respuesta 201: ```json { "id": 874, "status": "P", "ses_sent": true, "checkin_link": "https://partesdeviajeros.com/c/xyz789", "cost_eur": 0.60 } ``` ### AutoSES (camping, bungalow, glamping) ```bash curl -X POST https://autoses.com/api/v1/camping/reservations \ -H "Authorization: Bearer as_live_m3n4o5p6q7r8..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \ -d '{ "parcel_id": 22, "check_in": "2026-08-25", "check_out": "2026-08-28", "adults": 2, "children": 1, "pets": 1, "vehicles": 1, "license_plates": ["1234ABC"], "holder": { "name": "Ana", "surname": "López", "email": "ana@ejemplo.com", "phone": "+34688112233" }, "send_checkin_email": false }' ``` Respuesta 201: ```json { "id": 512, "status": "P", "ses_sent": true, "checkin_link": "https://autoses.com/c/def456", "cost_eur": 0.50 } ``` ## Ciclo de vida de una reserva | Estado | Código | Descripción | |--------|--------|-------------| | Guardada | G | Reserva creada pero SES.hospedajes no disponible. Sin cobro de saldo. El scheduler reintenta. | | Pendiente | P | Parte enviado a SES.hospedajes. Check-in pendiente del huésped. Saldo cargado. | | Formulario completado | F | El huésped rellenó sus datos. Parte listo para segundo envío a SES. | | Esperado | E | Parte enviado a SES con datos del huésped. Huésped en camino al alojamiento. | | Alojado | I | Huésped presente en el alojamiento. | | Finalizado | O | Estancia completada. Check-out. Recibo emitido al huésped. | | Cancelada | C | Reserva cancelada. El saldo se reembolsa si el huésped no había guardado datos. | ## Endpoints comunes (ejemplo con /hotel/; sustituir prefijo según plataforma) | Método | Endpoint | Descripción | |--------|----------|-------------| | GET | /hotel/rooms | Lista habitaciones o parcelas disponibles | | GET | /hotel/availability | Consulta disponibilidad para rango de fechas | | POST | /hotel/reservations | Crea reserva. Devuelve 201 con `checkin_link` y `status: "P"` | | GET | /hotel/reservations/{id} | Estado actual de la reserva | | PUT | /hotel/reservations/{id} | Modifica fechas u ocupantes (solo en estados P o F) | | POST | /hotel/reservations/{id}/cancel | Cancela la reserva; reembolsa saldo si procede | ## Webhooks (notificaciones push en tiempo real) Las tres plataformas envían webhooks: un POST HTTPS firmado a tu servidor cada vez que ocurre un evento, sin necesidad de hacer polling. Se configuran en el panel del propietario: Mi cuenta → Integraciones (URL destino, secreto de firma, filtro de eventos, ping de prueba y registro de entregas). Eventos: | Evento | Cuándo se emite | |--------|-----------------| | `reservation.created` | Nueva reserva registrada (cualquier origen) | | `reservation.status_changed` | Cambio de estado; `data` incluye `from` y `to` (señal universal del ciclo de vida) | | `reservation.updated` | Se modifican datos de la reserva | | `reservation.cancelled` | La reserva pasa a estado C | | `guest.checked_in` | El huésped completa y firma el parte (paso a F) | | `ses.submission_succeeded` / `ses.submission_failed` | Envío del parte a SES.hospedajes / Mossos | | `balance.low` | (AutoSES, Partehotel) el saldo baja del umbral configurado | | `receipt.sent` | (AutoSES, Partehotel) recibo de estancia emitido al huésped | | `webhook.ping` | Evento de prueba desde el panel | Envoltura (envelope): `{ "id": "evt_000123", "type": "...", "created_at": "2026-08-24T10:30:00Z", "owner_id": 42, "data": { ... } }`. Deduplica por `id`. Cabeceras de cada entrega: `X--Event`, `X--Delivery` y `X--Signature` con formato `t=,v1=` (esquema Svix/Resend), donde `` es `Partesdeviajeros`, `Partehotel` o `Autoses`. Verificación de la firma (Python): ```python import hmac, hashlib def verificar_firma(secret: str, header_sig: str, body: bytes) -> bool: partes = {p.split('=')[0]: p.split('=')[1] for p in header_sig.split(',')} mensaje = f"{partes.get('t','')}.{body.decode()}".encode() esperado = hmac.new(secret.encode(), mensaje, hashlib.sha256).hexdigest() return hmac.compare_digest(esperado, partes.get('v1', '')) # Usar siempre el cuerpo RAW (sin parsear ni re-serializar) para no romper la firma. ``` Entrega: at-least-once (deduplica por `id`), hasta 8 reintentos con backoff exponencial (2^intento minutos, tope 6 h), timeout de 10 s, 30 días de retención. Responde 2xx cuanto antes y encola el trabajo pesado en segundo plano. ## Control de acceso por matrícula — barrera ANPR (solo AutoSES) AutoSES expone un endpoint para que la barrera automática del camping (sistema ANPR / cámara lectora de matrículas) consulte si una matrícula tiene acceso autorizado en ese momento: ```bash curl -X POST https://autoses.com/api/v1/camping/access/plate \ -H "Authorization: Bearer as_live_..." \ -H "Content-Type: application/json" \ -d '{"plate": "1234ABC"}' ``` Respuesta: ```json { "authorized": true, "plate": "1234ABC", "reservation": { "id": 1234, "parcela_id": 12, "parcela": "A-14", "check_in": "2025-09-01", "check_out": "2025-09-05" } } ``` `authorized` es `true` solo si la matrícula (una de las hasta 3 por reserva) pertenece a una reserva del camping en estado E (parte enviado) o I (alojado) cuya estancia incluye la fecha de hoy. La barrera debe abrir únicamente si `authorized` es `true`. Así se abre automáticamente al llegar un campista con reserva y se deniega el paso a clientes cuya estancia ya terminó. Combínalo con el webhook `reservation.status_changed` para reaccionar a las llegadas/salidas en tiempo real. ## Códigos de error frecuentes | Código HTTP | Error | Descripción | |-------------|-------|-------------| | 400 | `invalid_dates` | check_out anterior o igual a check_in | | 400 | `room_not_found` | room_id / parcel_id / accommodation_id no existe en la cuenta | | 400 | `overlap` | La habitación ya tiene una reserva en esas fechas | | 401 | `invalid_api_key` | Bearer token inválido o revocado | | 402 | `insufficient_balance` | El propietario no tiene saldo suficiente | | 409 | `idempotency_conflict` | Idempotency-Key ya usada con un body diferente | | 422 | `ses_validation_error` | Los datos no superan las 28 validaciones previas al envío a SES | | 503 | `ses_unavailable` | SES.hospedajes no responde. La reserva se crea en estado G y el scheduler reintenta. | ## Patrones de integración ### PMS con múltiples clientes hoteleros El PMS almacena la API key de cada cliente (propietario del alojamiento). Cuando llega una reserva en el PMS, ejecuta el POST usando la API key del propietario correspondiente. El coste de SES.hospedajes recae sobre el saldo de cada propietario, no sobre el PMS. Flujo: 1. El propietario crea su cuenta en partehotel.com / partesdeviajeros.com / autoses.com. 2. El propietario genera su API key desde Mi cuenta → API REST y la comunica al PMS. 3. El PMS la almacena asociada al establecimiento del cliente. 4. Por cada nueva reserva, el PMS hace POST /reservations con la API key del propietario. 5. La plataforma envía el parte a SES.hospedajes y devuelve el `checkin_link`. 6. El PMS entrega el `checkin_link` al huésped (email, SMS, WhatsApp). ### Channel manager (OTA → SES.hospedajes) El channel manager recibe la reserva desde Booking.com, Airbnb u otra OTA, y la traduce en un POST a la API. El campo `channel` en el body identifica el origen (booking, airbnb, vrbo, directo…). ### Motor de reservas en la web propia del hotel El desarrollador integra el POST al finalizar el proceso de reserva en la web del hotel. Con `send_checkin_email: false` y modo transparente activado en la cuenta, el huésped recibe el link de check-in desde el email del hotel, no desde las plataformas de checkin-online.es. ### Modo transparente El modo transparente se activa en Mi cuenta → API REST. Con él activado: - La plataforma NO envía emails de check-in al huésped. - La plataforma NO envía el recibo al huésped. - El `checkin_link` de la respuesta 201 es el enlace que el integrador debe entregar al huésped. - El envío del parte a SES.hospedajes sigue siendo automático e inmediato. Se puede sobrescribir por reserva con el campo `"send_checkin_email": false` sin activar el modo global. ## Autenticación Solo API key con esquema Bearer: ``` Authorization: Bearer ph_live_xxxxxxxxxxxx ``` No hay OAuth, tokens de corta duración ni flujo de autorización. La clave se genera desde Mi cuenta → API REST y se muestra una única vez. Guardarla en un gestor de secretos (AWS Secrets Manager, HashiCorp Vault, variables de entorno en CI/CD). Si se compromete, revocarla desde el panel — la clave anterior queda inválida de inmediato. ## Idempotencia Usar el header `Idempotency-Key: ` en todos los POST /reservations. Cualquier reintento con la misma clave dentro de 24 horas devuelve la respuesta original sin crear duplicados. Generar un UUID v4 por intento de reserva y conservarlo hasta confirmar el 201. ## Páginas de información - Portal: https://checkin-online.es/api-integracion.html - Para PMS y desarrolladores de software: https://checkin-online.es/integracion-pms-ses-hospedajes.html - Para propietarios de alojamiento: https://checkin-online.es/como-pedir-automatizacion-partes-viajeros.html ## Contacto - Email: info@checkin-online.es - Teléfono: +34 91 99 33 454 ## Plataformas - [Partes de Viajeros](https://partesdeviajeros.com) — apartamentos, VUT, pisos turísticos, casas rurales - [Partehotel](https://partehotel.com) — hoteles, hostales, pensiones, apartahoteles - [AutoSES](https://autoses.com) — campings, bungalows, glamping, autocaravanas