Bookings API

Overview

Bookings API is a service that provides access to booking data for public transport journeys sold through Samtrafiken ACCESS, including SJ's segments of Resplus journeys.

It enables authorized clients to retrieve booking information, monitor status updates, and access relevant passenger and payment details.

Who Can Use This API?

The Bookings API is available to:

Retailers who sell public transport journeys
Operators (transport companies) who operate trains and buses

Data Coverage

The API provides:

Booking details and status
Passenger and payer information
Journey details (segments, stops, and times)
Price and ticket data
Cancellations and refunds

Use Case

Retrieve Bookings via Events

For clients who need to retrieve all events for bookings based on specific parameters, providing access to the complete booking history. This corresponds to the "Bokningsmeddelande" (Booking Messages) functionality and is typically most suitable for external parties.

Typical users: Retailers, operators requiring full booking history

Access Requirements

Technical Requirements

To access the Bookings API, you need:

Authorization: Configured permissions in Samtrafiken's system for either retailer or operator
Authentication: OpenID Connect / OAuth 2.0
Access level: Access is configured at the organizationCode level. The same retailer and operator registry is used as for NDS (National Distribution System)

Onboarding Information Required

From all clients:

JWKS URL where your public key is published (for OpenID Connect/OAuth 2.0)
Email address for receiving information about API updates

For retailers:

The selling organization (organizationCode) the access applies to

For operators:

The operator (producernumber) the access applies to

Access Types

Bookings API – Operator

Provides information about individual transactions for a specific transport operator.

Used by operators who need access to booking data related to their own segments.

Bookings API – Operator (Full Journey)

Extends the operator version by including details about the entire journey, not only the operator's segment.

Intended for operators with authorization to view complete Resplus journeys.

Bookings API – Retailer

Provides information about each booking transaction made by a specific retailer.

Intended for the retailer that originally sold the journey.

Important Technical Details

Data Sources

The Bookings database contains messages from both:

NDS (Turnit): Standard booking messages for journeys sold through the National Distribution System
SJ: Booking messages for journeys sold by SJ

Data Handling for SJ Bookings

SJ's messages reflect their actual customer relationship. This means:

If SJ refunds a non-refundable ticket to their customer, it will appear as refunded in the Bookings API (since SJ has actually refunded the customer)
Note: In the Settlement system (which retrieves data from Turnit), the same ticket will appear as not refunded - the refund occurs at SJ's expense

Known Limitations

Cancellations Made in TRAID for SJ-Sold Journeys

Bookings made by SJ that are cancelled through TRAID (or vice versa) are not updated and will not appear as cancelled in the Bookings API.

Reason: Lack of a common ID between the two booking systems for matching purposes.

Passenger and Payer Information Updates

Passenger and payer information is not updated if changes are made in the selling system after the initial booking (applies to all selling systems).

Reason: Messages are only sent to Samtrafiken when bookings reach the statuses Fulfilled, Refunded, or Cancelled. Intermediate updates to passenger information are not transmitted.

Getting Started

To request access to the Bookings API, please contact Samtrafiken with:

Your organization details
Intended use case
Technical contact information (JWKS URL and email for API updates)

For detailed API specifications and integration support, please refer to the technical documentation or contact your Samtrafiken representative.