Version: 1.23
Last updated: March 05 April 24 2024
| Info |
|---|
DISCLAIMER The Samtrafiken ACCESS API and its documentation is work in progress. Changes and additions will be made to the documentation during the implementation process. |
...
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:
...
BEST - Not used in this implementation
HIGH - A better/higher level of the travel class e.g. “2nd class with meals included”
STANDARD - The standard travel class ticket
BASIC - Not used in this implementation
ANY_CLASS - Used for ancillaries
Product name for Samtrafiken carrier will only be distributed in Swedish. E.g on Samtrafiken ticket the product name will be displayed in Swedish.
Journeys and Trips
A trip consists of one or several consecutive legs. In the Samtrafiken ACCESS implementation, one offer covers one trip. If the legs are not through-ticketed (i.e. co-priced), the system will split the trip to several trips within a Journey.
A multi carrier journey will be divided into multiple trips per carrier, since they are not through-ticketed.
...
| 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": []
|
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)
...
| 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}
...
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 | Comment |
|---|
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.