Page Comparison

Version: 1.01

Last updated: January 10 February 08 2024

...

The API is based on the OSDM (Open Sales and Distribution Model) standard. The OSDM standard is introduced below, along with details of the Samtrafiken implementation of the standard.

Architecture

...

Introduction to OSDM

Why OSDM?

...

The official OSDM documentation can be found here: https://osdm.io/ OSDM

Current OSDM version supported by Samtrafiken ACCESS is 3.0.3

Main objects in OSDM

The main objects in the model are:

...

To enable defining more complex products, offer parts can be coupled by references under the main offer part. Currently, there are only admissions that couple offer parts like this.

The extract example below shows the model for a one leg trip offer with admission, reservation and an ancillary:

...

• prebooked - when an offer is booked (the initial state);

• confirmed, when a prebooked offer is confirmed (i.e. customer has paid);

• fulfilled, when a prebooked offer is fulfilled (i.e. travel document has been issued);

• released, when a fulfilled offer part is cancelled but not refunded (i.e. the inventory has been made available for the other customers to book);

• refunded, when a fulfilled offer part is refunded to the customer;

• exchangeOngoingexchange ongoing, when an exchange process is initiated;

• exchanged, when the exchange process is finalized;

• onhold, when the sales channel has asked for an extended TTL (time to live) period for the offer.

...

To know which carrier respond to reduction card, promotion and corporate agreements requested in the offer search, can be found in offerCollectionsResponse => offers => admissionOfferParts => appliedPromotionCodes/appliedCorporateCodes/appliedReductionCardTypes

If there are multiple reduction card provided, the reduction card with the highest discount is always applied.

Passengers and Purchaser

anonymousPassengerSpecifications

...

"anonymousPassengerSpecifications": [
  {
    "externalRef": "PASSENGER_1",
    "age": 18,
    "type": "PERSON",
    "cards": [
      {
        "type": [
          "REDUCTION_CARD"
        ],
        "code": "SWE_STUDENT"
      }
    ]
  }
],

IMS respond with STUDENT fare and passenger type ADULT as carrier offer STUDENT fare. In appliedPassengerTypes.description the IMS respond with the “actual” passenger type to be printed on the ticket.

In addtion the IMS respond with their own carrier code, when the reduction cards SWE_STUDENT, SWE_PENSIONER or SWE_TDT are used in the request. The redction cards starting with SWE_ are generic cards used at the swedish market without an issuer but all carriers returning discounts based om these cards should return their own carrier code as issuer.

