Purpose

OpenAPI Documentaition

The BoB Booking API supports booking of Demand Responsive Transport, a form of transport which needs to be requested in advance and is not scheduled in a timetable. It can be added as a request to an ordinary combined journey.

When a travel is requested from the sales channel the Product API uses the optional field bookingRequired to tell the sales channel that it has to call the Booking API. The sales channel requests a booking for the trip chosen by the traveller which results in a preliminary booking of the Demand Responsive Transport part of the journey. The sales channel requests the ticket for the given manifest from the Ticket API. The ticket (MTB) is returned from the Ticket API. The sales channel calls Booking API to confirm the preliminary booking. MTB is attached as proof of purchase. A confirmation is received that the booking is confirmed by the Booking API. When the traveler has completed the payment the sales channel presents the ticket to the traveler.

For implemenentation and documentation details for each API request described on this page please see OpenAPI specifcation for that specific API.

Bob Booking API

Booking

Additional API used

Use Case - "Traveller requests a ticket for a combined journey including Demand Responsive Transport"

The following example is provided as guidance for implementation supporting combined journeys including demand responsive transport.

Traveller buys a ticket for a trip from A to D via B and C. In other words, a trip with three legs A-B-C-D. The trip begins and ends with Demand Responsive Transport.

Prerequisite

An input from a journey planner for a journey from start to end is needed before a ticket can be requested.

Sequence diagram

Expand for sequence diagram code

For editing of sequence diagram - Use below code in: https://sequencediagram.org/

title Booking

participantspacing equal

actor "Traveller" as traveller
participant "Sales Channel\n" as sales
participant "Authentication API\n(Sales)" as auth_api#C2EDFE
participant "Payment Service\n Provider" as psp_api
participant "Product API\n(Ticket issuer)" as product_api#C2EDFE
participant "Booking API\n(Ticket issuer)" as booking_api#C2EDFE
participant "Ticket API\n(Ticket issuer)" as ticket_api#C2EDFE

autonumber

sales->auth_api: Request JWT
auth_api-->sales: JWT

traveller->sales: Request ticket for trip A-D

sales->product_api: Request products (with certain criterias)
product_api-->sales: A list of products matching search

sales-->traveller: Return price and options A-D
traveller->sales: Selects trip X

sales->product_api: Request manifest valid for A-D
product_api-->sales: Manifest valid for A-D

sales->booking_api: Request booking for X (since bookingRequired is true for the product)
booking_api-->sales: Preliminary booking for X (with details/conditions)

sales-->traveller: Display booking-related\ndetails/conditions for trip X

traveller->sales: Confirms booking details

sales->psp_api: Reserve payment for X
psp_api-->sales:Payment reserve for X

sales->ticket_api: Request ticket given manifest
ticket_api-->sales: MTB valid for X

sales->booking_api: Confirm preliminary booking for X on given MTB
booking_api-->sales: Booking confirmed

sales->psp_api: Request payment for X
psp_api-->sales: Payment received for X

sales-->traveller: MTB valid for X

Sequence Steps

Sales channel calls Authentication API for creation of JWT (JSON Web Token).
JWT is returned to Sales channel.
Traveller asks Sales channel for a ticket from A to D. The request contains certain criteria, for example desired date and time.
Sales channels calls Product API for products matching the desired criteria.
A list of products is returned to sales channel.
Customers is presented the products with prices and options for a trip from A to D.
Traveller choses to buy a trip X (which will later produce a bundled ticket for the trip A-B-C-D).
Sales channel requests manifest for the selected ticket X from the Product API.
Manifest is returned to Sales channel. Within the manifest are details for all legs to make the trip complete. The response contains attribute bookingRequired = true.
Sales channel requests a booking for trip X. A booking call is made to booking API. Within the booking call is also the manifest containing details about trip A-B-C-D.
Booking API returns a preliminary booking with details and conditions for trip X.
The preliminary booking is displayed to the Traveller.
Traveller confirm booking details and agrees to pay.
Sales channel reserves amount for the payment of ticket X.
Sales channel receives a confirmation that amount has been reserved
Sales requests the actual ticket for the given manifest from Ticket API
The actual bundled ticket (MTB) valid for all legs (A-B-C-D) is returned from Ticket API.
Sales channel calls Booking API to confirm the preliminary booking requested in step 10. MTB is attached as proof of purchase.
A confirmation is received that the booking is confirmed by the Booking API.
The payment transaction is completed.
A confirmation is received that the payment is made.
The ticket bundle (MTB) for A-B-C-D is delivered to customer.

Notes:

Step 10 is likely to be one call, however depending on implementation there may be subsequent calls.
Step 10-11 and 18-19 may be treated as optional since they applies to the evaluation of attribute bookingRequired received in the response of step 9. If bookingRequired=true in step 9 then steps 10-11 and 18-19 is mandatory.
Step 17. When A-B-C-D is provided by the same travel company the MTB typically contains the whole trip in one ticket. An alternative condition may be that the MTB contains several tickets.
Steps 14-21. The order of these steps is provided as guidance, however there may be reasons for deviations depending on desired customer experience, selection of payment service provider, who is taking the financial risk etc.