Trip Execution module

Start, Pause, Finish rental

/legs/:id/events

With this endpoint the user can start, pause, finish a rental using the bookingId in the path param.

POST https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/legs/:id/events

Path parameters

Field	Content	Note
id	“7b0846ab-8192-4c1b-8b30-454382074e9e”	Required. The booking id.

Request body parameters

Field	Content	Note
event	`SET_IN_USE`, `PAUSE`, `FINISH`	Required. The operation that should be perfomed.
time	“2022-02-04T15:30:08Z”	Required. Time when the operation was submitted.

Example for starting a new ride.

curl -L -X POST 'https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/legs/d079aa69-210e-41b5-88fa-f6651d69f166/events' \
-H 'x-api-key: API_KEY' \
-H 'api-version: 1.3.0' \
-H 'maas-id: 1324A-DFB3482-32ACD' \
-H 'Accept-Language: en' \
-H 'Content-Type: application/json' \
--data-raw '{
    "event": "SET_IN_USE",
    "time": "2022-02-04T15:30:08Z"
}'

Example for sending customer position in case of ride pause, resume and finish.

curl -L -X POST 'https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/legs/d079aa69-210e-41b5-88fa-f6651d69f166/events' \
-H 'x-api-key: API_KEY' \
-H 'api-version: 1.3.0' \
-H 'maas-id: 1324A-DFB3482-32ACD' \
-H 'Accept-Language: en' \
-H 'Content-Type: application/json' \
--data-raw '{
    "event": "PAUSE",
    "time": "2022-02-04T15:35:05Z",
    "asset": {
        "id": "0a6b5fc7-4047-4eb3-a853-f54c756f4694",
        "overriddenProperties": {
            "location": {
                "coordinates": {
                    "lat": 47.531683,
                    "lng": 19.035182
                }
            }
        }
    }
}'

Click to expand JSON data response

{
    "asset": {
        "overriddenProperties": [],
        "id": "6f4491ff-2f1a-4738-9958-827e70f95f70"
    },
    "assetType": {
        "id": "tier-escooter",
        "assetClass": "OTHER",
        "assetSubClass": "escooter",
        "sharedProperties": {
            "propulsion": "ELECTRIC",
            "fuel": "ELECTRIC"
        }
    },
    "from": {
        "coordinates": {
            "lng": 19.106785,
            "lat": 47.537065
        }
    },
    "id": "12a6ccab-0616-4ebc-9c5d-9eb2b0dd4740",
    "state": "IN_USE"
}

Error Responses

When booking a leg you may encounter a 400, 404 error response.

400 Bad Request Error

400 means that the validation of the request body has failed.

Click to expand JSON data response

{
    "message": "body should have required property 'event'",
    "errorCode": 4001,
    "statusCode": 400,
    "name": "BadRequestError"
}

403 Forbidden Error

403 means that the customer is blocked.

Click to expand JSON data response

{
    "message": "Customer is blocked.",
    "errorCode": 4403,
    "statusCode": 403,
    "name": "Forbidden"
}

404 Not Found Error

404 means that no bookings could be found with the submitted id.

Click to expand JSON data response

{
  "message": "No booking was found with id: d079aa69-210e-41b5-88fa-f6651d69f16.",
  "errorCode": 4203,
  "error": "NotFoundError",
  "statusCode": 404
}

409 Conflict Error

409 means that there is some conflict with the ride. It can be different with the following names:

NineBotBikeNotLocked
VehicleInFullCapacityMandatoryParking
VehicleNotLocked
VehicleOutOfMandatoryParkingZone
VehicleInNoParkingZone
VehicleOutOfBusinessZone
OutdatedPricingError
VehicleNotReachable
VehicleNotAvailable
PaymentMethodNotWorking
PaymentMethodNotProvided
AlreadyRunningRentalExists

Click to expand JSON data response

{
    "message": "User tried to end ride with an unlocked vehicle",
    "errorCode": 4004,
    "statusCode": 409,
    "name": "NineBotBikeNotLocked"
}

Leg progress

/legs/:id/progress

With this endpoint the user can start, pause, finish a rental using the bookingId in the path param.

GET https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/legs/:id/progress

Path parameters

Field	Content	Note
id	“7b0846ab-8192-4c1b-8b30-454382074e9e”	Required. The booking id.

curl -L -X GET 'https://platform.tier-services.io/data-sharing/tier_utrecht/tomp/legs/d079aa69-210e-41b5-88fa-f6651d69f166/progress' \
-H 'x-api-key: API_KEY' \
-H 'api-version: 1.3.0' \
-H 'maas-id: 1324A-DFB3482-32ACD' \
-H 'Accept-Language: en' 

Click to expand JSON data response

{
    "coordinates": {
        "lng": 19.106785,
        "lat": 47.537065
    }
}

Error Responses

When booking a leg you may encounter a 404 error response.

404 Not Found Error

404 means that no leg could be found with the submitted id.

Click to expand JSON data response

{
  "message": "No leg was found with id: d079aa69-210e-41b5-88fa-f6651d69f16.",
  "errorCode": 4203,
  "error": "NotFoundError",
  "statusCode": 404
}

404 Not Found Error

404 means that vehicle that is in the leg could not be found.

Click to expand JSON data response

{
  "message": "Used vehicles position can not be found",
  "errorCode": 4203,
  "error": "NotFoundError",
  "statusCode": 404
}