"appliedPassengerTypes": [
              {
                "passengerRef": "PASSENGER_1",
                "type": "ADULT",
                "description": "Student",
                
"appliedReductionCardTypes": [
                  {
                    "code": "SWE_STUDENT"

IMS respond with YOUTH fare as carrier have no offer for STUDENT fare:

"appliedPassengerTypes": [
              {
                "passengerRef": "PASSENGER_1",
                "type": "YOUTH",
                "description": "Youth",
                
"appliedReductionCardTypes": []

...

The booking can be used as a shopping cart, holding different journeys. A booking consists of one or several bookedOffers with references to trips and passengers.
Before fulfillment/confirmation of the booking (prebooked state) it is possible to add/replace/remove bookedOffers, reservations and ancillaries from a booking.

Multi Carrier Journey

For multi carrier journeys, each carrier

Book offers

New booking

To add an initial offer and create a booking, run POST /bookings. Together with the selected offerId, it is possible to add optionalReservationSelections and optionalAncillariySelections from the offer-search response to make a complete booking in the pay-load.

It is also possible to add optional reservations and ancillaries and purchaser/passenger information before confirmation of the booking by:

• POST /bookings/{bookingId}/booked-offers/{bookedOfferId}/reservations

• POST /bookings/{bookingId}/booked-offers/{bookedOfferId}/ancillaries

• PATCH /bookings/{bookingId}/passengers/{passengerIds}

• PATCH /bookings/{bookingId}/purchaser.

Promotion codes to use is also possible to provide in the pay-load.

Add offers to an existing booking

The endpoint to use when adding a new offer to a already existing booking is POST /bookings/{bookingId}/booked-offers. The pay-load is the same as for POST /bookings. The only difference is that the existing bookingId is provided as a parameter in the call.

Multi Carrier Journey

For multi carrier journeys, each carrier will book their own offer for that part (trip) of the journey.

...

Grouped offers (private compartment) have more than one passenger referred from the admission. They share the admission and fulfillment. Aftersales activities will affect all passengers in the offer. It is not possible to refund only one of the passengers.

provisionalPrice and confirmedPrice

• provisionalPrice is the amount still to pay to fulfill all offers in the booking. After fulfillment, provisionalPrice is 0,00.

• confirmedPrice is the amount paid so far for the booking.

When provisionalPrice is 0.00 the booking is fully paid with the amount in confirmedPriceof the passengers.

provisionalPrice and confirmedPrice

booking.confirmedPrice and booking.provisionalPrice should be seen as de facto mandatory and always be present regardless of the booking status, sometimes having the value 0 and sometimes not.

• provisionalPrice
  Total sum of the offerParts that are pre-booked and yet to be confirmed. The
  (remaining) amount to be paid by the customer/passenger.

• confirmedPrice
  Sum of the offerParts that are confirmed and paid for by the customer/passenger, the monetary value of the booking. A refund will reduce the confirmedPrice because the offerPart is not active/valid any more.

ticketTimeLimit

The timestamp in ticketTimeLimit indicates the latest time to fulfill the booking. The time is set from the offer with the shortest ticketTimeLimit in the booking.

...

Passenger name, address, phone number, email address can be modified on a provisional booking (not fulfilledprebooked).

Availabilities

Only applies to Samtrafiken DISTRIBUTION

...

It is the fulfillment process that finalizes the booking. The result of the fulfillment is an offer with status fulfilled with a link to a document (e.g. PDF, pkPass) for the offer.

Note: It is the distributor’s responsibility to distribute the fulfillment to the customer/passengers.

...

Note: The OSDM specification is still undergoing an evolution, with an active workgroup having meetings every week to evolve the standard to support upcoming needs. The exact OSDM version to be used in Samtrafiken ACCESS at the Start of Sales is yet to be decided.

Resplus

Samtrafiken is the owner of the RESPLUS brand. Samtrafiken’s national distribution service (NDS) is responsible for determining if a journey is a Resplus journey or not. The Samtrafiken ACCESS user should not send throughTicketTag RESPLUS in the offer request. The throughTicketTag is set by Samtrafiken. Samtrafiken's NDS will respond with throughTicketTags in the response when applicable.

...

API Authentication

Open API Specification

...

Specification

Auth API

Authentication

The proposed method for authentication in OSDM is to use OAuth2 and for Samtrafiken ACCESS we use a login service to request a valid token by using a Client Id/Client Secret. The token is then used in all requests to Samtrafiken ACCESS. The access token request follows the OAuth standard method.

To avoid too much traffic to the login service, the customer must reuse the token as long it is valid and ask for a new token when the old one is expired.

Requestor header

The requestor header contains detailed information about who is calling the API. It will include an id of the sales unit and name of the application used (if needed). The content of the string is part of a bilateral contract by the two parties and not standardized by OSDM. It is recommend to encrypt the information transferred.

Code Lists

Samtrafiken is responsible for providing a collection of code lists in the Swedish domain of the OSDM implementation standard. The namespace is defined as “urn:x_swe:” and contains different code lists to handle all sellable stops and carriers in Sweden handled by Samtrafiken.

Fare Product Details

The product is one-dimensional, the fare is a . Each product has a its own combination of travel class and flexibility.

BoB Tickets

With BoB, multiple admisson offer parts or admissions may reference the same leg. Read more about this on BoB tickets.