First ideas Forge - Offer, Purchase & Refund

[edwinvandenbelt]

These 3 functions are in all standards available. Let's focus first on the concepts in these endpoint. I'll try to enlist all concepts in the standards, and a mapping table at the end. Please comment

[edwinvandenbelt]

First, let's have a look at the Offer Search. As discussed in the last session, we more or less found out that searching for offers is represented by these endpoints:

Operation	OSDM	TOMP-API 2.0.0	OMSA 0.1.0	BoB (full suite)	FerryGateway 1.3.1
Search offers	POST /offers	POST /processes/search-offers/execution	POST /processes/search-offers/execute	POST /product GET /product GET /product/{productId} (Product)	GetPriceRequest/Response GetServicesRequest/Response

OSDM has these concepts in the request:

POST /offers                                  → TM: TRIP FARE REQUEST
└── OfferCollectionRequest
    ├── tripIds[]                             (from a prior /trips-collection)
    ├── tripSpecifications[]                  (alternative: pre-determined legs)
    ├── tripSearchCriteria                    (alternative: inline trip search)
    ├── anonymousPassengerSpecifications[]
    │   ├── externalRef
    │   ├── type : PassengerType             (ADULT / CHILD / PRM / WHEELCHAIR …)
    │   ├── dateOfBirth / age
    │   ├── prmNeeds[]
    │   ├── cards[] : CardReference
    │   ├── residency : CountryCode
    │   └── transportable : TransportableSpecification
    ├── offerSearchCriteria
    │   ├── travelClasses[]
    │   ├── serviceClassTypes[]
    │   ├── flexibilities[]
    │   ├── requestedOfferParts[]
    │   └── currency
    ├── nonTripSearchCriteria
    │   ├── nutsCodes[]
    │   ├── zones[]
    │   └── places[]
    ├── corporateCodes[]
    ├── promotionCodes[]
    └── requestedFulfillmentOptions[]

The TOMP-API has these:

POST /processes/search-offers/execution       → TM: TRIP FARE REQUEST
└── searchOfferRequest
    ├── type : "searchOffer"
    ├── specification : travelSpecification
    │   ├── from : placeReference
    │   ├── via[] : placeReference            (max 3)
    │   ├── to : placeReference
    │   ├── startTime
    │   └── endTime
    ├── specification : tripPattern           (alternative)
    │   ├── serviceJourneys[]
    │   └── travelDate
    ├── travellers[]
    │   ├── id
    │   ├── characteristics
    │   │   ├── name / age / customerReference
    │   │   ├── entitlements[] / cardTypes[] / cards[]
    │   │   └── licenseTypes[] / licenses[]
    │   ├── profile : userProfile
    │   │   ├── ageGroup
    │   │   ├── minimumAge / maximumAge
    │   │   └── groupSize
    │   └── requirements : travellerRequirements
    │       ├── mode / subMode / class
    │       ├── operators[] / products[] / assets[] / zones[]
    │       ├── avoid.places[] / avoid.zones[] / avoid.lines[]
    │       └── prmNeeds[]
    ├── places[]                              (max 5, named places for context)
    └── packageToExchange : packageReference

OMSA looks like this:

POST /processes/search-offers/execute         → TM: TRIP FARE REQUEST
└── searchOfferInput
    ├── type : "search_offer"
    ├── travellers[] : individualTraveller    (1–10, required)
    │   ├── id                               (required)
    │   ├── age / gender / fullName
    │   ├── isValidated / customerReference
    │   ├── entitlements
    │   │   ├── commercialProfiles[]
    │   │   ├── entitlementsGiven[]
    │   │   ├── cardTypes[] / cards[]
    │   │   └── licenseTypes[] / licenses[]
    │   └── requirements
    │       ├── organisational[]
    │       ├── spotReservations[]
    │       ├── distribution[]
    │       ├── network[]                    (operator constraints)
    │       ├── routing[]
    │       ├── service[]                    (class, service type)
    │       ├── temporal[]
    │       ├── equipment[]                  (PRM / accessibility)
    │       ├── cancellation[]
    │       └── purchase[]
    ├── specification : requestedTravelSpecification + placeDefinitions
    │   ├── from : externalReference         (or gps:lat,lon)
    │   ├── via[] : externalReference        (max 3)
    │   ├── to : externalReference
    │   ├── startTime
    │   └── endTime
    ├── pattern[] : tripPattern              (alternative to specification)
    │   ├── serviceJourney : serviceJourneyReference
    │   ├── date
    │   ├── from : placeReference
    │   └── to : placeReference
    ├── profiles[] : userProfile
    │   ├── id / count
    │   ├── ageGroup (infant / child / youth / adult / senior)
    │   ├── minimumAge / maximumAge
    │   ├── localResident / genderLimitation
    │   └── minimumHeight / maximumHeight
    ├── travellingAssets[]
    │   ├── id : assetReference
    │   ├── entitlements (same structure as individualTraveller)
    │   └── requirements (same structure as individualTraveller)
    └── packageToExchange : packageReference

