Desarrolladores · para Desarrolladores

Guía rápida de la API

Q: ¿Hay una API para operadores de la plataforma?

Sí: la API de plataforma (/api/platform/v1, claves que empiezan por gpp_) da de alta cuentas y dominios. Consulta la sección de plataforma de la referencia de la API.

Crea una clave de API, haz tu primera llamada, crea reservas desde tu PMS, consulta el check-in y los pagos y reacciona a eventos con webhooks.

Todo lo que hace el panel está disponible como API REST en JSON. Usos habituales: crear reservas desde tu PMS o motor de reservas, incluir el enlace al portal del huésped en tus propios mensajes, leer los datos del check-in online o pasar la declaración a la MTA a contabilidad.

La referencia completa está en /api/docs, también en formato legible por máquina como OpenAPI 3.1.

1. Crea una clave de API #

Settings → API keys (solo owners): asigna a la clave un nombre y un rol. La clave puede hacer exactamente lo que puede hacer ese rol; usa Viewer para integraciones de solo lectura. La clave completa (gpk_…) se muestra una sola vez; guárdala en tu gestor de secretos. Puedes revocarla allí en cualquier momento.

2. Haz tu primera llamada #

Envía la clave como bearer token. La URL base es la dirección de tu portal.

curl https://stay.example.com/api/v1/me \
  -H "Authorization: Bearer gpk_xxxxxxxxxxxx"

La respuesta indica la cuenta (tenant), el rol de la clave y sus permisos.

3. Crea una reserva #

curl -X POST https://stay.example.com/api/v1/bookings \
  -H "Authorization: Bearer gpk_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "propertyId": "p_xxxxxxxxxx",
    "checkIn": "2026-11-18", "checkOut": "2026-11-23",
    "adults": 2, "children": 0,
    "guest": { "firstName": "Sofia", "lastName": "Rossi", "email": "sofia@example.com", "phone": "+39 333 1234567" },
    "source": "mypms", "externalId": "RES-48213",
    "sendPortalLink": true
  }'

Con source + externalId la llamada es un upsert: si vuelves a enviar la misma reserva, se actualiza en lugar de crear un duplicado.
Las fechas solapadas devuelven 409; añade "allowOverlap": true si es intencionado.
La respuesta contiene la reserva con portalUrl, el enlace personal del huésped.

Los IDs de los alojamientos se obtienen con GET /api/v1/properties.

4. Consulta el estado y los datos del check-in #

GET /api/v1/bookings?from=2026-11-01&to=2026-11-30: lista con estados de pago (eco.status, deposit.status), stayState y unlocked.
GET /api/v1/bookings/{id}: reserva completa, incluidos los datos del check-in online y el registro de actividad.
GET /api/v1/bookings?format=csv: exportación a hoja de cálculo.

Más endpoints #

Endpoint	Qué hace
`GET /api/v1/reports/stats?propertyId=&from=&to=`	Estadísticas por alojamiento y periodo (`format=csv` para CSV)
`GET /api/v1/reports/owner-statement?propertyId=&from=&to=`	Liquidación de la ecocontribución para el propietario; `POST …/owner-statement/send` la envía por email
`GET`/`PUT /api/v1/properties/{id}/translations`	Las traducciones de la guía por idioma; `POST …/translations/auto` completa las que faltan
`PATCH /api/v1/settings`	Incluye `stayTimes` (early/late), `journey` (mensajes a huéspedes), `pushArrivalHours` y `checkin.formType` (`short` o `long`)
`POST /api/v1/settings/journey/test`	Te envía un paso de la secuencia de mensajes como prueba
`GET /api/v1/push`, `POST /api/v1/push/subscribe`	Notificaciones en el móvil del usuario que ha iniciado sesión

La API del huésped acepta la cabecera X-GP-Lang (en, de, it, fr, es, nl, pl, mt) y devuelve la guía en ese idioma.

5. Reacciona a eventos #

En lugar de consultar periódicamente, registra un webhook (Settings → Webhooks) y recibe eventos firmados como checkin.completed, payment.completed o feedback.received; consulta Webhooks.

Convenciones #

Tema	Regla
Formato	JSON de entrada y salida, UTF-8; fechas `YYYY-MM-DD`, marcas de tiempo ISO 8601 UTC
Errores	Estado HTTP + `{ "error": "message" }`: 400 entrada no válida, 401 clave incorrecta, 403 no permitido, 404 no encontrado, 409 conflicto, 429 demasiadas solicitudes
Dinero	Números decimales en la moneda de la cuenta (EUR por defecto)
Secretos	Enmascarados en las respuestas; envía un valor vacío para conservar un secreto guardado

Preguntas frecuentes #

¿Hay un entorno sandbox? #

Usa la cuenta demo para explorar y el modo sandbox de Revolut para los pagos. En la demo no se pueden crear claves de API: crea una cuenta gratuita para desarrollo.

¿Hay una API para operadores de la plataforma? #

Sí: la API de plataforma (/api/platform/v1, claves que empiezan por gpp_) da de alta cuentas y dominios. Consulta la sección de plataforma de la referencia de la API.