diff --git a/images/on-demand-services/booking-process.puml b/images/on-demand-services/booking-process.puml new file mode 100644 index 00000000..e5ad5113 --- /dev/null +++ b/images/on-demand-services/booking-process.puml @@ -0,0 +1,28 @@ +@startuml +hide footbox + +actor "Retailer" + +== Creating the trip collection & getting the initial set of trips including an on-demand-service on the first mile == +Retailer -> Distributor: POST /trips-collection +Distributor -> JourneyPlanner : +JourneyPlanner --> Distributor : +loop for each trip + loop for each segment + Distributor -> Distributor: determine Provider + end +end +Distributor -> Distributor : create offer requests + +Distributor -> TompProvider: get offers +TompProvider -> TompProvider: calculate offers +TompProvider --> Distributor : offers +loop for each request + Distributor -> FareProvider: get offers + FareProvider -> FareProvider: calculate offers + FareProvider --> Distributor : request with trips +end +Distributor -> Distributor : reconcile trips and \nconstruct global offers +Distributor --> Retailer: + +@enduml diff --git a/spec/OnDemandServices b/spec/OnDemandServices new file mode 100644 index 00000000..b1a2ad36 --- /dev/null +++ b/spec/OnDemandServices @@ -0,0 +1,78 @@ +--- +layout: page +title: On Demand Services +hide_hero: true +permalink: /spec/processes/ +--- + +## Table of contents + +1. [Introduction](#introduction) +2. [Use Cased](#usecases) + +## Introduction + + +## Use Cases + +### find services + +search for ContinuousServices by: + + - JourneyId (from Trip) + - bookingId (context of a booking) + - passengerRef (multiple ones in case of taxi, self driving taxi) + - BookingPartId of a previous booking (special price as add on to booked timed services, ..) + - geo-coordinate of requested pick-up place + - geo-coordinate of requestor + + reply: list of available Continuous Services + per service: + id + description + available + available for blocking + fee for blocking + time limit for blocking + allocation procedure description + geo-location of the service + time to arrival at pick-up-place (taxi,..) + alternative pick-up-place + +### block service + +block ContinuousService by id + return ContinuousServiceUsage: + id + usage procedure description + descrition on end of usage + credentials to start the usage (e.g. nfc-enabled pkpass, ...) + time limit for start of usage + +### start and end usage + +start usage on continuous service usage by id + return ContinuousServiceUsage: + usage procedure description + descrition on end of usage + +end usage on continuous service usage by id + request: + EndUsageRequest + id + image of parking situation + return ContinuousServiceUsage + status + refund of unused prepayed amount + +get usage of continuous service + return ContinuousServiceUsage + status + amount to pay + remaining amount for prepayed usage + time to arrival at pick-up-place (taxi,..) + + + + + diff --git a/spec/on-demand-services.md b/spec/on-demand-services.md new file mode 100644 index 00000000..cf11285d --- /dev/null +++ b/spec/on-demand-services.md @@ -0,0 +1,207 @@ +--- +layout: page +title: Integrating On Demand Services +hide_hero: true +permalink: /spec/on-demand-services/ +--- +## Table of contents + +1. [Introduction](#introduction) +2. [Use Cases](#useCases) +3. [Offer and Booking Process](#Booking) +4. [Allocation of Service](#Allocation) +5. [Usage of Service](#Usage) + +## Introduction + +This page describes the integration of OSDM with TOMP to include on-Demand-Services on the first ad last mile of a journey. + + +## Use Cases + +A consumer of a trip offer collection where the first mile can be made via an On-Demand-Service. The retailer expects a complete offer and the distributor to handle the connection to the provider of the On-Demand-Service. + +The consumer can search for available vehicles that can provide the service. He can select a service which becomes blocked for other consumers. +The consumer can start the usage of the service with the allocated vehicle. +The consumer can end the usage of the service with the vehicle in use. + +The providers may have implemented different pricing and payment schemes: + + - prepayed fixed price or included in an overall admission booking part + - prepayed with pay per use and a refund on unused time or distance + - postpayment with pay per use based on time or distance + +### offer/booking + +Case 1: Additional Offer to an existing booking: + + The additional offer is requested at the end or beginn of the times journey + + GET /bookings/{bookingId}/booked-offers/{bookedOfferId}/additional-offers + + additional descriptions in offer and booking / product + - service description (link to images?) + - pricing description + - allocation procedure description + - usage procedure description + - description on handling accidents/damages/irregularities + + find a service vehicle, allocate it, start using it, end using it + +Case 2: Initial Offer + + Request an offer + Search for available services nearby before confirming the offer based on offerpartid + + find a service vehicle, allocate it, start using it, end using it + + +Case 3: book the service and allocate the service later + + search for services referes to bookingpart + + find a service vehicle, allocate it, start using it, end using it + + +payment alternatives: + + - Fixed price of the booking + - should work without changes + - Prepaid booking and refund of unused part + - display of amount used and refundable part needed. (indicatedConsumption already defined in bookingPart) + - Post Payment + - display of amount used needed (indicatedConsumption already defined in bookingPart) + + +### Resources: + +ContinuousServuces: just the endpoint to seatch for service vehicles providing the continuous service +ServiceVehicle: A service vehicle that could ppotentially provide a continuous service +ServiceVehicleUsage: The acual allocated service vehicle for the continuous service + + + +### allocate a service + + +search for available ContinuousServices by: + + PATCH continuousServices + ContinuousServiceVediclesSearcRequest: + - JourneyId/trip section (from Trip) + - bookingId (context of a booking or a prebooked service) / offerId (context of an offer without booking) + - passengerRef (multiple passengers in case of taxi, self driving shuttle) or number of passengers? + - BookingPartId of a previous booking (special price as add on to booked timed services, ..) + - geo-coordinate of requested pick-up place + - geo-coordinate of requestor + + reply: list of available Continuous Service Vehicles + - description + - service description (link to images) + - pricing description + - allocation procedure description + - usage procedure description + - description on handling accidents/damages/irregularitries + - per service vehicle: + id + description + - pricing + - allocation procedure description + - usage procedure description + - description on handling accidents/damages/irregularitries + available but not close enough for allocation / available for allocation + fee for allocation + time limit for blocking + geo-location of the service vehicle + estimated time of arrival at pick-up-place (taxi,..) + alternative pick-up-place + estimated price (in case of pay per use) + +### allocate service vehicle + +allocate Service Vehicle by id. The Service vehicle gets blocked for othre requests and the passenger(s) can start the usage of the vehicle + + POST /ServiceVehicleUsage serviceVehicleId + request: + passengerRef(s) + + return ServiceVehicleUsage: + id + status = allocated + usage procedure description + descrition on end of usage + credentials to start the usage (e.g. code, nfc-enabled pkpass, ...) + time limit to start the usage + + DELETE ServiceVehicleUsage by id + + + +notification in case + - allocation expires + - allocation is changed (new taxi) + - usage ends + - usage ends due to missuse (e.g. area restrictions) + - usage ends for technical reasons (e.g. battery empty) + +refund if allocation fails? + + + +### start and end usage + + +start usage on continuous service usage by id + + PATCH ServiceVehicleUsage by id + StartUsageRequest + optionally provide credentials (scanned vehicle barcode + + return ContinuousServiceUsage: + status = in use + usage procedure description + descrition on end of usage + +end usage on continuous service usage by id + PATCH ServiceVehicleUsage by id + request: + EndUsageRequest + id + image of parking situation + return ServiceVehicleUsage + status + refund of unused prepayed amount + driver tip? + + GET ServiceVehicleUsage by id + return: ServiceVehicleUsage including + - id + - status + - WAITING_TO_START + - STARTED + - CONTINUING + - ENDED + - usage procedure description + - descrition on end of usage + - technical features + - IMAGE_OF_PARKKING_REQUIRED + - NFC_PKPASS_SUPPORT_REQUIRED + - TIP_OPTION_SUPPORTED + - credentials to start the usage (e.g. code, nfc-enabled pkpass, ...) + - time limit to start the usage + - time of starting the usage + - time limit to end the usage + - time of ending the usage + - geo-coordinate to end the usage / place? + - geo-coordinate of the current location + - descriptions from the ServiceVehicle + - bookingPartId --> fulfillments for billing, refund of unused prepayed amount + - remaining amount for prepayed usage --> in corresponding booking part? + - current refund amount if usage ends --> in corresponding booking part? + - current amount used --> in corresponding booking part? + - current xyz used /in case of fixed time or distance --> in corresponding booking part? + - current xyz left /in case of fixed time or distance --> in corresponding booking part? + + + +--