> For the complete documentation index, see [llms.txt](https://docs.yoplanning.support/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yoplanning.support/developpeur/api-octo-yoplanning-workflow-de-vente-standard.md). # 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](https://certify.octo.travel/verify/d1a59704-1654-4385-874c-02a5b5939bad) Documentation officielle OCTO : *** ### 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 ``` https://yoplanning.pro/api/octo/teams//providers// ``` #### Variables | Variable | Description | | -------------- | ------------------------- | | `` | ID de la team revendeur | | `` | ID de la team fournisseur | *** ### Authentification L’authentification fonctionne comme l’API Yoplanning v3.1. Vous pouvez utiliser : #### Header Authorization Token ```http Authorization: Token XXXX ``` #### Header Authorization Bearer ```http Authorization: Bearer XXXX ``` *** ### Capabilities utilisées Toutes les requêtes utilisent les capabilities suivantes : ```http Octo-Capabilities: pricing,content ``` 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 : ``` /products ↓ /availability/calendar (optionnel) ↓ /availability ↓ /booking ↓ /confirm ``` Workflow d’annulation : ``` /cancel ``` Workflow de notifications : ``` /notifications/subscriptions ``` *** ### 1. Récupérer les produits Endpoint : ```http GET /products ``` 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 : ```http POST /availability/calendar ``` 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 : ```http POST /availability ``` 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 : ```http POST /booking ``` Cette route crée une réservation temporaire. La commande est créée avec le statut : ``` ON_HOLD ``` 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 : ```http POST /confirm ``` 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 : ```http POST /cancel ``` 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 : ```http POST /extend ``` 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 : ```http POST /notifications/subscriptions ``` 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 : ``` 30 minutes ``` 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 : ```http /availability ``` 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 : --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.yoplanning.support/developpeur/api-octo-yoplanning-workflow-de-vente-standard.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.