# Démarrage rapide de l'API

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](/api/docs), lisible par machine au format [OpenAPI 3.1](/api/v1/openapi.json).

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

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

## 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](/docs/statistics) 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](/docs/guest-languages) 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](/docs/early-check-in-late-check-out)), `journey` ([messages aux voyageurs](/docs/guest-message-timeline)), `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](/docs/host-app-notifications) 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](/docs/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](/demo) 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](/api/docs#platform).