# Guía rápida de la API

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](/api/docs), también en formato legible por máquina como [OpenAPI 3.1](/api/v1/openapi.json).

## 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.

![Settings → API keys](/site/img/docs/d-settings-apikeys.webp "Settings → API keys")

## 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](/docs/statistics) 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](/docs/guest-languages) de la guía por idioma; `POST …/translations/auto` completa las que faltan |
| `PATCH /api/v1/settings` | Incluye `stayTimes` ([early/late](/docs/early-check-in-late-check-out)), `journey` ([mensajes a huéspedes](/docs/guest-message-timeline)), `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](/docs/host-app-notifications) 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](/docs/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](/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](/api/docs#platform).