Ctrlk
Go to Yoplanning.pro
For the complete documentation index, see llms.txt. This page is also available as Markdown.

API OCTO Yoplanning - Workflow de vente standard

Présentation

Yoplanning propose une implémentation de l’API OCTO pour permettre la revente d’activités entre teams.

Cette documentation présente le workflow standard de vente, d’annulation et de notifications webhook.

Cette implémentation suit les standards OCTO Travel. Certification Officiel OCTO

Documentation officielle OCTO : https://docs.octo.travel/

Pré-requis

Avant d’utiliser l’API OCTO Yoplanning, les configurations suivantes doivent être en place dans Yoplanning :

  • Une team de revente (teamId)

  • Une team fournisseur (providerId)

  • Un token API de type run user créé sur la team de revente

  • Le provider doit :

    • avoir ajouté le revendeur dans sa team

    • avoir configuré les produits accessibles à la revente

URL de base

Variables

Variable
Description

<teamId>

ID de la team revendeur

<providerId>

ID de la team fournisseur

Authentification

L’authentification fonctionne comme l’API Yoplanning v3.1.

Vous pouvez utiliser :

Header Authorization Token

Header Authorization Bearer

Capabilities utilisées

Toutes les requêtes utilisent les capabilities suivantes :

Ces capabilities permettent de récupérer :

  • les informations tarifaires

  • les contenus marketing des produits

  • les données descriptives des disponibilités

Workflow standard supporté

Le workflow standard supporté par Yoplanning est le suivant :

Workflow d’annulation :

Workflow de notifications :

1. Récupérer les produits

Endpoint :

Ce endpoint permet de récupérer les produits disponibles à la vente.

Utilisation

Le revendeur utilise cette route pour :

  • afficher le catalogue fournisseur

  • récupérer les options

  • récupérer les unités tarifaires

  • afficher les contenus marketing

2. Afficher un calendrier de disponibilité (optionnel)

Endpoint :

Cette étape est optionnelle.

Elle permet d’afficher :

  • les dates disponibles

  • les prix “à partir de”

  • un calendrier de réservation

Bonnes pratiques

Utilisez cette route pour :

  • afficher un calendrier mensuel

  • précharger les disponibilités

  • améliorer les performances côté front

3. Vérifier les disponibilités

Endpoint :

Cette étape est obligatoire.

Elle permet de récupérer :

  • les créneaux disponibles

  • les horaires

  • les capacités

  • les prix exacts

  • l’availabilityId

L’availabilityId est obligatoire pour créer une réservation.

Recommandation importante

Le mieux est de transmettre les units (nombre de participants).

Cela permet :

  • d’obtenir le meilleur prix

  • de récupérer les bonnes disponibilités

  • de calculer correctement les capacités

4. Réserver les places

Endpoint :

Cette route crée une réservation temporaire.

La commande est créée avec le statut :

Le statut ON_HOLD signifie :

  • les places sont bloquées

  • la réservation n’est pas encore confirmée

  • la commande expire automatiquement après 30 minutes si elle n’est pas confirmée

Important

À cette étape :

  • la réservation existe déjà

  • les places sont sécurisées

  • le paiement peut être finalisé côté revendeur

5. Confirmer la commande

Endpoint :

Cette étape finalise la réservation.

Une fois confirmée :

  • la commande devient définitive

  • les billets peuvent être générés

  • la réservation est terminée

Important

La confirmation est simple :

  • elle confirme uniquement la commande existante

  • il n’est pas possible de modifier le contenu de la commande à cette étape

6. Annuler une commande

Endpoint :

Cette route permet d’annuler une réservation.

Important

Attention à respecter la politique d’annulation de la structure fournisseur si le booking est déjà confirmé.

Selon les règles du fournisseur :

  • des frais peuvent être appliqués

  • l’annulation peut être interdite

  • des conditions spécifiques peuvent exister

Le revendeur doit vérifier les règles d’annulation avant de proposer l’action au client final.

Étendre la réservation (optionnel)

Endpoint :

Cette route permet d’étendre la durée du statut ON_HOLD.

Exemple :

  • attente de paiement

  • validation client en cours

  • délai supplémentaire nécessaire

Le booking doit être encore valide au moment de l’appel.

Notifications webhook

Endpoint :

Cette route permet de s’inscrire aux webhooks OCTO.

Les webhooks permettent de recevoir des notifications concernant :

  • les produits

  • les disponibilités

  • les bookings

Fonctionnement

Les données complètes des objets ne sont pas directement envoyées dans le webhook.

Le webhook contient les informations nécessaires pour rappeler les endpoints concernés et récupérer les mises à jour.

Bonnes pratiques

Après réception d’un webhook :

  • rappeler le endpoint concerné

  • recharger les données à jour

  • ne pas utiliser le webhook comme source complète de données

Gestion de l’expiration des réservations

Une réservation non confirmée est automatiquement supprimée après expiration.

Par défaut :

Le revendeur doit donc :

  • confirmer rapidement les commandes

  • gérer correctement les délais de paiement

  • utiliser /extend si nécessaire

Bonnes pratiques

Toujours utiliser /availability

Même si vous utilisez /availability/calendar, il faut toujours appeler :

avant /booking.

Cette route fournit l’availabilityId nécessaire à la réservation.

Envoyer les unités tarifaires

Transmettez toujours les unités (units / participants).

Cela améliore :

  • le calcul tarifaire

  • les disponibilités

  • les règles de capacité

Gérer les expirations côté front

Affichez un timer visible lorsque la commande est en ON_HOLD.

Recharger les données après webhook

Les webhooks servent uniquement de notification.

Rechargez toujours les données via les endpoints API concernés.

Documentation officielle OCTO

Le détail complet des endpoints ainsi que l’architecture OCTO sont disponibles ici :

https://docs.octo.travel/

PrécédentBrique technologique de planification
SuivantSe connecter à Yoplanning via MCP

Mis à jour