Version: 1.12
Last updated: February 08 March 05 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. |
...
The official OSDM documentation can be found here: OSDM https://osdm.io/
Current OSDM version supported by Samtrafiken ACCESS is 3.0.3
...
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:
...
When searching for offers, anonymousPassengerSpecifications are provided. One for each passenger.
ExternalRef is a reference the sales channel can use to locate what offers in the response that match the passenger. The provider is obligated to return the reference in all responses.
In the request for a passenger with no special need use passenger type “PERSON”.
...
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 addition 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.
...
Code Block |
---|
"appliedPassengerTypes": [ { "passengerRef": "PASSENGER_1", "type": "ADULT", "description": "Adult", "appliedReductionCardTypes": [] |
ExternalRef is a reference the sales channel can use to locate what offers in the response that match the passenger. The provider is obligated to return the reference in all responses.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 |
---|
},
"anonymousPassengerSpecifications": [
{
"externalRef": "P1",
"type": "PERSON",
"cards": [
{
"type": "TRAVEL_PASS",
"code": "ST_ANNUAL_DIAMOND",
"number": "11112222233333",
"issuer": "urn:x_swe:carrier:101"
}
]
}
]
}
|
If the card is applied by the IMS, the IMS respond with returning information in appliedReductionCardTypes with code, issuer, 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 |
---|
"passengerSpecifications": [
{
"externalRef": "P1",
"cards": [
{
"type": "TRAVEL_PASS",
"code": "ST_DIAMOND_ANNUAL_CARD",
"number": "11112222233333",
"issuer": "urn:x_swe:carrier:101"
}
],
|
The IMS respond with the applied card in the booking response in appliedReductionCardTypes and appliedReductions
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.
...
API Authentication
Open API Specification
Auth APIhttps://identity.ds.dev.ci.turnit.tech/help/index.html
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.
...
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.