Create / Update
- Remco Groot Beumer (Unlicensed)
- Niels
- Ard Broos
- 1 General
- 1.1 Update
- 2 Credentials
- 3 Rate limiting
- 4 Revisions
- 5 Specification
- 5.1 TEST
- 5.2 PROD
- 5.3 XSD
- 5.3.1 Assignment
- 5.3.2 Location
- 5.3.3 Checklists
- 5.3.4 Vehicle
- 5.3.5 DriverDetails
- 5.3.6 InsuranceDetails
- 5.3.7 BillingAgreements
- 5.3.8 ExternalReference
- 5.3.9 UpdateAssignmentStatusResponse
General
This interface is used for creating and updating assignments for towers connected to the Assistance Online platform.
Update
It is possible to update the following properties of an order:
Locations
Load
Interim location
Destination
PurchaseOrderNumber
FinishDateTime of Assignment
Type of Assignment
Remarks
Vehicle Remarks
Location Remarks
Assignment Description
Assignment Remark
Assignment PersonsToTransport
ReportedBy
Credentials
The API uses OAuth2 with Bearer tokens. Please contact ao@rgbplus.nl to request credentials for this API.
Every request with the API must have a Bearer token. You can request this token via the following token endpoints:
https://berger.assistanceonline.nl/auth/connect/token for our production environment
https://berger.test.assistanceonline.nl/auth/connect/token for our test environment
The json response contains an 'access_token'. You should use this token as Authorization header:
Rate limiting
The API uses rate limiting to prevent misuse. The limit is 1000 requests per 5 minutes. The following response will be given when this limit is reached:
HTTP 429 Too Many Requests
retry-after: 1
API calls quota exceeded! maximum admitted 1000 per 5m.The retry header tells that the client can retry after 1 second.
Successful requests will return the following headers:
x-rate-limit-limit: 5m
x-rate-limit-remaining: 999
x-rate-limit-reset: 2022-02-03T12:57:44.7280454Z Revisions
Date | By | Property | Change |
|---|---|---|---|
04-06-2018 | RGB | Assignment.finishDateTime | Field added |
04-06-2018 | RGB | Location.locationRole | Enumerations mutated from Unload to Destination Enumerations mutated from Depot to LayoverLocation |
11-06-2018 | RGB | Location.MainRoad.Direction | Non mandatory |
08-08-2018 | RGB | Assignment.type | Enumerations added for PlannableTransportation and PlannableTransportation. Removed enumeration for Transportation |
12-02-2019 | RB | - | Added open-api (swagger) specification |
28-01-2020 | AB | Assignment.BillingAgreement | Added object BillingAgreements. Only with property FirstServiceKms for now. |
17-07-2020 | AB | Checklists | Added checklists |
24-11-2020 | MA | Assignment.BillingAgreement.SecondServiceKms | Added SecondServiceKms to BillingAgreements |
09-07-2021 | NW | UpdateAssignmentRequest | Added PUT endpoint for updating assignments and GET update-status for retrieving the status of the update |
01-11-2021 | NW | Assignment.FinishDateTimeSecondService | Added optional datetime field to provide the expected unload datetime of the transport after first service |
14-04-2022 | MA | Assignment.Cause | Added optional cause field |
05-10-2022 | AB | ExternalReferences | Added options field |
09-12-2022 | NW | Assignment | DateTime replaced by DateTimeOffset in CreateAssignmentRequests |
25-01-2023 | NW | Vehicle.Properties | Added DriveShaft (replacing is4x4) and YearOfManufacture |
14-06-2023 | AB | Vehicle.Properties | Added IsTrailer |
07-08-2023 | NW | Assignment.ReportedBy | Added ReportedBy field to Assignment |
13-09-2023 | AB | Contact.Email | Added Email field to Contact |
04-09-2024 | NW | Vehicle.Properties | Added LicensePlateCountryCode |
Specification
TEST
Open-api specification: https://berger.test.assistanceonline.nl/api/assignments-external/v2/swagger/v1/swagger.json
Swagger-ui: https://berger.test.assistanceonline.nl/api/assignments-external/v2/swagger/
PROD
Open-api specification: https://berger.assistanceonline.nl/api/assignments-external/v2/swagger/v1/swagger.json
Swagger-ui: https://berger.assistanceonline.nl/api/assignments-external/v2/swagger/
XSD
| Request | Response |
|---|---|---|
Create Assignment |
|
|
Update Assignment |
|
|
Assignment
General set of fields, describing the general assignment characteristics
Element | Description | Type | Mandatory | Example |
|---|---|---|---|---|
type | Requested type of service | Enumeration | Yes | Breakdown, PlannableTransportation, NonPlannableTransportation, Damage, ErrorParked, Seizure, Security, AbandonedVehicle, Cleaning |
receiver | Unique AO identifier for the towing company | String | Yes | 1001 |
sender | Unique AO identifier for the customer | String | Yes | Allianz |
debtor | Identifier of the paying party within the assignment, in case this isn't the sender | String | Allianz XX | |
description | Description of the (cause of the) event or requested services | String | Car drops oil | |
remark | Extra remark for the towing company | String | Driver is not with his vehicle | |
customerReference | Unique reference from the customer | String | S34897 | |
purchaseOrderNumber | Purchase order reference as it will be shown on the invoice | String | P123456 | |
invoiceText | Optional text which will be printed on the invoice | String | Costs to the direction of Jan Jansen | |
startDateTime | Requested start date/time from which point the assignment may be executed. This could be in the future. If empty the current date and time will be used | Date | 2017-12-06T10:23:35.520Z | |
finishDateTime | Optional requested end date/time | Date | 2017-12-06T10:23:35.520Z | |
finishDateTimeSecondService | Optional requested end date/time of transport after first service | Date |
| 2017-12-06T10:23:35.520Z |
orderDateTime | Optional order date/time. May be in the future. If empty the current time is used as the orderdate time | Date | 2017-12-06T10:23:35.520Z | |
personsToTransport | Number of people to be transferred | Number | 3 | |
securityRequired | Security transport requested (only used for towing assignments) | Boolean | True | |
billingAgreements | Object with optional price agreements | BillingAgreements | ||
cause | Optional text with the cause of the incidentexe | String |
| Accu |
reportedBy | Optional name of the reporter | String |
| Jan Janssen |
Location
Describes the location and the role it takes in the assignment. This could be a public road or an address. Geo coordinates are optional and if provided leading. Every assignment must have one loading location
Element | Description | Type | Mandatory | Example |
|
|
|
|
|
|---|---|---|---|---|---|---|---|---|---|
locationRole | Describes the role which the location has in the assignment. If the assignment does not require transportation, 1 location (load) will be sufficient | Enumeration | Yes | Load, Destination, LayoverLocation, PersonDestination, LuggageDestination |
|
|
|
|
|
locationType | Describes if the location is a mainRoad or an address. Based on this choice the fields below the yellow lines (below) must be provided | Enumeration | Yes | mainRoad of address |
|
|
|
|
|
remark | Remark for the provided location | String | On crossroads with Central street |
|
|
|
|
| |
name | Optional name of the location | String | Makro Zwolle |
|
|
|
|
| |
mainRoad (if locationType == mainRoad) |
|
|
|
|
| ||||
hmp | Hectometre post | Number | Yes | 17.1 |
|
|
|
|
|
direction | Direction sign | Enumeration | Yes | Li of Re |
|
|
|
|
|
roadname | Main road name (Highway) | String | Yes | A35 |
|
|
|
|
|
hmpaddition | Hectometre post addition | String | l |
|
|
|
|
| |
countryIso2 | Countrycode in ISO2. If empty than default = NL | String | Yes | NL |
|
|
|
|
|
|
|
|
|
| |||||
address (if locationType == address) |
|
|
|
|
| ||||
streetName | Streetname | String | Dorpstraat |
|
|
|
|
| |
houseNumber | Address number | String | Yes | 18a |
|
|
|
|
|
city | City | String | Zwolle |
|
|
|
|
| |
postalCode | Zip code | String | Yes | 8102XC |
|
|
|
|
|
countryIso2 | Countrycode in ISO2. If empty then default = NL | String | Yes | NL |
|
|
|
|
|
|
|
|
|
| |||||
coordinates |
|
|
|
|
| ||||
latitude | X coordinate in geodecimal formaat (DD) | Number | 31.157845 |
|
|
|
|
| |
longitude | Y coordinate in geodecimal formaat (DD) | Number | 5.15478 |
|
|
|
|
| |
|
|
|
|
| |||||
restrictions |
|
|
|
|
| ||||
IsParkingGarage | Describes if the address provided is a parking garage | Boolean | true |
|
|
|
|
| |
MinEuroclassification | Describes if the address is within a environmental zone | Number | 5 |
|
|
|
|
| |
|
|
|
|
| |||||
openinghours (list) |
|
|
|
|
| ||||
dayOfWeek | Day of the week | Enumeration | Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday |
|
|
|
|
| |
from | Start opening time | String | 08:00 |
|
|
|
|
| |
to | Eind opening time | String | 18:00 |
|
|
|
|
| |
|
|
|
|
| |||||
contact (list) Phone: the first contact with the name 'Phone'. The Phone field will be used CellPhone: the first contact with the name 'CellPhone'. The Phone field will be used Email: the first contact with the name 'Email'. The Email field will be used The other contacts will be ignored. |
| ||||||||
Name | This field is not used and can be left out | String | Jan Jansen |
|
|
|
|
| |
Phone | Telephone number on which the location can be reached | String | 0123-4567890 |
|
|
|
|
| |
Email address | String |
| ao@rgbplus.nl |
|
|
|
|
| |
Role | This field is not used and can be left out | Enumeration |
| Primary, Other |
|
|
|
|
|
Checklists
Checklists that must be completed by the contractor.
DataExe.V2 | AO | Description | Type | Mandatory | Example |
|---|---|---|---|---|---|
ExternalIdentifier | External identifier | String | Yes | checklist1 | |
Name | Name | String | Yes | Intake | |
ProcessStep | ChecklistProcessStep | For whom the checklist is intended: the order intake colleague or the driver. Options:
| Enumeration | Yes | OrderIntake |
items: List of ChecklistItems | |||||
Id | Id | Number | Yes | 1 | |
Identifier | Identifier | String | Yes | checklist-item1 | |
Description | Description | String | Yes | What is the mileage of the vehicle? | |
ChecklistItemType | ChecklistItemType | Options:
| Enumeration | Yes | Number |
Value | Value | Default value of the checklist item | String |
| 12500 |
IsRequired | IsRequired |
| Boolean | Yes | true |
ValidationRegex | ValidationRegex | Indicates against which regular expression the checklist answer should be validated | String |
| |
ValidationMessageKey | ValidationMessageKey | String |
| ||
Options | Options | List with options. Used when ChecklistItemType is Options | List<String> | Yes (only when ChecklistItemType = Options) |
|
Vehicle
Description of the vehicle in need of service. Dutch vehicles will be enriched with data from the national RDW
Element | Description | Type | Mandatory | Example |
|---|---|---|---|---|
licensePlate | License plate | String | x | AB12AB |
chassisNumber | Chassis number | String | 234234SD23FDSF | |
mileage | Mileage at the point of service | Number | 123456 | |
vehicleType | Description of the vehicle type | Enumeration | x | car, truck, trailer, boat, bike, other |
remark | Remark of the vehicle | String | Burned down | |
state | ||||
isLocatedInWater | Vehicle is in the water | Boolean | True | |
metersToQuay | Distance to quay | Number | 18 | |
isRollable | Vehicle is rollable | Boolean | True | |
isSteeringWheelLocked | Vehicle steering wheel is locked | Boolean | True | |
hasTrailer | Vehicle has trailer attached | Boolean | True | |
hasBikeCarrier | Vehicle has bike carrier attached | Boolean | True | |
hasRoofBox | Vehicle has roofbox | Boolean |
| True |
locationKeys | Known location for keys | String | Under left wheel | |
locationDocuments | Known location for papers | String | Dashbord | |
properties | ||||
make | Make of the vehcile | String | Ford | |
model | Type of the vehicle | String | Focus D1 | |
color | Color of the vehicle | String | Zwart | |
weightKg | Weight of the empty vehicle | Number | 1500 | |
LengthCm | Length of the vehicle in cm | Number | 500 | |
heightCm | Height of the vehicle in cm | Number | 180 | |
widthCm | Width of the vehicle in cm | Number | 230 | |
fuelType | Type of fuel system | Enumeration | Diesel, Gas, Benzine, Hybrid, Electric, Other | |
isManualGear | Manual gear | Boolean | True | |
is4x4 | 4x4 Deprecated: Please use | Boolean | False | |
isForeign | Vehicle is not registered in the NL | Boolean | False | |
driveShaft | Drive shaft type | Enumeration |
| All, Front, Rear |
yearOfManufacture | Year of manufacture | Number |
| 2023 |
licensePlateCountryCode | Country code as displayed on the license plate | String |
| NL, B, D, E, F, GB |
DriverDetails
Describes the driver of the vehicle (if known).
Element | Description | Type | Mandatory | Example |
|---|---|---|---|---|
gender | Gender | Enumeration | male, female | |
initials | Initials | String | RCB | |
prefixes | Prefix | String | van der | |
firstName | First name | String | Ron | |
lastName | Last name | String | Jansen | |
Email address | String | |||
phone | Phone | String | 0572-05721 | |
cellphone | Cellphone | String | 06-12345678 | |
licenseNumber | Drivers license number | String | 123456789 | |
licenseExpires | Drivers license expiration date | Date | 2018-01-01 | |
address | ||||
streetName | Street | String | Dorsplein | |
houseNumber | House number | String | 2s | |
city | City | String | Deventer | |
postalCode | Zip code | String | 8101LK | |
countrIso2 | Countrycode in ISO2. If empty, then default = NL | String | NL | |
InsuranceDetails
Describes the person/company which is on the insurance card of the vehicle.
Element | Description | Type | Mandatory | Example |
|---|---|---|---|---|
name | Name insurance company | String | Achmea | |
policyNumber | Insurance policy number | String | 12345678 | |
validTillDate | Expiration date of the policy | Date | 2017-12-06 | |
typeOfCoverage | Type of coverage of the vehicle | Enumeration | WA, WAplus, WACasco, nonInsured | |
policyOwnerDetails | ||||
gender | Gender | Enumeration | male, female | |
initials | Initials | String | RCB | |
prefixes | Prefix | String | van der | |
firstName | First name | String | Ron | |
lastName | Last name | String | Jansen | |
E-mail address | String | |||
phone | Phone | String | 0572-353535 | |
cellphone | Cellphone | String | 06-12312312 | |
address | ||||
streetName | Street | String | Dorpstraat | |
houseNumber | House number | String | 18a | |
city | City | String | Zwolle | |
postalCode | Zip code | String | 8102XC | |
countryIso2 | Countrycode in ISO2. If empty, then default = NL | String | NL | |
BillingAgreements
Information about optional price agreements
Element | Description | Type | Mandatory | Example |
|---|---|---|---|---|
FirstServiceKms | Price agreement for the distance to be charged of the first job | int | Yes | 25 |
SecondServiceKms | Price agreement for the distance to be charged of the transport after first service job | int | No | 75 |
ExternalReference
Optional collection of name-value pair that will be sent back to the sender in the Acceptance en CompletionReport request. AO can add some additional references to it.
Element | Descripton | Type | Mandatory | Example |
|---|---|---|---|---|
Name | Name of the external reference | string | Yes | order-identificaton |
Value | Value of the external reference | string | Yes | XV-006-HJIU-2022 |
UpdateAssignmentStatusResponse
Element | Description | Type | Mandatory | Example |
|---|---|---|---|---|
success | Indicator if the request has been processed succesfully | Boolean | Yes | true |
result | Textual result representation | String | Yes | InProgress |
reasonNoSuccess | Not used in this context | String | No |
|
changes: List of ChangeResultResponse | ||||
description | Textual description of the change | String | Yes | Edit Destination |
status | Current status of the change | Enumeration | Yes | None, |