For this guide, we will refer to the main Provider as "Provider A", and another provider as "Provider B". You will use the x-api-key for "Provider A" for the whole purchase process.
In order for these two providers to be considered as Interline "partners", they both have to be invited and configured.
If a product from any provider is added first, it will create another transaction containing only accounting items. If all of the provider items are deleted, the transaction will be deleted unless it contains items that belongs to you.
Please make sure you read the Conventions before continuing with this guide.
Prerequisites
You will need an X-API-KEY and a username and password to authenticate.
Steps to complete a purchase
1) Select a product
Get the list of configured products, select one, and remember its _id. The product that you select will determine which Fares (and Fare Classes, if in use) are available when performing a Trip Search and making a purchase.
If you have configured Fare Classes for your passengers, you must select a product with pricingType = "journey" to make use of Fare Classes in the following steps.
2) Get fares
Get available fares for the product that you have selected, using your product's _id as a filter parameter.
3) Select an origin station
Get all possible origin stations for your selected product.
Select an origin station, and remember its _id.
4) Select a destination station
After selecting an 'origin' station, get all possible destination stations that can be reached from that starting point.
This endpoint does not guarantee that there are schedules available between the origin and destination stations - this can only be determined by performing a Trip Search.
Select a destination station, and remember its _id - this will be needed when searching for Trips.
5) Find and select available trips
Find trips that are available for your selected product, fares, origin, destination, and travel date(s).
From the results, select a single departure trip. If searching for a round-trip, also select a return trip. Remember each trip id, a long hash that will look something like this:
{
"id": "eyJhY2NvdW50SWQiOiI1OTEwY2ZiYWZhMWI5MDRkMGMwMDAwMTUiLCJwcm9kdWN0SWQiOiI1OTEwY2ZiYWZhMWI5MDRkMGMwMDAwMTYiLCJvcmlnaW5JZCI6IjU5MjQ1OTBlOTk4MmNmMjA3YzBkZjQwMCIsImRlc3RpbmF0aW9uSWQiOiI1OTI0NTkyODk5ODJjZjIwN2MwZGY0MDEiLCJmYXJlSWRzIjoiNTkyNDViNTc5OTgyY2YyMDdjMGRmNDAyOjEiLCJkZXBhcnR1cmVEYXRlIjoiMjAxNy0xMC0yOCIsImRlcGFydHVyZVRpbWUiOiIwOTowMCIsImNoYW5uZWwiOiJ3ZWJzYWxlcyIsInNlZ21lbnRzIjpbeyJyb3V0ZUlkIjoiNTkyNDU5NDE1MDJjYzcxMDcyMDAwMDFlIiwic2NoZWR1bGVJZCI6IjU0MGZkNWQ5LThiZDEtNGIxNS05ZDZlLTJiNzk3ZmFhYWM1NyIsIm9yaWdpbiI6IkJlcmxpbiBDZW50cmFsIGJ1cyBzdGF0aW9uIChaT0IpIiwiZGVzdGluYXRpb24iOiJXYXJzYXcgV2VzdCBidXMgc3RhdGlvbiJ9XSwidGlja2V0VHlwZSI6Im9uZXdheSJ9"
}
If Fare Classes are being used, you will need to select the passenger's desired Fare Class . Select only one Fare Class from the trip search results, and remember it's id. The id will need to be specified when adding the item to the shopping cart.
At this time, if you are searching for a round-trip, the Fare Class that is selected for the passenger's Outbound and Return Trip must be the same.
6) Add an item to the cart
Add the selected trip to the shopping cart.
Remember the cartId and the total from the response. You will need this information to complete the order.
7) Repeat steps 1-6, but use a product from Provider B
Items added for "Provider B" will need to include that provider's id.
To see the API calls in action, you can look at the Postman collection at the bottom of this document.
8) Retrieve payment types
To complete the order, first retrieve the available payment types and select one.
9) Get country and province information
Get our list of country and province information, and remember the result. You will need a valid Country Code and Province when paying for the order, in the next step.
10) Complete the order
Create an order (pay for the items in the cart) using one of the available payment types.
Once the payment is accepted, the booking is complete.
11) Download tickets
In some cases you may want to download tickets for the booking. The tickets are downloaded as PDF files.
12) Postman resources
If you would like to use Postman to test the API, we have included a collection you can use as a starting point below.
This collection is designed to allow you to purchase two one way trip reservations as a customer, with each product being from a different provider. In order to use it successfully, you will need your x-api-key, and valid stations and routes set up. In this example, we create a customer, but you can use an existing customer if you prefer.
After importing the collection, and the environment, make sure your collection is using the new environment, and that you have set the values. Variables that start with "YOUR_" will need to be replaced with a value specific to your situation. If you are going to be using our API in sandbox, please change the {{basePath}} environment variable to https://sandbox-api.betterez.com.