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

Official OCTO documentation: https://docs.octo.travel/

---

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/<teamId>/providers/<providerId>/

Variables

Variable	Description
<teamId>	Reseller team ID
<providerId>	Supplier team ID

---

Authentication

Authentication works like the Yoplanning API v3.1.

You can use:

Header Authorization Token

Authorization: Token XXXX

Header Authorization Bearer

Authorization: Bearer XXXX

---

Capabilities used

All requests use the following capabilities:

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:

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:

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:

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:

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:

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:

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:

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:

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:

/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:

https://docs.octo.travel/