Patterns d'intégration courants

Cadrez votre intégration OmniLab autour de patterns éprouvés avant d'investir dans des scripts ad hoc ou du polling agressif. Cette page regroupe les approches demandées le plus souvent.

Synchroniser un CRM ou un CDP avec des webhooks

Utilisez les webhooks lorsqu'un autre système doit réagir à des événements participant, reward, booking, ou OmniLab Smart Link sans faire de polling.

Un pattern fréquent ressemble à ceci :

Bonnes habitudes :

• séparer la réception OmniLab de l'écriture dans le CRM aval
• vérifier les signatures avant de faire entrer l'événement dans votre queue
• garder le receiver idempotent en stockant webhook-id
• ne souscrire qu'aux types d'événements réellement utiles au CRM

Exporter vers l'analytics ou un entrepôt de données

C'est le bon pattern lorsque vous voulez retrouver les données d'engagement OmniLab dans des dashboards BI, un data lake, ou un entrepôt analytique.

Types d'événements souvent utilisés ici :

• touchpoint.page_visit.v1
• touchpoint.participated.v1
• touchpoint.completed.v1
• reward.won.v1
• reward.redeemed.v1
• smartlink.redirected.v1

Préférez une ingestion événementielle à un polling très fréquent. Si vous avez quand même besoin de backfills, exécutez-les en batchs paginés hors pics de trafic.

Construire une vue self-service de booking

Ce pattern est utile lorsqu'un portail participant ou une app mobile doit afficher les réservations à venir et permettre leur annulation. Pour la référence champ par champ complète de ces endpoints, voir l'API de réservation.

1. Récupérer les bookings d'un contact

Utilisez GET https://<api-host>/v1/interactions:fetchContactBookings avec l'external ID du participant et les filtres utiles.

curl -X GET "https://<api-host>/v1/interactions:fetchContactBookings?external_id=CONTACT-123&booking_status=CONFIRMED&page_size=50&page_number=1"       -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Paramètres disponibles :

• external_id (obligatoire)
• interactions ou public_keys pour restreindre le périmètre
• slot_date_range.from et slot_date_range.to
• booking_status
• page_size
• page_number

Utilisez soit interactions, soit public_keys pour filtrer, mais pas les deux en même temps.

La réponse inclut un tableau paginé bookings avec des champs comme :

• activity
• interaction
• ticket_type
• host
• slot_starting_at
• slot_duration_in_minutes
• booking_status
• booked_at, cancelled_at, checkedin_at
• booking
• timezone

Les statuts de booking incluent CONFIRMED, CANCELLED, CHECKED_IN, et WAITLIST.

2. Annuler un booking

Utilisez POST https://<api-host>/v1/interactions:cancelInteractionBooking avec l'ID de booking renvoyé par la requête précédente.

curl -X POST "https://<api-host>/v1/interactions:cancelInteractionBooking"       -H "Authorization: Bearer YOUR_ACCESS_TOKEN"       -H "Content-Type: application/json"       -d '{
        "booking": "BOOKING_ID"
      }'

Une annulation réussie renvoie un objet JSON vide.

3. Bonnes pratiques UX pour le booking

• affichez tous les horaires dans le fuseau renvoyé par OmniLab
• demandez une confirmation avant l'annulation
• rafraîchissez la liste après une annulation réussie
• gérez proprement les listes vides
• gardez vos filtres de dates en UTC lors des appels API

Automatisation maîtrisée autour d'une campagne ou d'un système aval

Certaines équipes ont besoin d'un workflow assisté par API autour des campagnes, rewards, ou participants. Comme la référence API complète n'est pas encore publiée, le plus sûr est de garder cette automatisation explicite et bien cadrée.

• confirmez la liste des endpoints supportés avec OmniLab avant de démarrer
• placez l'automatisation derrière un feature flag côté intégrateur
• validez le flux complet en staging avant la production
• gardez des logs d'audit sur chaque action automatisée lancée par votre système

Pour aller plus loin