This tutorial will show you how to build a booking engine based on the Yoplanning API.
If you want to be able to sell Yoplanning activities in your system, you are on the right place to start.
We assume that you have read the API documentation and that you already have your API token.
We will cover the 6 steps involved in the worflow :
Retrieve your teams data
Get the list of products
Get availabilities for a specific product
(Optional) Retrieve available options (equipments)
First, you need to retrieve your teams ids to be able to make use of the API
There are 2 very important information you need to retrieve and store in your system :
team_id : You will need this id for pretty much every request on the API
vendor_id : You will need this id only if you want to use the Payment Manager for the payment - see (Optional) Handle the payment via Payment Manager
You can retrieve all your team at once using the following endpoint : /api/v3.1/teams/ (see API documentation for more details)
This step should not be done for every payment !
You should do this only once and store the team_id and vendor_id in your system.
Depending on your needs, you can also skip this step and simply ask the support (support@yoplanning.com) to give you the team_id and vendor_id for your team.
First of all, you want to know what you can sell. To do so, you will have to retrieve the list of products that can be sold online for your team.
Here is the end point you are going to use : /api/v3.1/teams/[teamId]/online-products/ (see API documentation for more details)
Example of call using Curl :
curl https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/online-products -H 'Authorization: Token 4504c2cb0d87a93106d4de029f407c86149f2ada'
Obviously, you have to replace the ID by the ID of your team and the token by the token we gave to you.
This will return a list of products (please see Pagination, Filter and expand fields in the documentation)
Each product contains a title, a description and other translatable content. You can retrieve these content in 3 different languages : french, english and deutsch.
To do so, just give an additional query parameter with the language code (ISO 2).
Example : curl https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/online-products?lang=fr -H 'Authorization: Token 4504c2cb0d87a93106d4de029f407c86149f2ada'
You can also filter by category. If you want to do so, you will need to contact us to know the category IDs.
You can now display the list of products.
The next step is to retrieve the availabilities (sessions) for a given product.
Basically, when the user will click on a product, you are going to display the availabilities for this product.
Here is the end point you are going to use : /api/v3.1/teams/[teamId]/online-products/[productId]/availabilities/ (see API documentation for more details)
Example of call using Curl :
curl https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/online-products/f16ed6c6-e972-4232-b452-ecd393e61642/availabilities -H 'Authorization: Token 4504c2cb0d87a93106d4de029f407c86149f2ada'
Obviously, you have to replace the team ID(5a90332e-568f-4980-9859-88a984844a4d), product ID(f16ed6c6-e972-4232-b452-ecd393e61642) and token.
You can filter by date, price, number of tickets, staff (instructor) etc...
For each availability, you will get the associated prices. The "standard price" is the default price. This is the price everyone will get without anything else specified.
The "other prices" are a set of prices that can be choosen for each participant. For example : child price, member price, etc...
You can now display the availabilities.
In case the team is selling/renting equiments along with sessions, you might want to present them to the purchaser after he or she
chose an availability from the list retrieved in the previous step ("Get availabilities for a product").
To do so, you will need to retrieve the details of the desired availability using the following endpoint : /api/v3.1/teams/[teamId]/availability-details/[pk]/
Replace with the "session_group" id you retrieved from the previous call ("Get availabilities for a product").
This endpoint will give you all you need about the different options available. The current stock is taken into account so only the available equipments will be in the response.
For more information about what is an option, how you should diplay them and what's the json structure,
please refer to the API documentation.
Here is an example using CURL :
curl https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/availability-details/374facd3-df50-4295-a0ff-7b90eb6a26e2/ -H 'Authorization: Token 4504c2cb0d87a93106d4de029f407c86149f2ada'
You can now display each option as a dropdown. When you will finally create the order, you will use the "id" retrieved here to fill the "resource" field.
And you will use the "session_group" id to fill the "resource_target_group". Please take a look at the last step "Place the order" and to the API documentation (/orders) for more information.
If you have a lot of customers making bookings at the same time, you might want to increase the robustness of the system to avoid overbooking.
To do so, you can simply check that the cart content is still available before checkout.
Here is the end point we are going to use : /api/v3.1/teams/[teamId]/order-validation
You just need to send the exact same JSON you would send to place an order (see below : "Place the order").
The only difference is the URL.
Here is an example using CURL :
curl -H "Content-Type: application/json" -X POST -d '{"external_reference" : "956", "items" : [{"session_group" : "53071a97-0c2d-4973-89f5-cafd10665b3b", "price" : {"amount" : 51.25}, "client" : {"id" : "71ea849f-226c-4302-a433-528179634aa7", "first_name" : "John", "last_name" : "Doe", "email" : "john.doe@gmail.com"}}], "payments" : [{"amount" : 51.25, "client" : {"first_name" : "Framold", "last_name" : "Doe", "email" : "john.doe@gmail.com"}}]}' https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/order-validation -H 'Authorization: Token 4504c2cb0d87a93106d4de029f407c86149f2ada'
If everything is still available (most of the time), you should receive this answer :
{
"success": true
}
If some items are not available anymore, you should receive an answer similar to this one :
{
"success": false,
"unavailable_items": {
"group_ids": ["2265cac0-cba5-46eb-8095-b89f93e7473f"],
"dry_resource_ids": [],
"voucher_ids": [],
"resources": []
}
} if success is true, you can proceed to the next step.
Before getting started, make you sure you have stored the vendor_id in your system (see step 1 : Retrieve your teams data)
Once the cart is ready, the next step is to checkout and proceed to payment.
To handle your client payment, you have 2 options : you can use your own payment solution or you can use the Payment Manager provided by Yoplanning.
If you choose to use the Payment Manager, here is the workflow you need to implement :
Create a payment and retrieve the payment link
Redirect your client on the payment link
handle the IPN (Instant Payment Notification)
First, you need to create a payment To do so, you will use another API and thus another base URL : https://payment.yoplanning.pro/api/ The endpoint we are going to use here is : https://payment.yoplanning.pro/api/create-payment We are going to use the POST HTTP method because we want to create a new payment.
You will need to setup a callback url on your system. This url must be reachable without authentication and must accept POST requests.
Once the payment is done, you will receive an IPN on this url.
Here is the JSON data you can provide :
{
"order_id": (required) This is the order id in your system
"vendor_id":(required) This is your vendor id
"price": (required)
"currency": (required)
"callback_url": (required) Once the payment is done, you will receive an IPN on this url
"redirection_url": When the payment is done, the user will be redirected to this URL
"cancel_url" : The user will be redirected on this url if the payment is cancelled
"payer_email": used to pre-fill the payment form
"cardholder_first_name": used to pre-fill the payment form
"cardholder_last_name": used to pre-fill the payment form
"billing_address_line1":
"billing_address_line2":
"billing_address_city":
"billing_address_postal_code":
"billing_address_country":
"billing_address_state":
}
Example of call using Curl :
curl -H "Content-Type: application/json" -X POST -d '{"order_id": "RFGYJ52","vendor_id": "a3dfc41e-5869-42d1-a8ec-a1d0280dcbf8","price": 59.84,"currency": "EUR","callback_url": "https://mysite.com/payment-callback","redirection_url": "https://mysite.com/payment-redirection","cancel_url" : "https://mysite.com/payment-cancelled","payer_email": "yousef.dupond@gmail.com","cardholder_first_name": "Yousef","cardholder_last_name": "Dupond","billing_address_line1": "7 route du chef-lieu","billing_address_city": "Annecy","billing_address_postal_code": "74000", "billing_address_country": "FR"}' https://payment.yoplanning.pro/api/create-payment -H 'Authorization: Token 3ef270c8a2ed6e15207ba8b0dab59ed7eb872ae8'Be careful : the header "Content-Type: application/json" is important.
Here is an example of answer you should get :
{
"payment_solution": "Stripe",
"vakario_fee": "1.40",
"customer_id": null,
"success": true,
"payment_id": "18135b43-f61b-4041-b89c-98c7086e8f68",
"payment_url": "https://payment.yoplanning.pro/pay/3be2d0a0-f9a2-4fb0-aba2-bc3301c399c9"
}
if success is true, you can proceed to the next step.
Redirect the client on the payment page All you need to do is redirecting the client on the payment_url received in the previous step.
Handle the IPN When the payment is done, you will receive an Instant Payment Notification on the callback_url you provided when you created the payment.
The callback url must be accessible by POST without authentication.
here is an example of the IPN JSON data you should receive :
{
'title': null,
'payment_solution': 'Stripe',
'card_brand': null,
'success': True,
'payer_lang': 'fr',
'id': '3d23247e-6115-4f2a-9258-f8071c0d0e07',
'seller_id': null,
'order_id': 'E816E3DA',
'payed': true,
'payment_method': null
}
if success is true, you can proceed to the next step.
Once the client has paid his cart, you will basically want to place an order to Yoplanning. When you place an order, the team planning is updated, the order & participants are displayed in Yoplanning, the staffs are notified, the availabilities are updated for the future bookings, etc...
Here is the end point you are going to use : /api/v3.1/teams//orders/ (see API documentation for more details)
For the previous 2 calls, we used the HTTP method GET (because we wanted to retrieve data).
This time, we are going to use POST method because we want to add a new order.
Example of call using Curl :
curl -H "Content-Type: application/json" -X POST -d '{"external_reference" : "956", "items" : [{"session_group" : "4f655815-58d9-4c7c-b1c9-2ea152073371", "price" : {"amount" : 51.25}, "client" : {"id" : "71ea849f-226c-4302-a433-528179634aa7", "first_name" : "John", "last_name" : "Doe", "email" : "john.doe@gmail.com"}}], "payments" : [{"amount" : 51.25, "client" : {"first_name" : "Framold", "last_name" : "Doe", "email" : "john.doe@gmail.com"}}]}' https://yoplanning.pro/api/v3.1/teams/5a90332e-568f-4980-9859-88a984844a4d/orders -H 'Authorization: Token 4504c2cb0d87a93106d4de029f407c86149f2ada'
Obviously, you have to replace the team ID(5a90332e-568f-4980-9859-88a984844a4d) and token.
Be careful : the header "Content-Type: application/json" is important.
The session-group correspond to the session-group of an availability.