Business - Trips

The Admin interface handles web service calls from the Admin web gui. The base url for this is at:

/api/business-admin

A JSON file with OpenAPI data about all business-related admin APIs can be downloaded here.

Get trip cost details

Gets the list of trip cost details for a specified trip (it’s a Paged List APIs, as explained in the introduction):

GET /v1/trips/cost-details/{t}

Gets the list of trip cost details for a specified trip

Parameters

t (string) – The guid of the trip

Status Codes

200 OK – Success

t: Trip Guid (Guid)

Returns a Json positive response and the list of all the cost details for the trip corresponding to the trip guid provided in the request:

[
  {
    "OriginatorKey": "bl-cost",                                                       // String
    "CreatedDate": "2020-09-03T06:48:13Z",                                            // DateTime
    "Labels": "{\"en\":\"Total trip cost:\",\"it\":\"Costo totale della corsa:\"}",   // String
    "ValueLabels": null,                                                              // String (nullable)
    "Value": "2ddc0f63-e924-4fba-8e31-fa5803bf1e39",                                  // String
    "ValueType": 4,                                                                   // Int
    "ID": 2613                                                                        // Int
  },
  ...
]

The value of the OriginatorKey property can be one of the value described in Trip Details.

The ValueType field can be one of the AdditionalValueTypes enumeration.

The type of the contents of the Value field depends on the value specified in ValueType field

Returns a plain Json negative response if the trip guid does not correspond to any existing record.

Get trip payments

Gets the list of payments for a specified trip (it’s a Paged List APIs, as explained in the introduction):

GET /v1/trips/{t}/payments

Gets the list of payments related to a trip

Parameters

t (string) – The guid of the trip

Status Codes

200 OK – Success

t: Trip Guid (Guid)

Returns a Json positive response and the list of all the cost details for the trip corresponding to the trip guid provided in the request:

[
  {
    ID: 1,                                                  // Int
    Type: 0,                                                // Int
    Status: 4,                                              // Int
    Amount: 12.3,                                           // Decimal
    CreatedDate: "2021-01-01T05:00:00Z",                    // Date
    LastExecutionAttempt: "2021-01-01 06:00:00",            // Date (nullable)
    LastExecutedBy: "Administrator",                        // String (nullable)
    Note: "Notes on the payment"                            // String
  },
  { ... }
]

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

t: Trip Guid (Guid)

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: "{"en":"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.

Apply coupon to a trip

Applies a coupon to an existing trip

POST /v1/trips/apply-coupon

Applies a coupon to a trip

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_InvalidElement: No trip guid or coupon code has been provided
err_NoTripFound: No trip was found for the provided guid
err_NoCouponFound: No coupon was found for the provided code
err_CommunityMismatch: The coupon community filter does not match the user’s communities
err_CouponEffectDates: The provided coupon cannot be used at the date and hour in which the trip has been started
err_PromotionsAlreadyApplied: A promotion can be applied to the provided trip, and the coupon is not cumulable with other discounts
err_CouponAlreadyApplyed: A coupon has already been applied to the trip
err_CouponAlreadyUsed: The provided coupon has already been used by the user