> 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/en/developpeur/api-octo-yoplanning-workflow-de-vente-standard.md). # API OCTO Yoplanning - Workflow de vente standard ### Presentation Yoplanning offers an implementation of the OCTO API to enable the resale of activities between teams. This documentation presents the standard workflow for sales, cancellations, and webhook notifications. This implementation complies with OCTO Travel standards. [Official OCTO Certification](https://certify.octo.travel/verify/5065485c-5142-4814-91b7-1dd63777a741) Official OCTO documentation: *** ### Prerequisites Before using the OCTO Yoplanning API, the following configurations must be in place in Yoplanning: * A resale team (`teamId`) * A supplier team (`providerId`) * An API token of type `run user` created on the resale team * The provider must: * having added the reseller to his team * having configured the products available for resale *** ### base URL ``` https://yoplanning.pro/api/octo/teams//providers// ``` #### Variables | Variable | Description | | -------------- | ---------------- | | `` | Reseller team ID | | `` | Supplier team ID | *** ### Authentication Authentication works like the Yoplanning API v3.1. You can use: #### Header Authorization Token ```http Authorization: Token XXXX ``` #### Header Authorization Bearer ```http Authorization: Bearer XXXX ``` *** ### Capabilities used All requests use the following capabilities: ```http Octo-Capabilities: pricing,content ``` These capabilities allow you to retrieve: * pricing information * product marketing content * descriptive data on availability *** ### Standard workflow supported The standard workflow supported by Yoplanning is as follows: ``` /products ↓ /availability/calendar (optionnel) ↓ /availability ↓ /booking ↓ /confirm ``` Cancellation workflow: ``` /cancel ``` Notification workflow: ``` /notifications/subscriptions ``` *** ### 1. Retrieve the products Endpoint: ```http GET /products ``` This endpoint allows you to retrieve products available for sale. #### Use The reseller uses this route to: * display the supplier catalog * retrieve the options * retrieve the tariff units * display marketing content *** ### 2. Display an availability calendar (optional) Endpoint: ```http POST /availability/calendar ``` This step is optional. It allows you to display: * available dates * prices “starting from” * a booking calendar #### Best practices Use this route to: * display a monthly calendar * Preload availability * improve front-side performance *** ### 3. Check availability Endpoint: ```http POST /availability ``` This step is mandatory. It allows you to retrieve: * the available time slots * the schedules * the capabilities * the exact prices * the `availabilityId` The `availabilityId` is required to create a reservation. #### Important recommendation The best way is to transmit the `units` (number of participants). This allows: * to get the best price * to recover the good availability * to correctly calculate the capacities *** ### 4. Reserve seats Endpoint: ```http POST /booking ``` This route creates a temporary reservation. The order is created with the status: ``` ON_HOLD ``` The `ON_HOLD` status means: * The seats are blocked. * The reservation is not yet confirmed. * The order expires automatically after 30 minutes if it is not confirmed. #### Important At this stage: * the reservation already exists * The spaces are secure. * The payment can be finalized on the reseller's side. *** ### 5. Confirm the order Endpoint: ```http POST /confirm ``` This step finalizes the booking. Once confirmed: * the order becomes final * Tickets can be generated * The reservation is complete. #### Important The confirmation is simple: * It only confirms the existing order * It is not possible to modify the order content at this stage *** ### 6. Cancel an order Endpoint: ```http POST /cancel ``` This route allows you to cancel a reservation. #### Important Be sure to respect the cancellation policy of the provider if the booking is already confirmed. According to the supplier's rules: * Fees may apply * Cancellation may be prohibited * specific conditions may exist The reseller must check the cancellation rules before offering the action to the end customer. *** ### Extend the reservation (optional) Endpoint: ```http POST /extend ``` This route allows extending the duration of the `ON_HOLD` status. Example : * payment pending * Customer validation in progress * Additional time needed The booking must still be valid at the time of the call. *** ### Webhook notifications Endpoint: ```http POST /notifications/subscriptions ``` This route allows you to register for OCTO webhooks. Webhooks allow you to receive notifications about: * the products * availability * bookings #### Functioning The complete object data is not sent directly to the webhook. The webhook contains the information needed to recall the relevant endpoints and retrieve updates. #### Best practices After receiving a webhook: * recall the endpoint in question * reload the latest data * Do not use the webhook as your complete data source *** ### Managing reservation expirations An unconfirmed reservation is automatically deleted after expiry. By default: ``` 30 minutes ``` The reseller must therefore: * quickly confirm orders * manage payment deadlines properly * use `/extend` if necessary *** ### Best practices #### Always use `/availability` Even if you use `/availability/calendar`, you still need to call: ```http /availability ``` before `/booking`. This route provides the `availabilityId` necessary for booking. #### Send the tariff units Always transmit the units (`units` / participants). This improves: * tariff calculation * availability * the capacity rules #### Managing exhalations on the front side Display a timer visible when the command is in `ON_HOLD`. #### Reload data after webhook Webhooks are used solely for notifications. Always reload the data via the relevant API endpoints. *** ### Official OCTO documentation Full details of the endpoints and the OCTO architecture are available here: --- # 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/en/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.