reservations-eapi icon

reservations-eapi

1.0.x
(0 reviews)

There will be three main categories of Reservation resources, supported by reference data:

  1. Query availability
  2. Make or amend a booking
  3. Retrieve coach details
  4. Reference data

Each of these categories may contain one or more resources as determined by the requirements and underlying RARS platform capabilities.

Query Availability
  • /availability

This resource allows consumers to request availability of products on services. Broadly equivalent of the Retail SOPI AQ message the availability resource allows for more granular availability queries, for example in relation constructing bundles for multiple passenger bookings, or by prioritising products

Make or amend a booking
  • /bookings

This resource allows consumers to make a provisional booking. It enables consumers to supply customer, journey, product and optionally seat information in order to provisionally reserve a seat (or berth if applicable). Once provisionally reserved the seat will be held for that customer for a configurable period of time (currently 30 mins). Consumers have to confirm the booking (see below) within that time window otherwise the provisional booking will be automatically cancelled (expire).

  • /bookings/{bookingReference}

This resource allows consumers to recall a provisional or confirmed booking using the unique booking reference assigned to it by the reservations service

  • /bookings/{bookingReference}/status

This resource allows consumers to update a booking's status. Possible options are:

  • Confirm - this will confirm a provisional booking (i.e. the booking will not expire and must be explicitly cancelled to be released)
  • Cancel - this will cancel a booking and can be used for either provisional or confirmed bookings
  • Revert - this will back out changes made to a confirmed booking

Note: It is best practice to cancel a provisional booking if it is known that it will not be taken up, rather than allowing it to expire, as this will free up the held seats for other passengers to potentially book.

  • /bookings/{bookingReference}/seats

This resource allows consumers to update a seat associated to a reservation, subject to availability. This can be done before or after a provisional booking is confirmed.

  • /bookings/{bookingReference}/customer

This resource allows consumers to manage a Customer's details, such as name, email address, phone number, etc. A Customer is the 'owner' of a booking as distinct from passengers which are those who are actually travelling. In the majority of cases the Customer will be one of the passenger's but this may not always be the case - for example a corporate booking may be made by a representative of a business (e.g. a PA) as the Customer, for one or more employees to travel as the Passengers. Because these details contain personably identifiable information they will be hidden/masked in certain circumstances for GDPR compliance purposes.

  • /bookings/{bookingReference}/passengers

This resources allows consumers to manage passenger details, such as name, email address, phone number, etc. It also allows additional passengers to be added to an existing booking. Because these details contain personably identifiable information they will be hidden/masked in certain circumstances for GDPR compliance purposes.

  • /bookings/{bookingReference}/passengers/cancel

This resource allows consumers to cancel (remove) one or more passengers from an existing booking

To cancel passenger(s) the system requires the passenger identifier (uuid), which can be found in the booking:

  • data->passengers->uuid

As part of this call, the system will blank out the requested passenger details following successful cancellation of the passenger and will be recorded as a change to the booking.

  • /bookings/{bookingReference}/notes

This resource allows consumers to add free text notes to a booking. These notes have no functional impact and can be used to record any reasonable information relating to a booking which can not be applied to an existing field. Because these notes may contain personably identifiable information they will be hidden/masked in certain circumstances for GDPR compliance purposes.

  • /bookings/{bookingReference}/legs

This resources allows consumers to add one or more legs and/or product items to an existing booking

  • /bookings/{bookingReference}/legs/cancel

This resources allows consumers to cancel (remove) one or more legs from an existing booking

To cancel leg(s) the system requires the leg identifier (uuid), which can be found in the booking:

  • data->outboundBookingTariffLegs->uuid
  • data->inboundBookingTariffLegs->uuid

.

  • /bookings/{bookingReference}/legs/productItems/cancel

This resources allows consumers to cancel one or more seat product items from an existing booking

To cancel product item(s) the system requires the product item identifier (itemRef), which can be found in the booking:

  • data->outboundBookingTariffLegs->requiredProducts->itemRef
  • data->inboundBookingTariffLegs->requiredProducts->itemRef

