-
Notifications
You must be signed in to change notification settings - Fork 41
ProcessIdentifiers
home > Operator information > Meta Information > Process Identifiers
These identifiers describe the possible process flows per module (some span multiple modules) or provide more detailed information needed for TO and MP to interoperate. Each identifier is briefly described here. More detailed descriptions may be added later, optionally including a sequence diagram. (In progress)
The availability endpoint has parameters that may be conditionally required. The following process identifiers are used to indicate these requirements.
The regionId parameter is required when calling the availability endpoint.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#availability_region_mandatory" ]The stationId parameter is required when calling the availability endpoint.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#availability_station_mandatory" ]The assetTypeId parameter is required when calling the availability endpoint.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#availability_asset_type_mandatory" ]The lon, lat, and radius parameters are required when calling the availability endpoint.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#availability_on_spot" ]When multiple of these labels are combined, only ONE of them has to be satisfied. For example, if AVAILABILITY_REGION_MANDATORY and AVAILABILITY_ON_SPOT are both applicable, this does not mean that both regionId and lon, lat, and radius must be provided. Complying with one of these requirements is sufficient, although all of them may be supplied.
The process identifiers below do not describe process flows as such. Instead, they describe the required usage of the /planning/inquiries and /planning/offers endpoints.
Planning is created to travel from A to B. The from field is mandatory and the to field is optional. Either departureTime or arrivalTime must be present. If arrivalTime is specified, to should also be specified.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#planning_based" ]Planning is based on one or more assets (I want to use this bike). The planning request's useAssets array contains an asset id from the Operator Information module.
This should be accompanied by one or more of the following identifiers.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#asset_based" ]Planning is based on a series of assets found through a Bluetooth scan. The information obtained during the scan is provided in the useAssets array. The TO must use this information to filter the possible results. This may also refer to a beacon scan.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#bluetooth_scan" ]Same as BLUETOOTH_SCAN, except the input is a scanned QR code.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#qr_scan" ]Same as BLUETOOTH_SCAN, but using NFC.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#nfc_scan" ]Same as BLUETOOTH_SCAN, but using a barcode.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#barcode_scan" ]If the other options are not applicable, a manual code can be requested by the app.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#manual_entry" ]This can be used in specific situations. MP and TO should contact each other to determine whether and how this specific implementation can be arranged.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#other_id" ]This must be used in the book-from-map scenario. An exact identifier found in the /available-assets/ endpoint is used.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#exact_id" ]Planning is created in a similar way to asset-based planning, but with additional location information, for example a station id from the Operator Information module.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#specific_location_based" ]The final planning (booking-intent=true) and booking should be completed without user intervention. This is typically used to allow a user to select an asset and book it directly, for example in a Pick and Go scenario.
This process identifier became obsolete when POST /bookings/one-stop (v1.3) was introduced.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#atomic_planning_and_booking" ]Use estimatedDistance to create an offer instead of using the from and to fields. This TO requires from and estimatedDistance. [version 1.3]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#use_estimated_distance" ]At least one traveler must be included in the request, and that traveler must include an age.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_traveler_age" ]The radius field is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_radius" ]A from station id is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_from_station_id" ]A to station id is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_to_station_id" ]A from stop reference is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_from_stop_reference" ]A to stop reference is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_to_stop_reference" ]The departureTime field is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_departure_time" ]The arrivalTime field is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_arrival_time" ]The number of travelers is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_nr_of_travelers" ]A from address is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_from_address" ]A to address is mandatory.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#mandatory_to_address" ]The booking process itself can be described using the following process identifiers.
The booking is created without full commitment. Immediately after creation, the booking status is CONDITIONAL_CONFIRMED. The TO must either confirm it using POST /bookings/{id}/events - COMMIT or deny it using POST /bookings/{id}/events - DENY.
This is applicable when the TO must first arrange the resources required to fulfil the trip. [version 2.0]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#postponed_commit" ]A booking can be made directly, without first requesting offers. This requires external information (from GBFS, GTFS, NeTEx, and so on). Identifiers found in those sources can be used in the booking process. [version 1.4]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#one_stop" ]The default booking process is supported: request offers, book one of them, and finally commit it. [version 1.4]
If none of the booking process identifiers below are present, NORMAL should be assumed.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#normal" ]These booking identifiers can be combined with other booking process identifiers (see also Access Methods).
A QR code is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_qr" ]A PDF is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_pdf" ]A token is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_token" ]A deep link is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_deeplink" ]An Aztec code is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_aztec" ]An EKey token is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_axa_ekey_otp" ]A description of where to collect the physical key is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_physical_key" ]A barcode is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_barcode" ]An HTML page is provided in token for use during execution.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_html" ]A ticket is created in the ticket stock by the TO.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_ticketstock" ]The access code is created by the TO. This is the default and does not need to be added explicitly.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_by_to" ]The access code is created by the MP. This is not yet supported.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_by_mp" ]The QR code, PDF, and similar access data can be found in the booking result.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_in_booking" ]The QR code, PDF, and similar access data can be found in the commit result.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_in_commit_event" ]The QR code, PDF, and similar access data can be found in the result of trip execution - prepare.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_in_prepare_event" ]The QR code, PDF, and similar access data can be found in the result. Assigning an asset directly delivers the access information, for example for opening lockers.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_in_assign_asset_event" ]The access code can be found in the result of GET /legs/{id}.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_in_get_leg" ]The access code can be found in the result of GET /bookings/{id}.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#access_code_in_get_booking" ]This TO allows the booking expiry time to be extended. The booking response header contains an expiry time, which is required. When this expiry time is approaching, the MP may request a new expiry time. If this is done too often, the TO may decide not to grant the request. [version 1.5]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#allow_extend_booking_expiry_time" ]This TO handles all functionality except the payment part. When booking, a valid license plate of a parked car must be included in the useAssets field. It is also possible to provide a payment method using customer->cards. The returned booking is usually FINISHED. [proposed in v1.5]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#pick_up_the_bill" ]Booking, commit, and /legs/events/ set-in-use are completed in one step. This identifier cannot be combined with the POSTPONED_COMMIT scenario. The returned booking is STARTED.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#atomic_booking_set_in_use" ]The booking results in a committed booking, and no /bookings/{id}/events - COMMIT message is expected. This implies that, when cancelling a chain of legs, this leg must be cancelled using CANCEL.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#auto_commit" ]Deprecated. Booking, commit, and unlock (from the Trip Execution module) are completed in one step. This identifier cannot be combined with the POSTPONED_COMMIT scenario. The returned booking is STARTED.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#atomic_booking_unlocking" ]Trip execution is the most complex part.
The asset is locked or unlocked remotely.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_remotely" ]The asset must be opened using the app. For now, the deep link solution must be used.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_app" ]Bluetooth is used to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_bluetooth" ]A deep link is used to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_deeplink" ]Wi-Fi is used to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_wifi" ]NFC is used to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_nfc" ]RFID is used to lock or unlock the asset. This cannot be supported directly by the app unless a button such as It's open / It's closed is used.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_rfid" ]An access code is shown in order to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_show_access_code" ]The operator's own SDK is used to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_own_sdk" ]Another mechanism is used to lock or unlock the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#lock_unlock_other" ]The TO, for example a taxi provider, sends a prepare event to the MP to indicate that it has started moving towards the pickup address.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#use_prepare_to_indicate_start" ]The TO sends ETA notifications to the MP. Whenever Arrived is sent as an ETA message, the asset is at the pickup location. This ETA refers to the period before the trip starts, for example when a taxi is coming to the user and sends information about the expected arrival time at the pickup location. To send ETAs during the trip, use PROGRESS_NOTIFICATION.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#eta_notification" ]The TO sends trip progress updates using POST /bookings/{id}/progress.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#progress_notification" ]The TO can send additional information, for example to the end user, using POST /bookings/{id}/progress.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#general_notification" ]The TO, for example a taxi provider, sends the SET_IN_USE and FINISH events to the MP.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#to_controlled" ]The TO requires off-boarding evidence in the FINISH event. DEPRECATED. Use the offBoarding steps process steps.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#off_boarding_required" ]When a telephone number is supplied at booking time, this number is called automatically a few minutes before the asset arrives at the to location.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#supplies_call_service" ]After the booking process has ended, either by /bookings/{id}/events - COMMIT or by AUTO_COMMIT, the asset is unlocked directly by the TO. DEPRECATED. Use the ATOMIC_BOOKING_SET_IN_USE process identifier.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#auto_unlock" ]In some cases, location information is required in leg events. The following process identifiers are used for that purpose.
The location must be supplied when starting the leg.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_required_set_in_use" ]The location must be supplied when pausing the leg.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_required_pause" ]The location must be supplied when opening the trunk (/helmet box).
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_required_open_trunk" ]The location must be supplied when ending the leg.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_required_finish" ]The location must be supplied when extending the leg in time, where supported by the asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_required_time_extend" ]The location must be supplied when assigning an asset.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_required_assign_asset" ]The user's location must be supplied in asset.overriddenproperties.place. Please note that this is a GDPR-related issue. Do not apply this without additional security measures. [version 2.0]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#leg_event_location_is_user_location" ]There is no generic LEG_EVENT_LOCATION_REQUIRED process identifier. You must be explicit about what you are requesting. Sharing this information requires a valid need to share it under GDPR.
Support is straightforward and does not require any process identifiers yet.
Deposit and refund issues must be communicated in the conditions, because they may depend on which MP booked the leg. The following identifiers are defined.
The estimated costs in the booking can be committed directly. The difference between the actual costs, calculated after trip execution, and the estimated costs is communicated to the MP using POST /payments/{id}/claim-extra-costs.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#correction_by_extra_costs" ]The TO requires a deposit before the trip can be executed. The process for obtaining this deposit is handled externally and is outside TOMP. [version 2.0]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#deposit" ]The TO requires direct payment after the trip is finished. [version 2.0]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#pay_when_finished" ]The TO requires payment before the trip starts. [version 2.0]
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#upfront_payment" ]At the moment, the General section contains only one process identifier, but it is important because it affects all endpoints.
In ALL requests, the addressed-to header field is mandatory if this header field is used. This applies when the TO is behind walls, for example in a platform or broker/routing structure.
"conformsTo": [ "https://github.com/TOMP-WG/TOMP-API/wiki/ProcessIdentifiers#to_operator_required" ]Introduction
- Roadmap
- Semantic versioning
- Use cases
- Changes per version
- Contribution
- Participants
Workflow
- Operator information
- Planning phase
- Booking phase
- Trip execution phase - start
- Trip execution phase - on route
- Trip execution phase - end
- Support
- Payment
Points of attention
- Modalities
- Specifying locations
- GDPR
Eco system
- Relations
Introduction
Scope of the TOMP-API
Versioning and releases
Process Flows
- Authentication
- Operator Information
- Privacy and Registration
- Planning Module
- Booking Module
- Trip Execution Module
- Payment Module
- Support Module
Meta-Information
Reference implementations
To-dos and risks
Technical Specifications
A1 List of terms and definitions
A2 Passenger characteristics dictionary
A3 APIs available on the transportation ecosystem
A4 Overview of the User stories
A5 Authors, Architects, collaborators and stakeholders involved
A6 Adoption and Implementation of the TOMP-API