Business - Users
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 user payment methods
Returns the Paged List APIs of active payment methods for the user
- GET /v1/biz-users/{guid}/payment-methods
Gets the list of payment methods for the specified user
- Parameters
guid (string) – The user to retrieve the payment methods for
- Status Codes
200 OK – Success
Returns the user’s payment methods:
[
{
"ID": 2, // Int
"Name": "payment method name", // String
"Type": 0, // Int
"CreatedDate": "2021-01-01T00:00:00Z", // Date
"LastValidTransaction": "2021-01-01T:00:00:00Z", // Date (nullable)
"LastErrorDescription": "Error message", // String (nullable)
"IsPreferred": true, // Boolean
"CardHolderName": "Name of the credit card holder", // String (nullable)
"CardNumber": "Number of the credit card", // String (nullable)
"CardExpiryMont": "1", // String (nullable)
"CardExpiryYear": "2022", // String (nullable)
"CardBrand": "Credit card circuit" // String (nullable)
},
{ ... }
]
where the Type property can be one of the value defined in the PaymentMethodTypes enumeration.
Get user wallet
Gets the user’s wallet:
- GET /v1/biz-users/{guid}/wallet
Gets the wallet for the user GUID
- Parameters
guid (string) – The user to retrieve the wallet for
- Status Codes
200 OK – Success
- POST /v1/biz-users/{guid}/wallet
Modifies the wallet data for the specified user
- Parameters
guid (string) – The user to retrieve the wallet for
- Status Codes
200 OK – Success
Returns the wallet data for the user:
{
ID: 1234, // Int
CreatedDate: "2001-01-01T01:01:01Z", // DateTime
LastUsed: "2021-01-01T01:01:01Z", // DateTime (nullable)
TokenBalance: 1, // Int
MinutesBalance: 0, // Decimal
KmBalance: 10 // Decimal
}
Update user wallet
Updates the balance on the user’s wallet:
- GET /v1/biz-users/{guid}/wallet
Gets the wallet for the user GUID
- Parameters
guid (string) – The user to retrieve the wallet for
- Status Codes
200 OK – Success
- POST /v1/biz-users/{guid}/wallet
Modifies the wallet data for the specified user
- Parameters
guid (string) – The user to retrieve the wallet for
- Status Codes
200 OK – Success
The API accepts a body in the following format:
{
TokenBalance: 1, // Int
MinutesBalance: 10, // Decimal
KmBalance: 50 // Decimal
}
The API will search for the user wallet to be updated, and if no wallet has been found it will create a new one.
The API will accept values as positive, negative or zero number, and will respond with a generic error if no user has been found for the specified Guid or with one of the following errors:
err_InvalidBalanceOne of the provided balance is not in the correct format
err_MaxAmountReachedOne of the provided balance exceeds its maximum allowed value, as defined in the related environment variable
Get user additional costs
Gets the paged list (see Paged List APIs) of existing additional cost for the specified user
- GET /v1/biz-users/{guid}/additional-costs/list
Gets a list of additional amount for a user
- Parameters
guid (string) – The guid of the user
- 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: "{"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.
Get payments
Gets the paged list (see Paged List APIs) of the user’s payments
- GET /v1/biz-users/{guid}/payments
Gets a list of payments for a user
- Parameters
guid (string) – The guid of the user
- Query Parameters
statuses (string) – An optional list of payments status
types (string) – An optional list of payments type
- Status Codes
200 OK – Success
The API accepts the following filters in the query params: * statuses (comma separated list of payment statuses, as int value, to be extracted) * types (comma separated list of payment types, as int value, to be extracted)
and responds with a plain error, or with the following format:
[
{
ID: 1, // Int
Type: 0, // Int
Status: 0, // Int
Amount: 12.3, // Decimal
LastExecutionAttempt: "2021-01-01 06:00:00", // Date (nullable)
LastExecutedBy: "Administrator", // String (nullable)
Note: "Notes on the payment", // String
ExtUserGuid: "1414dec6-31a1-403d-a426-446147e807b2", // Guid
ExtUser: "User Name", // String
TripGuid: "be9896c4-8feb-4daa-aa3a-0170a8702b18", // Guid (nullable)
StartLocationName: "Milan", // String (nullable)
StartTimestamp: "2021-01-01 06:00:00:", // Date (nullable)
EndLocationName: "Milan", // String (nullable)
EndTimestamp: "2021-01+01 06:00:00", // Date (nullable)
CostType: 0, // Int (nullable)
CostLabel: "{"en":"Speed Fine", ... }, // String (nullable)
ArticleID: 3, // Int (nullable)
ArticleQuantity: 1, // Int (nullable)
ArticleLabels: "{"en":"Article Name", ...} // String (nullable)
},
{ ... }
]
The property Type can assume values among the one defined in the PaymentTypes enumeration.
The property Status can assume values among the one defined in the PaymentStatuses enumeration.
The property CostType can assume values among the one defined in the AdditionalCostTypes enumeration.
The trip related properties (guid, location names and timestamp) are valorized only if the Type property is either
TripPayment, Fine or AdditionalCost.
The cost related properties (type and label) are valorized only if the Type property is either Fine or AdditionalCost.
The article related properties (ID, quantity and labels) are valorized only if if the Type property is ArticlePurchase.