Business - Trips
The Mobile interface handles web service calls from the mobile app. The base url for this is at:
/api/business-mobile
A JSON file with OpenAPI data about all business-related mobile APIs can be downloaded here.
Apply coupon to a trip
Applies a coupon to an existing trip
- POST /v1/trips/apply-coupon
Applies a coupon to a trip
- Query Parameters
t (string) –
- Status Codes
200 OK – Success
The API accepts a JsonBody with the following data:
{
Trip: "2abd7aa3-3a80-47e7-b6de-2e411d297434", // Guid
Coupon: "coupon-code" // String
}
where both Trip and Coupon are mandatory.
The API will apply the coupon to the trip (also recalculating the total cost if it was already computed) and respond with a plain Ok response, or with one of the following error codes:
err_InvalidElementNo trip guid or coupon code has been provided
err_NoTripFoundNo trip was found for the provided guid
err_TripUserMismatchThe currently logged user is not the one relatedo to the provided trip
err_NoCouponFoundNo coupon was found for the provided code
err_CommunityMismatchThe coupon community filter does not match the user’s communities
err_CouponEffectDatesThe provided coupon cannot be used at the date and hour in which the trip has been started
err_PromotionsAlreadyAppliedA promotion can be applied to the provided trip, and the coupon is not cumulable with other discounts
err_CouponAlreadyApplyedA coupon has already been applied to the trip
err_CouponAlreadyUsedThe provided coupon has already been used by the user
Get trip additional costs
Gets the paged list (see Paged List APIs) of existing additional cost for the specified trip
- GET /v1/trips/{guid}/additional-costs/list
Gets a list of additional amount types
- Parameters
guid (string) – The guid of the trip
- Status Codes
200 OK – Success
The API responds with the data of the specified additional cost:
[
{
ID: 1, // Int
CreatedDate: "2021-01-01 06:00:00", // Date
LastUpdated: "2021-01-01 06:00:00", // Date
Amount: 10.30, // Decimal
Notes: "...", // String (nullable)
TripGuid: "b5849483-ee93-4ca5-961a-6e21dc8c56dd", // Guid
StartLocationName: "Milan", // String
StartTimestamp: "2021-01-01 06:00:00", // Date
EndLocationName: "Milan", // String
EndTimestamp: "2021-01-01 06:00:00", // Date
TypeID: 1, // Int
CostType: 0, // Int
Labels: "Speed Fine // String
}
]
where the value of CostType represent the cost macro-type, and is among the ones
described in the AdditionalCostTypes enumeration, and TripGuid and TypeID
are reference to the trip the cost is related to and its additional cost type.
Retrieve Trip History
Retrieves the history of trips for the current user, with costing data
The API accepts an input body like this:
{
fromDate: "2012-04-23T18:25:43.511Z",
toDate: "2012-04-23T18:25:43.511Z"
}
and returns a list of trips opened inside a time range, defined in the
configuration variable MAX_TRIP_HISTORY_USER_DAYS.
If both dates are sent as null, the system will set the time range as ending at the current time. If only one of the two dates is sent as not null, the system will set the time range as starting/ending at the provided time. If both the dates are sent as not null, the system will check if the defined time range exceedes the configuration variable, and if so will set the time range as ending at the provided end time and overwrite the provided start time.
The API will return a response like this:
{
Trips: [
{
Guid: "d9f1d223-782b-414e-81aa-918cc4105b45", // Guid
MovementAuthority: "840dcbc1-4f53-4878-a0c9-cf5916b6c7dc", // Guid
DeletionDate: null, // DateTime (nullable)
IsCompleted: true, // Boolean
Status: 1, // Int
Index: 0, // Int
StartLocationName: "Milan", // String
StartLocationLatitude: 45.46417, // Double (nullable)
StartLocationLongitude: 9.19, // Double (nullable)
StartTimestamp: "2001-01-01T01:01:01Z", // DateTime
EndLocationName: "Milan", // String
EndTimestamp: "2001-01-01T02:01:01Z", // DateTime (nullable)
EndLocationLatitude: 45.46417, // Double (nullable)
EndLocationLongitude: 9.19, // Double (nullable)
Details: [
{
Guid: "ca9e1a11-cc86-4525-aadd-9f4ae176b1cd", // Guid
Deletiondate: null, // DateTime (nullable)
OriginatorKey: "detail key", // String
Labels: "detail name labels", // JSON stringified array of localized strings (nullable)
ValueLabels: "value labels", // JSON stringified array of localized strings (nullable)
Value: "123", // String
ValueType: 0 // Int
},
...
],
Events: [
{
Guid: "7806f52d-ef6a-4c2c-a297-b8124728e0f5", // Guid
Timestamp: "2001-01-01T01:01:01Z", // DateTime
Latitude: 45.46418, // Double (nullable)
Longitude: 9.191, // Double (nullable)
Source: 2, // Int (enum TripEventSource)
Type: 1, // Int (enum TripEventType)
AdditionalData: "", // JSON stringified dictionary (nullable)
OriginatorKey: null // Guid (nullable)
},
...
],
UserId: "6a2f4328-275c-48e4-978d-0e92a58dc6d0", // Guid
EquipmentReference: "...", // String (nullable)
ServiceReference: "...", // String (nullable)
ActualDurationSeconds: 3900, // Int (total running time in seconds)
ActualMileageKm: 25, // Int
Duration: 4000 // Int (total trip time in seconds),
TotalTripCost: 15.5, // Decimal (base trip cost)
TotalAdditionalCost: 10, // Decimal (additional expenses total cost)
IsPaid: true, // Boolean
CouponCode: "..." // String (nullable)
},
...
]
}
The API will return a generic error if no user is found for the data set in the provided authentication token.
The value of the IsCompleted property is always set to true for the trip retrieved from this API.
The value of the OriginatorKey property of the trip’s details can be one of the value
described in Trip Details.
The value of the property IsPaid is set to true if all the related payments are either in the payed or not to be payed
status (see PaymentTypes for reference)