Documentation

← Issuing API (v1) →

# Using the TapConnect TOMP API

TapConnect provides a limited implementation of the TOMP-API (opens new window). The TapConnect implementation of the TOMP-API is available at Swaggerhub (opens new window).

To be able to use this API a client needs the following:

  • A configured sales channel with a single product available at any time. This is required so that TapConnect selects the correct product for issuing tickets when creating TOMP Bookings.
  • An API token with the TOMP endpoint role for the sales channel.

Versioning and routing of the TOMP API is based on headers, examples below:

  • api: TOMP signals TapConnect that this request is a TOMP-API request
  • api-version: 1.1.3 indicates that the client uses the 1.1.3 version of the API
  • Authorization: Bearer z6QkOERZsWbQC4QcwIdexgEWZHJP4VNF8CfQogaZmXV= is how the client passes the authorization key to TapConnect. This key is provided to the client by the tenant administrator. All communication to the TapConnect TOMP-API uses https.

# Planning phase

The TOMP-API wiki (opens new window) describes different phases to search, buy and use travel products. In the planning phase, the client/customer provides the start and end locations of the intended travel, and TapConnect responds with a couple of options and prices for this trip.

In the case of TapConnect, the from and to fields in the planning request need to contain GTFS ids (opens new window).

# Booking phase

The booking options received in the Planning Phase each have a unique id. The client can create a new booking by sending the selected option id in a booking request. The booking will be created in a "PENDING" state, and the legs will be in state PREPARING.

To commit the booking and create tickets, or cancel the booking the client can update the state of the booking. TapConnect only suports the COMMIT and CANCEL operations on this endpoint.

When a booking is committed, TapConnect will set the booking to state "CONFIRMED", and create all tickets required for the legs. Depending on the type of travel product configured, tickets can be immediately active, or have to be activated later. For immediately active tickets, the leg state will be "IN_USE". For tickets which need to be activated later, the leg state will be "PREPARING".

# Trip execution phase

If the leg state is "PREPARING" (for tickets which are not active immediately), the state can be changed by sending the SET_IN_USE event to the legs endpoint.

For legs which are in the state "IN_USE", tickets can be retrieved by getting the leg. The leg response will contain the ticket in the form requested earlier in the booking process.

# Caching of responses

The API responses contain cache headers. In case of legs and tickets, the cache time will match the lifetime of the barcode. Particularly for products where the barcodes will expire regularly to prevent fraud it is important to note the cache header and request a new version of the barcode by fetching a fresh copy of a leg.

← Issuing API (v1) →