Développeurs · pour Développeurs

Démarrage rapide de l'API

Q: Existe-t-il une API pour les opérateurs de plateforme ?

Oui : l'API plateforme (/api/platform/v1, clés commençant par gpp_) provisionne les comptes et les domaines. Voir la section plateforme de la référence de l'API.

Créez une clé API, faites votre premier appel, créez des réservations depuis votre PMS, lisez check-in et paiements et réagissez aux événements par webhooks.

Tout ce que fait le tableau de bord est disponible via une API REST JSON. Usages typiques : créer des réservations depuis votre PMS ou votre moteur de réservation, insérer le lien du portail voyageurs dans vos propres messages, lire les données du check-in en ligne ou récupérer la déclaration MTA dans votre comptabilité.

La référence complète se trouve sur /api/docs, lisible par machine au format OpenAPI 3.1.

1. Créer une clé API #

Settings → API keys (propriétaires uniquement) : donnez un nom et un rôle à la clé. La clé peut faire exactement ce que ce rôle peut faire — utilisez Viewer pour les intégrations en lecture seule. La clé complète (gpk_…) n'est affichée qu'une fois ; conservez-la dans votre coffre-fort de secrets. Vous pouvez la révoquer à tout moment au même endroit.

2. Faire votre premier appel #

Envoyez la clé comme jeton bearer. L'URL de base est l'adresse de votre portail.

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

La réponse indique le compte (tenant), le rôle de la clé et ses autorisations.

3. Créer une réservation #

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
  }'

Avec source + externalId, l'appel est un upsert : renvoyer la même réservation la met à jour au lieu de créer un doublon.
Des dates qui se chevauchent renvoient 409 ; ajoutez "allowOverlap": true si c'est voulu.
La réponse contient la réservation avec portalUrl — le lien personnel du voyageur.

Les identifiants des logements s'obtiennent via GET /api/v1/properties.

4. Lire l'état et les données de check-in #

GET /api/v1/bookings?from=2026-11-01&to=2026-11-30 — liste avec l'état des paiements (eco.status, deposit.status), stayState et unlocked.
GET /api/v1/bookings/{id} — réservation complète, y compris les données du check-in en ligne et le journal d'activité.
GET /api/v1/bookings?format=csv — export pour tableur.

Autres endpoints #

Endpoint	Fonction
`GET /api/v1/reports/stats?propertyId=&from=&to=`	Statistiques par logement et par période (`format=csv` pour du CSV)
`GET /api/v1/reports/owner-statement?propertyId=&from=&to=`	Relevé d'éco-contribution pour le propriétaire ; `POST …/owner-statement/send` l'envoie par e-mail
`GET`/`PUT /api/v1/properties/{id}/translations`	Les traductions du guide par langue ; `POST …/translations/auto` complète celles qui manquent
`PATCH /api/v1/settings`	Comprend `stayTimes` (arrivée anticipée/départ tardif), `journey` (messages aux voyageurs), `pushArrivalHours` et `checkin.formType` (`short` ou `long`)
`POST /api/v1/settings/journey/test`	Vous envoie une étape de la séquence de messages à titre de test
`GET /api/v1/push`, `POST /api/v1/push/subscribe`	Notifications sur téléphone de l'utilisateur connecté

L'API voyageur accepte l'en-tête X-GP-Lang (en, de, it, fr, es, nl, pl, mt) et renvoie le guide dans cette langue.

5. Réagir aux événements #

Au lieu d'interroger l'API en boucle, enregistrez un webhook (Settings → Webhooks) et recevez des événements signés comme checkin.completed, payment.completed ou feedback.received — voir Webhooks.

Conventions #

Sujet	Règle
Format	JSON en entrée et en sortie, UTF-8 ; dates `YYYY-MM-DD`, horodatages ISO 8601 UTC
Erreurs	Statut HTTP + `{ "error": "message" }` — 400 saisie invalide, 401 clé incorrecte, 403 non autorisé, 404 introuvable, 409 conflit, 429 trop de requêtes
Montants	Nombres décimaux dans la devise du compte (EUR par défaut)
Secrets	Masqués dans les réponses ; envoyez une valeur vide pour conserver un secret enregistré

Questions fréquentes #

Existe-t-il un environnement sandbox ? #

Utilisez le compte de démonstration pour explorer, et le mode sandbox de Revolut pour les paiements. Les clés API ne peuvent pas être créées dans la démo — créez un compte gratuit pour le développement.

Existe-t-il une API pour les opérateurs de plateforme ? #

Oui : l'API plateforme (/api/platform/v1, clés commençant par gpp_) provisionne les comptes et les domaines. Voir la section plateforme de la référence de l'API.