(There is also an itemRef for additional products, however, additional products is intended for future use)

  • data->outboundBookingTariffLegs->additionalProducts->itemRef
  • data->inboundBookingTariffLegs->additionalProducts->itemRef

Although there is a uuid for a product item, the product item cancel resource requires the itemRef and not uuid, as specified above

  • /bookings/{bookingReference}/utn or /bookings/{bookingReference}/rbr

These resources allow consumers to add or update the Unique Ticket Number or Retailer Ticket Reference. These can be added when creating a provisional booking, or by using these resources consumers can add or change them at a later time.

  • /bookings/{bookingReference}/rebooking

This resource allows consumers to change the booked service(s) and/or product(s)

To perform a rebooking the system requires the product item identifier (uuid), which can be found in the booking:

  • data->outboundBookingTariffLegs->requiredProducts->uuid
  • data->inboundBookingTariffLegs->requiredProducts->uuid

Although there is an itemRef for a product item, the rebooking resource requires the uuid and not itemRef, as specified above

  • /bookings/references

This resource allows consumers to recall a booking reference using a unique identifier assigned to it by the booking owner. Two different references can be used, subject to them being recorded against a booking:

  • Unique Ticket Reference (UTN) - this will allow consumers to recall a reservation using a barcode UTN.
  • Retailer Booking Reference (RBR) - this will allow consumers to recall a booking using a their own reference

.

  • /bookings/{rsid}/{serviceOriginDate}/{boardLocation}/{alightLocation}/{coachId}/{seatId}

This resource allows consumers to recall a booking reference applicable to a specified seat and calling points. This may be used, for example, to recall a booking reference for a Customer who knows which seat they are booked in but doesn't know their reference. A consumer would still need the usual permissions to recall or amend a booking once the reference has been retrieved.

  • /bookings/booking

This resource allows consumers to attempt a booking without first checking for availability. If the requested product is fully available a provisional booking will be made, and if it isn’t, an error message will be returned. Consumers can also optionally request for the provisional booking to be confirmed.

It is the equivalent of the consumer doing the below separate API requests:

  • POST /availability to check availability
  • POST /bookings to make a provisional booking (using tariff code from availability response)
  • optionally PUT /bookings/{bookingReference}/status to confirm booking (using bookingRef from make booking response)
Retrieve coach details
  • /service/{rsid}/coaches

This resource provides the full details of a service, including; the number of coaches and their sequence order, what seats are on each coach and their properties (e.g. plug socket available), and the booking status of each seat. The response also includes an image for each of the coaches along with dimensions of both the coach and the position and dimensions of seats within each coach so that these can be plotted on a suitable display.

  • /service/{rsid}/coaches/images

This resource is a subset of the coach layout resource; providing only the details, sequence and image of each coach on a service without the seat status or position/dimension information

  • /services/{rsid}/reports/passengers

This resource provides a list of passengers as well as seat reservation details on any given service for a particular train operating company

Reference data
  • /refdata/disabilityTypes

This resource allows consumers to request the latest list of disability types supported by the reservations service. Disability types can be submitted in booking requests and will impact on what seats may be booked (e.g. allowing seats specifically for passengers with wheelchairs).

  • /refdata/discountedOrSeasonCardTypes

This resource has been added as it will be a requirement to record a season ticket number against any bookings with a season ticket. This information will be used for MI and fraud detection/reduction purposes. At the moment this data set has only one entry, but may be expanded in the future to include other forms of discounted travel.

  • /refdata/seatProperties

This resource allows consumers to request the latest list of seat properties supported by the reservations service. Seat property codes can be submitted in certain requests and returned by others. This reference data provides details of seat property codes and their associated descriptions for different carriers and time periods.

Security

The resources will be protected by the following policies:

  • JWT Validation

As shown in the examples, Bearer token must to be sent as part of the Authorization header which will be validated by JWT policy by communicating with the already configured identity provider.

Last update: 26-Apr-2024 16.15: ASSIST API Documentation Maintenance: 'reservations-eapi', Version 'v1', Page 'Home', Revision 'D'.

To request updates to this text please contact Neil Barkham.

Reviews