This is BoB's treeview:

POST /product                                 → TM: TRIP FARE REQUEST (partial)
└── productFilter
    ├── route
    │   ├── operatorRef
    │   └── lineRef / serviceJourneyRef
    ├── area
    │   └── geometry (geographic area)
    ├── genericCategories{}                   (key → string[], AND across keys)
    │   ├── transportMode[]
    │   └── fareClass[]
    ├── travellersPerCategory{}
    ├── discountCodes{}
    ├── adjacencies
    │   ├── ingress : adjacency              (entry point)
    │   └── egress  : adjacency             (exit point)
    ├── temporal
    │   ├── earliestDeparture
    │   ├── latestArrival
    │   ├── startOfValidity / endOfValidity
    │   └── requestedRelativeValidity / requestedAbsoluteValidity
    └── productPropertyFilter[]              (name-value pairs)

And the FGW looks like this:

GetPriceRequest                               → TM: TRIP FARE REQUEST
├── Context : ContextType
│   ├── @AgentAccountNumber                  (required)
│   ├── @TimeStamp                           (required)
│   ├── @Currency                            (required, ISO 4217)
│   ├── @CountryCode                         (ISO 3166-1)
│   ├── @LanguagePrefCode                    (ISO 639-1)
│   ├── @TransactionId
│   └── @ExternalBookingReference
├── Passengers : PassengersQuoteType
│   └── Passenger[] : PassengerType
│       ├── @Id                              (required)
│       ├── @Category                        (Adult / Child / Infant / Senior …)
│       ├── @Age
│       ├── @DateOfBirth
│       ├── @SubCategory
│       ├── @LoyaltyCardId
│       └── @LoyaltyCardCategory
├── FerryComponent
│   └── Sailings
│       └── Sailing[]
│           ├── SailingRef                   (reference to sailing from GetSailingsResponse)
│           ├── PassengerRefs[]
│           ├── VehicleRefs[]
│           └── FareDetails : FareDetailsRequestType
│               └── RequestedFareCategories[]
├── Vehicles : VehiclesType
│   └── Vehicle[]
│       ├── type enum (Car / Motorcycle / Caravan / Truck …)
│       ├── length / height
│       └── registrationNumber
└── Pets : PetsType

GetServicesRequest                            → TM: TRIP FARE REQUEST (ancillary offers)
└── (sailing reference + passenger/vehicle refs + service type filter)

GetSailingsRequest                            → TM: TRIP REQUEST
├── Context : ContextType                    (required — see fields below)
├── TPE : TradingPartnersExtensionType       (optional) bilateral extension payload
├── Passengers : PassengersQuoteType         (required)
├── Pets : PetsType                          (optional)
├── Vehicles : VehiclesType                  (optional)
├── FerryComponent : FerryComponentGetSailingsRequestType  (required)
│   ├── OfferCode : OfferCodeType            (optional) promotional/offer code
│   └── Sailings : SailingsGetSailingsRequestType
│       └── Sailing[] : SailingGetSailingsRequestType
│           ├── PassengerRefs[]              (if not @AllPassengers)
│           ├── PetRefs[]                    (if not @AllPets)
│           ├── VehicleRefs[]                (if not @AllVehicles)
│           ├── SailingSearchCriterion : SailingSearchCriterionType  (required)
│           │   ├── RequestedServices        (optional) filter sailings by required services
│           │   ├── @DepartDateTime          (required) requested departure dateTime
│           │   ├── @DepartPlace             (required) UN/LOCODE or route group code
│           │   ├── @DepartPlaceQualifier    (optional, default "Port")
│           │   ├── @DestinationPlace        (required) UN/LOCODE or route group code
│           │   ├── @DestinationPlaceQualifier  (optional, default "Port")
│           │   ├── @BeforeDepartHours / @BeforeDepartSailings  (optional) search window before
│           │   └── @AfterDepartHours / @AfterDepartSailings    (optional) search window after
│           ├── FareDetails : FareDetailsRequestType  (optional) pre-filter by fare type
│           ├── @AllPassengers               (boolean, default true)
│           ├── @AllPets                     (boolean, default true)
│           └── @AllVehicles                 (boolean, default true)
├── @IsOnlyMinicruise                        (boolean, default false) mini-cruises only
├── @ShowAlternativeRoutes                   (boolean, default false) suggest alternative routes
└── @AllotmentAgreementId                    (optional) allotment id

[edwinvandenbelt]

We could focus on starting with underlying concepts. Should we start with things like Vehicles, pets, travellers (instead of passengers), maybe some filter concepts?