General Information
The Digital Fleet Push API allows you to receive updates to truck and ticket status as they are processed by Digital Fleet. While the Digital Fleet API allows you to retrieve data on demand, the Push API lets us send you updates in real time. The Push API uses a simple protocol, sending JSON-formatted data over HTTP.
Configuration
To configure the Push API
- Client Administration rights are required
- Access Client Management --> General, which can be found in Settings (gear icon)
- In the Integrations modal, edit the dispatch system you are testing against and select the Push Endpoints tab
- Enter the External URL for your HTTP endpoint, to which we will POST data. While not required, we suggest you use HTTPS in order to protect the data being transmitted.
- Enter the login/password pair, which we will included in an HTTP Basic Authentication header in all requests to your endpoint.
Message Protocol
This describes version 1.0 of the messaging protocol. Digital Fleet uses the Semantic Versioning standard for this API. To ensure compatibility with future changes, you should ignore unrecognized fields or enumerated values.
The Push API makes HTTP POST requests, made to a given configured URL.
Headers
The following HTTP headers are notable:
-
Authorization: The Push API uses HTTP Basic Authentication
-
Content-Type: The Push API encodes the message payload using JSON. This header will be “application/json; charset=utf-8”.
-
X-DigitalFleet-Retry: If “true” then Digital Fleet has previously failed to deliver this message; otherwise “false”. See the Response section for more on delivery failure.
Payload
The request body will contain a single JSON-encoded object with the following fields:
-
Version: “1.0”
-
Events: This will be a list of one or more objects representing status or position updates, as described below.
Event Object Data
Event objects contain some common fields, and some optional fields depending on the type of the event. Some fields have enumerated values; see the Reference section below for possible values. Some events may not have data for all available fields.
All events may contain these common fields:
-
MessageId: Unique ID for this event. Always present
-
EventType: Indicates the general type of update. Will be one of TRUCK, TICKET, or POSITION. Always present
-
EventTime: UTC time stamp of the event, using ISO-8601 formatting. Always present
-
TruckName: Identifier for the statusing truck. Always present
-
Latitude: Current latitude of truck, as reported by GPS.
-
Longitude: Current longitude of truck, as reported by GPS.
-
Heading: Direction truck is travelling, as reported by GPS. In degrees.
-
Speed: Current speed truck is travelling, as reported by GPS.
-
SpeedUom: Unit in which “Speed” field is measured. Always “MPH” for miles per hour (but may be variable in future versions).
-
TriggeringPointId: For events triggered by geofence breaks, this is the Digital Fleet point ID for the relevant geofence.
-
VendorLocation: For events triggered by geofence breaks, this is the vendor point ID for the relevant geofence. Can be suppressed in the configuration of this dispatch integration.
- DriverUserId: The user id of the driver that was logged into the truck when the event was created
POSITION events will have no additional fields.
TRUCK events will have the following fields:
-
TruckEventCode: Identifies the truck-specific type of event being processed.
-
TruckStatusCode: Identifies the new truck status determined by processing this event.
TICKET events will have the following fields:
-
TicketEventCode: Identifies the ticket-specific type of event being processed.
-
TicketStatusCode: Identifies the new ticket status determined by processing this event.
-
TicketType: Identifies whether this is a Standard or Quick Route ticket. The presence and interpretation of ticket events and status codes is slightly different for different ticket types.
-
TicketNumber: Ticket number being updated.
-
TicketId: Digital Fleet ticket ID for ticket being updated.
-
OrderNumber: Order number/ID for ticket being updated.
-
OrderId: Digital Fleet order ID for ticket being updated.
Response
Upon successful processing of a message by your system, the Push API expects you to return an HTTP Success response (i.e., status code 200). Any other response will be interpreted by Digital Fleet as a delivery failure. Digital Fleet will periodically attempt to re-send messages which were not successfully delivered, up to a cut-off time limit (typically 2 hours).
Reference
This is the list of valid values for event and status codes. The names listed here are the typical defaults. Note that Digital Fleet statusing is highly flexible, and you may be configured to show event and status names with different labels. For example, it is common for truck event 3 (In Service ) to be displayed as “In Yard”. Additionally, some events and statuses depend on particular features or hardware setups, and may not appear for your configuration.
EventType
TRUCK |
An update caused by a truck-related event |
TICKET |
An update caused by a ticket-related event |
POSITION |
An update to the GPS location data for a truck |
TruckEventCode
1 |
Ignition On |
2 |
Ignition Off |
3 |
In Service |
4 |
Out Service |
5 |
Broken Down |
6 |
Emergency |
7 |
Yard Work |
8 |
Washout |
9 |
To Shop |
10 |
Begin Moving |
11 |
Stopped |
12 |
Location Log |
13 |
Illegal Power Up |
14 |
Illegal Power Cycle |
15 |
Leave |
16 |
Arrive |
17 |
Lunch Start |
18 |
Lunch End |
19 |
Leave Shop |
20 |
Broken Down (Loaded) |
21 |
Driver Begin Prep |
22 |
Washout Start |
23 |
Washout End |
24 |
Ready To Load |
25 |
Driver Begin Shutdown |
26-65 |
(Reserved for custom events) |
66 |
Mixer Data Submission |
TruckStatusCode
1 |
In Service |
2 |
Out Service |
3 |
Broken Down |
4 |
Emergency |
5 |
Yard Work |
6 |
To Shop |
7 |
Leave |
8 |
Lunch Start |
9 |
Driver Prep |
10 |
Washing Out |
11 |
Ready To Load |
12 |
Driver Shutdown |
13-42 |
(Reserved for custom statuses) |
TicketType
1 |
Standard Ticket |
2 |
Quick Route Ticket |
TicketEventCode
|
Standard Ticket |
Quick Route Ticket |
0 |
Ticket Created |
Route Created |
1 |
Ticket Assigned |
Route Assigned |
2 |
Begin Load |
|
3 |
To Job |
To Destination |
4 |
Arrive Job |
Arrive Destination |
5 |
Begin Pour |
|
6 |
Stop Pour |
|
7 |
To Yard |
|
8 |
Product Add |
|
9 |
Completed |
Route Completed |
10 |
Updated |
|
11 |
Ticket Void |
Route Cancelled |
12 |
Load Complete |
|
13 |
Arrive Pickup |
|
14 |
Delay At Job |
|
15 |
Truck Assigned |
|
16 |
To Pickup |
|
17 |
Deactivate |
|
18 |
Pause Pour |
|
19 |
Resume Pour |
|
TicketStatusCode
|
Standard Ticket |
Quick Route Ticket |
0 |
Ticket Created |
Route Created |
1 |
Ticketed |
Route Assigned |
2 |
Loading |
|
3 |
To Job |
To Destination |
4 |
Waiting |
Arrive Destination |
5 |
Pouring |
|
6 |
Returning |
|
7 |
Completed |
Route Completed |
8 |
Cancelled |
Route Cancelled |
9 |
Arrive Pickup |
|
10 |
Loaded |
|
11 |
Poured |
|
12 |
Truck Assigned |
|
13 |
To Pickup |
|
Sample Message
This is an example of a push message, containing each of a truck event, a ticket event, and a position status update event.
POST / HTTP/1.1
Authorization: Basic dGhlbG9nxxxxxxxxxxxxxxxx
Content-Type: application/json; charset=utf-8
X-DigitalFleet-Retry: False
{
"Version": "1.0",
"Events": [{
"EventTime": "2022-01-07T22:10:48.74Z",
"EventType": "TICKET",
"Heading": 188.182,
"Latitude": 41.0000,
"Longitude": -87.0000,
"MessageId": 780,
"OrderNumber": "2201061",
"Speed": 0.387,
"SpeedUom": "MPH",
"TicketEventCode": 9,
"TicketId": 9912600,
"TicketNumber": "2201061",
"TicketStatusCode": 7,
"TicketType": 1,
"TruckName": "757"
},
{
"EventTime": "2022-01-07T22:15:13.497Z",
"EventType": "TRUCK",
"Heading": 195.634,
"Latitude": 41.0000,
"Longitude": -87.0000,
"MessageId": 784,
"Speed": 88.683,
"SpeedUom": "MPH",
"TruckEventCode": 9,
"TruckName": "757",
"TruckStatusCode": 6
},
{
"EventTime": "2022-01-07T22:14:21Z",
"EventType": "POSITION",
"Heading": 195.634,
"Latitude": 41.0000,
"Longitude": -87.0000,
"MessageId": 781,
"Speed": 88.683,
"SpeedUom": "MPH",
"TruckName": "757"
}]
}
Comments
0 comments
Please sign in to leave a comment.