API de réservation

L'API de réservation permet à votre backend de lire et de gérer les réservations qu'un contact a effectuées sur une campagne OmniLab — par exemple pour alimenter une page de compte qui affiche les réservations à venir d'un client et lui permet de les annuler.

Tous les endpoints sont en serveur à serveur : demandez un jeton d'accès depuis votre propre backend, puis appelez OmniLab avec un jeton bearer. N'exposez jamais le secret client dans un navigateur, une page kiosque ou un bundle d'application mobile.

URL de base et environnements

Chaque appel utilise le chemin de base /v1/ sur un hôte propre au tenant. L'hôte suit ce modèle, où <tenant> est la clé de votre tenant et <env> l'environnement :

Gardez les identifiants de préproduction et de production séparés, et développez puis testez d'abord en préproduction. Voir URL de base et environnements pour les règles plus générales.

S'authentifier

Obtenez un jeton avec le flux client-credentials, puis envoyez-le en tant que Authorization: Bearer <token> sur chaque appel de l'API de réservation.

curl -X POST "https://<api-host>/v1/oauth:token" \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "audience": "YOUR_AUDIENCE",
    "grant_type": "client_credentials"
  }'

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}

Considérez expires_in comme la durée de vie du jeton en secondes : mettez le jeton en cache sur votre backend et renouvelez-le avant son expiration, ou après une réponse 401. Toutes les consignes sur les jetons figurent dans Authentification.

Concepts clés

Avant la référence des endpoints, trois notions expliquent comment les identifiants s'articulent.

Comment un contact est identifié

En résumé : l'identifiant externe identifie la personne, et la clé publique identifie la campagne. Vous n'avez besoin de stocker que l'identifiant externe que vous possédez déjà.

Campagnes, touchpoints et identifiant d'activité

Une campagne dans OmniLab est une interaction, identifiée par sa public_key. Une interaction peut contenir une ou plusieurs activités réservables — aussi appelées touchpoints. Chaque réservation de la réponse porte un objet activity avec son propre id. Cet activity.id est l'identifiant du touchpoint, et c'est la clé pour distinguer les réservations lorsqu'une campagne comporte plusieurs activités réservables.

activity.id est unique au sein d'une campagne, pas entre campagnes — le même id peut apparaître sous deux campagnes différentes. Pour identifier un touchpoint de façon unique, utilisez activity.id avec la interaction.public_key de la campagne. Les deux cas d'usage ci-dessous le montrent en pratique.

L'identifiant de réservation et les statuts

Chaque réservation est identifiée par le champ booking — un identifiant unique (un UUID). Renvoyez cette valeur exacte pour annuler la réservation ; n'ajoutez pas de préfixe et ne la transformez pas.

Endpoints

Lister les réservations d'un contact

GET /v1/interactions:fetchContactBookings

Renvoie toutes les réservations d'un contact, avec pagination et filtres optionnels.

Paramètres de requête

curl -X GET "https://<api-host>/v1/interactions:fetchContactBookings?external_id=9b33d8c1-64bd-4eff-b0e4-d2fb29ecbe83&booking_status=CONFIRMED&page_size=50&page_number=1" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Réponse

Chaque réservation de bookings contient les champs ci-dessous. Consultez Formats et conventions des champs pour le format exact de chacun.

{
  "bookings": [
    {
      "activity": {
        "id": "b8b2a0e2-1f3c-4a7d-9c52-0c8f2d1a6e44",
        "title": "Santa Photo Experience",
        "location_hint": "Niveau 1, près de la fontaine"
      },
      "interaction": {
        "public_key": "winter-festival",
        "timezone": "Europe/London"
      },
      "group": {
        "unique_key": "example-brand",
        "display_name": "Example Brand"
      },
      "slot_starting_at": "2024-12-10T12:30:00Z",
      "slot_duration_in_minutes": 30,
      "booking_status": "CONFIRMED",
      "booked_at": "2024-12-01T09:15:00Z",
      "ticket_type": {
        "display_name": "Entrée standard",
        "has_limited_capacity": true
      },
      "host": {
        "display_name": "Photo Station 2"
      },
      "booking": "2394d604-afcc-4f7f-98c1-ef3676c20d6b"
    }
  ],
  "page_number": 1,
  "page_size": 50,
  "total_count": 1
}

Formats et conventions des champs

Envoyez aussi les filtres slot_date_range.from et slot_date_range.to en RFC 3339, en UTC.

Annuler une réservation

POST /v1/interactions:cancelInteractionBooking

Annule une réservation et ses billets. Transmettez la valeur booking renvoyée par l'appel de récupération, telle quelle.

curl -X POST "https://<api-host>/v1/interactions:cancelInteractionBooking" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "booking": "82ce03a0-939e-423f-811d-0345eacdc137"
  }'

Une annulation réussie renvoie un objet JSON vide ({}).

Cas d'usage

Campagne avec un seul touchpoint d'activité

Lorsqu'une campagne n'a qu'une seule activité réservable, toutes les réservations de la réponse partagent le même activity.id. Vous pouvez lister les réservations directement sans regroupement — chaque ligne est simplement un créneau que le contact a réservé pour cette activité.

Campagne avec plusieurs touchpoints d'activité

Lorsqu'une campagne propose plusieurs activités réservables (par exemple une photo avec le Père Noël et un atelier créatif dans la même campagne d'hiver), chaque réservation porte l'activity.id du touchpoint auquel elle appartient. Utilisez activity.id pour regrouper ou étiqueter les réservations par activité, afin que le client voie « Santa Photo Experience » et « Atelier créatif » comme des lignes distinctes plutôt qu'une liste à plat. Le champ activity.title fournit une étiquette prête à l'emploi pour chaque groupe.

Afficher les réservations sur une page de compte

Un flux typique de page de compte :

Collections Postman

OmniLab maintient une collection Postman par environnement (Développement, Préproduction/UAT et Production) couvrant tous les endpoints ci-dessus. Demandez la collection de votre environnement à votre Customer Success Manager.

Bonnes pratiques

• Effectuez l'échange de jeton sur votre backend et appelez l'API de réservation en serveur à serveur.
• Mettez le jeton d'accès en cache et renouvelez-le avant l'écoulement de expires_in ou après un 401.
• Envoyez les filtres de date (slot_date_range.from / slot_date_range.to) en UTC.
• Affichez les heures de créneau dans interaction.timezone, qui est un nom de fuseau IANA.
• Demandez confirmation au client avant d'annuler, puis rafraîchissez la liste.
• Gérez sereinement un tableau bookings vide — un contact peut n'avoir aucune réservation.

Articles liés