Patterns d'intégration courants

Ce guide regroupe les patterns d'intégration demandés le plus souvent. Utilisez-le pour cadrer votre architecture avant d'investir dans des scripts ad hoc ou du polling agressif.

Pattern 1 : 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 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

Pattern 2 : 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.

Pattern 3 : 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.

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 actuels 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

Pattern 4 : 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