Skip to content

Backend integration

APIs provided by the RH operator

Watchdog auth API

This endpoint will be used by the RH frontend app, it will not be called by Mileus backend. When the RH app calls this endpoint, RH backend retrieves the auth token from the Mileus /auth/v1/token endpoint and returns it to the app. This is not relevant to the backend integration flow, but this API needs to be provided by the RH operator so that the watchdog frontend implementation could retrieve the auth token safely.

Price estimate API

To retrieve the expected price of a ride for a passenger, Mileus will use this API of the RH operator. The API should accept origin (pickup) and destination (drop-off) locations and return the appropriate price estimate, including the currency.

Order create API

Mileus calls this API when a passenger-driver match is found during the watchdog search. RH operator should notify the driver about this order. This API is expected to be asynchronous, the response of the driver is later passed to Mileus via either /order/driver-accept or /order/driver-cancel API endpoint. However, the orderId needs to be returned synchronously so that it can be later recognised by Mileus when used for other calls.

Request payload:

  • passengerId - ID (in the RH system, as passed in the request to the Mileus /auth endpoint) of the passenger to order the ride for
  • driverId - ID (in the RH system, as received by Mileus in the events ingestion) of the driver that should perform the ride
  • origin - location object defining where the ride should start
  • destination - location object defining where the ride should end
  • pickupTime - date-time value defining when the ride should start, i.e. when the passenger is expected to be ready to get into the car (and also when the driver should be ready at the pickup location)

Response payload:

  • orderId - ID (unique in the RH system) of the order generated by this request (used later for reference)

Order accept API

Mileus calls this API when the order is accepted from the passenger side which is the final confirmation that the ride is going to happen. This API can by either synchronous or asynchronous, in case of sync version the RH operator immediately responds with ok or not ok (for example the driver has canceled the ride in the meantime), in case of async version the RH operator will pass the confirmation result to Mileus via the /order/confirm endpoint.

Request payload:

  • orderId - ID of the order (as previously returned by the Order create API of the RH operator)

Response payload:

  • status - OK (confirmation that the order has been successfully confirmed in case this API is synchronous)

Order state API

This API is used for retrieving the state of an order, it serves as a safety net for cases when

  • Order accept API is implemented synchronously and it times out (so Mileus doesn't know whether the confirmation succeeded or not), or
  • Order accept API is implemented asynchronously and the confirmation call to the /order/confirm Mileus endpoint is not made before the OrderConfirmationTimeout occurs.

Using this endpoint, Mileus can determine whether the order has been confirmed successfully or not even if one of the errors above occurs.

Request payload:

  • orderId - ID of the order (as previously returned by the Order create API of the RH operator)

Response payload:

  • state - one of the status codes for the order in the RH operator system, for example CREATED, ACCEPTED, PICKUP_ARRIVAL, CANCELED_BY_DRIVER (the particular status set which means that the order has been confirmed successfully can be defined by the RH operator during the integration with Mileus)

Order cancel API

Mileus calls this API whenever the order in the RH operator system needs to be canceled from the passenger side, so the ride shouldn't happen and the driver should be notified.

Request payload:

  • orderId - ID of the order (as previously returned by the Order create API of the RH operator)
  • reason - a status defining why the cancel happened, one of the following values:
    • DRIVER_ACCEPT_TIMEOUT - the driver didn't accept the order (the Mileus /order/driver-accept API wasn't called) in time before the DriverAcceptTimeout occurred
    • PASSENGER_ACCEPT_TIMEOUT - the passenger didn't respond to the offered match in time before the PassengerAcceptTimeout occurred
    • ORDER_CONFIRMATION_TIMEOUT - the order wasn't confirmed by the RH operator (the Mileus /order/confirm API wasn't called) in time before the OrderConfirmationTimeout occurred
    • SEARCH_TIMEOUT - the order wasn't processed (driver hasn't accepted yet) in time before the SearchTimeout occurred
    • PASSENGER_CANCEL - the passenger canceled the watchdog search

Notification API

This API is called by Mileus when there is an important update to the watchdog search state for a particular user (for example when a match is found) and it's used to let the user know about updates even when the RH app is closed.

Request payload:

  • passengerId - ID (in the RH system, as passed in the request to the Mileus /auth endpoint) of the passenger to be notified
  • code - a code describing what kind of update happened, this can be used by the RH operator to modify the content of the push notification to be more precise (instead of just a generic message that something has changed), for example say that a match has been found or that the ride has been canceled instead of only saying that there is an update and the user should open the app to check. The code can be used to distinguish between visible and background notifications. The code can have one of the following values:
    • CONFIRMATION_FAILED - the confirmation of the ride has failed, the ride is not going to happen and the search continues
    • CONFIRMATION_SUCCEEDED - the ride has been successfully confirmed, the passenger should get on the way to the PT stop
    • DRIVER_CANCEL - the driver has canceled the ride
    • FOREGROUND_LOCATION_NEEDED - the user needs to open the app and share the foreground location in order to start the search
    • MATCH_FOUND - a match has been found
    • PASSENGER_ACCEPT_TIMEOUT - the passenger has failed to accept the ride in time, the search is canceled
    • SEARCH_START_FAILED - watchdog was unable to start (location wasn't obtained), the search is canceled
    • SEARCH_STARTED - watchdog search has been successfully started
    • SEARCH_STARTING_SOON - background notification starting background location sync one minute before scheduled watchdog
    • SEARCH_TIMEOUT - the time for the watchdog search is up
  • details - (for later use, not specified yet) set of values which can be used to enhance the message content with additional details, for example the estimated price of the matched ride or the time remaining to planned departure of the passenger from the origin