Version: 1.3
Last updated: April 24 2024
...
| Table of Contents | ||||
|---|---|---|---|---|
|
Samtrafiken ACCESS/DISTRIBUTION API
The Samtrafiken ACCESS API is an entry point to Swedish public transport sales. The API provides access to approximately 50 public transport carriers on the Swedish market. Through the API, users can search journeys, make bookings, seat reservations, add ancillaries, handle fulfillment and after sales.
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.
This documentation is mainly aiming to support Samtrafiken ACCESS implementation. When the information is directed to Samtrafiken DISTRIBUTION implementation the text starts with with “Instructions to Samtrafiken DISTRIBUTION:”
Architecture
...
Introduction to OSDM
Why OSDM?
OSDM is a new standard to provide public transportation products in a common way, created by a group of members representing fare providers (operators), allocators (GDS) and distributors in Europe.
...
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.
Trip with no reservation | Trip with reservation on leg 1 | Two leg trip with reservations | Two leg trip with reservations and breakfast at leg 1 |
Admission | Admission | Admission | Admission |
| Reservation (leg 1) | Reservation (leg 1) | Reservation (leg 1) |
|
| Reservation (leg 2) | Ancillary (leg 1) |
|
|
| Reservation (leg 2) |
The extract example below shows the model for a one leg trip offer with admission, reservation and an ancillary:
...
In given implementation an offer covers the complete trip. An admission, normally covers the whole trip as well. Reservations and ancillaries cover one trip leg.
Products
Offer part has references to products. A product describes the rules and properties of the offer part. E.g., a product for an admission describes the ticket-type like “Refundable 1st Class ticket”.
Flexibility
...
Prm need wheelchair
To search available offer for passenger with prm need ”wheelchair”, in the offer request add offer.anonymousPassengerSpecifications.prmNeeds: WHEELCHAIR. The IMS will respond with offer when available.
There are different reasons an offer is not returned when searching with this parameter. The seat availablity is fully booked or the carrier do no support wheelchair on the specific departure.
Interrail
Some carrier offer discount for Interrail/Eurail card holder. In the offer request add offer. anonymousPassengerSpecifications.cards: type: REDUCTION_CARD and code: UIC_INTERRAIL.
If the discount is applicable on the specific journey, the offer response will include
"appliedReductionCardTypes": [
{
"code": "UIC_INTERRAIL",
"issuer": "urn:x_swe:carrier:313",
"name": {
"id": "5a5e4e5c-fc7a-4b04-acfb-bfac08f012ba",
"text": "Interrail discount"
}
}
Travel Pass
Communication of time: The validity period for the Travel pass should be communicated in UTC time to the recipient, with a time zone offset.
In the field validUntil for a Travel pass, it should be specified so that it corresponds to 23:59:59 local time on the day the pass expires to get the correct date of the last day.
· Examples:
offer request validFrom 2024-08-24T22:00:00Z is preferred
offer request validFrom 2024-08-25T00:00:00+02:00 is also acceptable
response validFrom 2024-08-24T22:00:00Z corresponds to local time 00:00:00 on the 25th
response validUntil 2025-08-24T21:59:59Z corresponds to local time 23:59:59 on the 24th of the next year
Products
Offer part has references to products. A product describes the rules and properties of the offer part. E.g., a product for an admission describes the ticket-type like “Refundable 1st Class ticket”.
Flexibility
In OSDM, three types of flexibilities exist:
FULL_FLEXIBLE - Can be refunded (and rebooked)
SEMI_FLEXIBLE - Can be rebooked to another trip
NON_FLEXIBLE - Can not be rebooked or refunded
...
| Code Block |
|---|
"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.
...
| Code Block |
|---|
"appliedPassengerTypes": [
{
"passengerRef": "PASSENGER_1",
"type": "ADULT",
"description": "Student",
"appliedReductionCardTypes": [
{
"code": "SWE_STUDENT" |
...
| Code Block |
|---|
"appliedPassengerTypes": [
{
"passengerRef": "PASSENGER_1",
"type": "YOUTH",
"description": "Youth",
"appliedReductionCardTypes": [] |
...
| Code Block |
|---|
"appliedPassengerTypes": [
{
"passengerRef": "PASSENGER_1",
"type": "ADULT",
"description": "Adult",
"appliedReductionCardTypes": [] "Adult",
"appliedReductionCardTypes": []
|
To search offer with discount, add the discount card in anonumousPassengerSpecifications with the type of card, code, number and issuer (owner of the discount card)
...
If the card is applied by the IMS, the IMS respond with returning information in appliedReductionCardTypes with code, issuer, http://name.id (card number) and text (name of the card)
| Code Block |
|---|
"appliedPassengerTypes": [
{
"passengerRef": "P1",
"type": "ADULT",
"description": "Adult",
"appliedReductionCardTypes": [
{
"code": "ST_DIAMOND_ANNUAL_CARD",
"issuer": "urn:x_swe:carrier:101,
"name": {
"id": "11112222233333”
"text": "ST Diamond Årskort"
}
}
]
}
|
The sales channel provide the applied card in the booking request and send the type, code, number and issuer.
...
| Code Block |
|---|
"appliedPassengerTypes": [
{
"passengerRef": "a8790c60-0a95-459a-9983-b10d008cbb24",
"type": "ADULT",
"description": "Adult",
"tripCoverage": {
"coveredTripId": "20853111-0b2e-4118-b56d-f6bdcfb8cce7"
},
"appliedReductionCardTypes": [
{
"code": "ST_DIAMOND_ANNUAL_CARD",
"issuer": "urn:x_swe:carrier:101",
"name": {
"id": "11112222233333",
"text": "ST Diamond Årskort"
}
}
]
}
],
]
}
],
"appliedReductions": [
{
"code": "ST_DIAMOND_ANNUAL_CARD",
"number": "11112222233333",
"issuer": "urn:x_swe:carrier:101",
"type": "TRAVEL_PASS"
}
]
|
Passenger
The passenger object can be updated with name and other contact information with the endpoint PATCH /bookings/{bookingId}/passengers/{passengerId}
...
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.
Modify
Passenger name, address, phone number, email address can be modified on a provisional booking (prebooked).
Availabilities
Only applies to Samtrafiken DISTRIBUTION
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.
Modify
Passenger name, address, phone number, email address can be modified on a provisional booking (prebooked).
Cancel
Instructions to Samtrafiken DISTRIBUTION: To avoid a refund on a ticket cancelled due to traffic disturbance overrule code EXTERNAL_COMPENSATION is used in the Release offer reques
Availabilities
With GET /availabilities/preference endpoint the client will have the possibility to display the seat availability with seat characteristics for carrier and journey offering prebooked seat reservation.
NDS support contextType ”OFFER” and resourceType ”RESERVATION” in the offer flow.
NDS support contextType ”BOOKING” and resourceType ”RESERVATION” in the booking flow.
Instructions to Samtrafiken DISTRIBUTION: To avoid too large lists in the UI and make it possible to count overallAvailability the implementation of GET/availabilities/preferences should not include all available combinations.
...
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.
Resource | Path | End-point description |
|---|---|---|
Offers | POST /offers | Returns trip and non-trip offers. |
| GET /bookings/{bookingId}/bookedOffers/ {bookedOfferId}/additionalOffers | Returns ancillary and reservation offers |
Availabilities | GET /availabilities/placeMap | Gets place map including availabilities. |
| GET /availabilities/preferences | Gets availabilities for a set of preferences. |
Bookings | POST /bookings | Allows to create a booking based on a previously requested offer. |
| GET /bookings/{bookingId} | Returns a booking with the id provided. |
| DELETE /bookings/{bookingId} | Deletes the booking with the id provided. |
| PATCH /bookings/{bookingId} | Allows updating the fulfillment type of the booking. |
BookedOffers | POST /bookings/{bookingId}/bookedOffers | Adds a bookedOffer in an existing booking. |
| DELETE /bookings/{bookingId}/bookedOffers/{offerId} | Deletes a booked offer in an existing booking. |
BookingPart | POST /bookings/{bookingId}/bookedOffer/{bookedOfferId}/reservations | Adds a optional reservation to a prebooked offer. |
| DELETE /bookings/{bookingId}/bookedOffer/ | Deletes a reservation part from a prebooked offer. |
| POST /bookings/{bookingId}/bookedOffer/{bookedOfferId}/ancillaries | Adds an ancillary to a prebooked offer. |
| DELETE /bookings/{bookingId}/bookedOffer/ | Deletes an ancillary part from a prebook. |
BookingsSearch | POST /booking-search | Searches for bookings according to parameters. |
Passengers | GET /bookings/{bookingId}/ | Returns the passenger's information at every stage of the flow. |
| PATCH /bookings/{bookingId}/ | Updates the passenger's information. |
Purchaser | GET /bookings/{bookingId}/purchaser | Returns the purchaser information. |
| PATCH /bookings/{bookingId}/purchaser | Updates the purchaser information. |
Fulfillment | POST /bookings/{bookingId}/fulfillments | Triggers the fulfillment of the booking. |
| PATCH /fulfillments/{fulfillmentId} | Activates a fulfillment, i.e. changes the status to CONFIRMED/FULFILLED. |
Refund | POST /bookings/{bookingId}/refundOffers | Initiates a refund process by creating a RefundOffer resource. |
| GET /bookings/{bookingId}/refundOffers/{refundOfferId} | Returns the refund offer for the ids provided. |
| PATCH /bookings/{bookingId}/refundOffers/{refundOfferId} | Allows to accept and confirm a refund offer. |
DELETE /bookings/{bookingId}/refundOffers/{refundOfferId} | Deletes a refundOffer without waiting for an expiry. It is a good behavior to delete refundOffers that is not meant to be refunded. | |
Exchange | POST /bookings/{bookingId}/exchangeOperations/{exchangeOperationId} | Allows to update an ongoing exchange operation. |
| DELETE /bookings/{bookingId}/exchangeOperations/{exchangeOperationId} | Cancels an ongoing exchange operation in provisional state. It is a good behavior to delete exchangeOffers that is not meant to be used. |
| POST /exchange-offer | Returns exchange offers for a specified fulfillments submitted given requested new trip characteristics. |
Release (Cancel admission and resources but not refund) | POST /bookings/{bookingId}/releaseOffers | Initiates a release process by creating a releaseOffers resource. |
| PATCH /bookings/{bookingId}/ | Allows to accept and confirm a release offer. |
MasterData | GET /places | Returns all searchable places (stops). |
| GET /coachLayouts | Returns all coach layouts. |
| GET /coachLayouts/{layoutId} | Returns a coach layout for a provided ID. |
GET /reductionCards | Returns all reduction cards |
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.
...
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.
Name | Details |
|---|---|
Requestor* | { "salesApplication": "[String, name of the sales client, exact format provided by the inventory holder to the reseller]" "salesUnitCode": "[String, agreed between reseller and inventory owner]" (required) } The content will be a parsable json and Base64-encoded to a single string like this: Requestor: ewogICJzYWxlc0FwcGxpY2F0aW9uIjogIlRSQUlEIiwgICAgICAKICAic2FsZXNVbml0Q29kZSI6ICJTVDEyMzQ1NiIKfQ== |
Accept-Language | The requestor can request languages Swedish or English |
traceparent |
tracestate |
Idempotency-Key |
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.
Name | Code | Link | Details |
|---|---|---|---|
Stops | urn:x_swe:stn:<nnnnnnnnn> | National stop ID, 9 digits. “Rikshållplats” in Swedish. | |
Carrier | urn:x_swe:carrier:<nn> |
Product Category (Service Brand Code) | urn:x_swe:sbc:<XXX> |
ptMode (transport modes) | ptMode |
Attributes (Service Properties) |
Fare Product Details
The product is one-dimensional. Each product has a its own combination of travel class and flexibility.
...
Name
...
Code
...
Name | Code | Comment |
|---|---|---|
Flexibility | FULL_FLEXIBLE SEMI_FLEXIBLE NON_FLEXIBLE | FULL_FLEXIBLE - Can be refunded (and rebooked) SEMI_FLEXIBLE - Can be rebooked to another trip NON_FLEXIBLE - Can not be rebooked or refunded |
ServiceClass | STANDARD HIGH | Only STANDARD and HIGH are currently implemented on the Swedish market. Type of quality level, finer grained than comfort class. E.g. a carrier offers regular First class (STANDARD) and luxury First class (HIGH) |
TravelClass | SECOND FIRST |
|
Fulfillment | PDF_A4 Ticket data | Samtrafiken will provide PDF and the distributor can also create ticket with barcode (for carrier offering this) and ticket information. Important the distributor need to use Samtrafiken and carrier’s ticket template |
Mandatory passenger and purchaser details | First name, Last name, Email | For the carriers in Samtrafiken’s IMS. Mandatory passenger details for external IMSs to be verified. |
VAT free | isPartOfInternationalTrip | It is up to the requestor to set to true if one or more parts of the journey is international. |
BoB Tickets
With BoB, multiple admisson offer parts or admissions may reference the same leg. Read more about this on BoB tickets.