API Documentation V3.0

1 Changelog

Version	Date	Author	Update
2.1.1	06/01/2016	Jim Potter	- API release
3.0.0	12/28/2016	Jim Potter	- JSON document introduction - Method consolidation & deprecation
3.0.1	02/01/2017	Jim Potter	- Versioning table - Correction to jdDriver xml sample
3.0.2	03/02/2017	Jim Potter	- Updated Customer Field Length
3.0.3	07/11/2017	Jim Potter	- Added deliveryResponse document to allow for resend of deliveryReceipt in case of error/timeout

2 General Overview

At its most basic, JDISPATCH allows delivery drivers to collect an electronic copy of a signature on a touch enabled mobile device. Beyond that, it can also track a driver’s location as well as act as a rudimentary messaging app on a data enabled mobile device. This application, however, will run in a ‘batch mode’ for devices without fill-time data capabilities. Allowing even remotely located customers to take advantage of JDISPATCH’s basic functionality.

2.1 Basic JDISPATCH web service functionality

A common, integrated, JDISPATCH transaction would have a fairly straight-forward flow. An order is placed on the seller’s system, and the seller’s system processes the order up to the point of being dispatched for delivery. At that point, the seller system generates a dispatch transaction for a driver to send one or more invoices to the JDISPATCH API. Once JDISPATCH receives notice of the delivery, it will notify the driver of a pending delivery and push the order detail to their device. From there, the driver would deliver the product and take a signature of the party receiving the product. That signature is then passed back to the JDISPATCH server where it is saved off and available for future use. Once the signature is saved on the JDISPATCH server, it can optionally be passed back to the sellers system via the API if they wish to merge it on to an electronic copy of the invoice the customer received. After a delivery is made, the confirmation signature is instantly available within the JDISPATCH dashboard for any proof-of-delivery queries that may come in.

In addition, the seller has access to a number of tools to help them analyze their delivery performance. From within the JDISPATCH dashboard, a user sees real-time statistics of average processing and delivery time by driver and customer as well as driver efficiency. Beyond the real time statistics and graphs, the JDISPATCH user has the ability to extract detailed delivery information for analysis after the fact.

Communication between the driver’s mobile device and the JDISPATCH server does not have to be on-going. If the mobile device notices a loss of connectivity, it will operate in a ‘batch mode’ until connectivity is restored, at which point it will send through any deliveries that were processed during the loss of connectivity. Subsequently, any ‘batch’ transactions will be pushed back to the seller system at the time they are confirmed on the JDISPATCH server.

2.2 JDISPATCH Features

jDispatch Mobile Application	Connected	Batch Mode
Signature capture	Yes	Yes
Part delivery confirmation	Yes	Yes
Background location services	Yes
System to driver communication	Yes
Part pickup confirmation	Yes	Yes
‘One Off’ invoice scan and confirm	Yes
Push notifications	Yes
Driving directions	Yes
Route Optimization	Yes
jDispatch Dashboard	Connected	Batch Mode
Real-time delivery analysis	Yes
Real-time corporate delivery metrics	Yes
Signature recall	Yes	Yes
Delivery analysis extracts	Yes	Yes
Pickup dispatch	Yes	Yes
Driver communication	Yes
Driver 'on map' location tracking	Yes
Dashboard configuration	Yes	Yes
Quick phone registration	Yes	Yes

2.3 JDISPATCH Flow Diagram - Integrated

2.4 JDISPATCH Flow Diagram – Non-Integrated

3 Transaction API

3.1 Overview

In order for third-party systems to utilize the integrated features of JDISPATCH, they must utilize the JDISPATCH Transaction API, which allows third-party systems to create dispatch requests, and accept back subsequent delivery confirmations and signatures. The two transaction types utilized are a dispatch transaction and a delivery transaction

3.2 Basic JDISPATCH order transaction architecture

Overall, the JDISPATCH document stack can be broken down in to 2 main segments, delivery dispatch and delivery receipt. These two transactions would be the only required integration points for any third party system, as all other functionality of the product can be handled by the JDISPATCH web and mobile applications

Delivery Dispatch: This is the point where a delivery is dispatched from the third-party system
Delivery Receipt: This is a transaction that is passed back to a pre-configured URL utilized by the third-party system to take back delivery confirmations once they are processed by the JDISPATCH web application.

3.3 Document Structure

The information passed within a JDISPATCH API document can be sent via XML or JSON. All necessary information within a JDISPATCH API document is contained within an element tag. This is recognized by both a root <jDispatchElement> tag, and an ending </jDispatchElement> tag. Empty elements are allowed within a JDISPATCH API document and will be ignored upon document validation on the JDISPATCH server.

AMS has done their best to select semantic element names to avoid confusion when translating documents. Also, all tag names use Camel Case, indicating that the first letter of each word will be capitalized, and all subsequent letters are lower case. The first letter of the <jDispatchElement> elements will, however, be lower case.

3.4 XML Schema

Each of the JDISPATCH document layouts are described in an XML schema document, or, template. If you are unfamiliar with a schema document, the W3C site provides more information on this topic here: http://www.w3.org/standards/xml/schema. Detailed schemas are listed in Appendix B.

3.5 Document Sections

Each document contains 3 basic elements, a root <jDispatchElement> element, which will be named by the transaction type, either a <jDispatchRequest> or a <jDispatchResponse> <DocHeader> element and a <DocContent> element.

3.6 DocHeader

The header of each document contains identifying information that validates the request and the user sending the request. The required information will not change, regardless of the document type being used. The following attributes must exist on each incoming request’s header element

Attribute	Required	Description
DocID	Required	A GUID to make each document uniquely identifiable
DocType	Required	Defining the document type that is being sent
Sender	Required	A unique identifier assigned to the sender.
Date	Required	Time stamp of the document, to the millisecond per the ISO 8601 standard. YYYY-MM-DDThh:mm:ss
apikey	Required	API Key provided to you from AMS
env	Required	“TEST” or “PROD”

3.7 DocType Types

Document	Description
deliveryDispatch	Document to create a delivery
deliveryReceipt	Document sent on delivery confirmation
deliveryResponse	Document sent to confirm deliverReceipt
jdCustomer	Document to add a customer to the web
jdDriver	Document To add a driver to the web.
deliveryDispatchResponse	Response from deliveryDispatch document
jdCustomerResponse	Response from jdCustomer document
jdDriverResponse	Response from jdDriver document

3.8 DocContent

The DocContent is much different than the DocHeader element in that the DocContent element will contain all of the information unique to the requested transaction type. A DocContent element may contain many elements of the same type, sending many invoices in one deliveryDispatch document. For example, this allows many invoices to be dispatched at a single time.

XML document examples can be found in Appendix A, and JSON examples can be found in Appendix B, defining element types and requirements.

4 Transaction Overviews

This section will give a general outline of each of the unique transaction types. For detailed XML examples, please refer to Appendix A, and for JSON examples, please refer to Appendix B.

4.1 jDispatchRequest DocType Overviews

deliveryDispatch: The deliveryDispatch transaction is the initial dispatch of a delivery to the JDISPATCH web application, and subsequently through to the defined mobile application running on a smart device. Additionally, any cancellations, manual receipts and deletions will be processed via this transaction.

The decision of what type of transaction is being passed is determined by the resquest document’s <Status> tag.

A – Add a delivery in to the jDispatch system. Drivers are notified of new deliveries added to their device via a push notification

R – Mark a delivery as Received, this is usually in the case of a delivery being as being picked up or received by the host system

D – Delete a delivery from the jDispatch system. This is usually a scenario where an invoice was inadvertently dispatched, and needs to be ‘pulled back’ to the host system for dispatch at a later time.

C – Cancel a delivery. This will mark a delivery as cancelled within the jDispatch system. Drivers are notified of cancelled deliveries, and confirmations are done against cancelled deliveries, putting them into a ‘Retired’ state when confirmed.

Deliveries are sent to the jDispatch system, one delivery batch per driver, and the response of the delivery will be within the <Status> tag of the response, with a response based on the response status table found in Appendix C, with the detail of any failures being reported in the response’s <Message> tag. A successful load of all deliveries will result in a SUCCESS <Status>, with the <Message> tag returning the unique run ID assigned to the delivery batch.

jdCustomer: Any maintenance to customer information (Add/Change/Delete) in the JDISPATCH web application needs to be done via the jdCustomer function & transaction. Only basic information is passed for the purpose of enabling the functionality of the JDISPATCH web & mobile applications. This transaction can have multiple customers passed, so bulk actions are possible. The possible statuses for this document are:

A – Add a new customer. Records passed with this status are assumed to be new customers, and the data is added to the system. If, for some reason, the customerID that is passed is already in the system, that customerID will be updated with the detailed information found in the document

D – Delete a customer. The customerID associated with this status will be deleted from the jDispatch system

C – Change a customer. The customer record associated with the customerID passed in this document will have its information updated based on the detail passed within the document.

jdDriver: Any maintenance to driver information (Add/Change/Delete) in the JDISPATCH web application needs to be done via the jdDriver function & transaction. Only basic information is passed for the purpose of enabling the functionality of the JDISPATCH web & mobile applications. This transaction can have multiple drivers passed, so bulk actions are possible. The possible statuses for this document are:

A – Add a new driver. Records passed with this status are assumed to be new drivers, and the data is added to the system. If, for some reason, the driverID that is passed is already in the system, that driverID will be updated with the detailed information found in the document

D – Delete a driver. The driverID associated with this status will be deleted from the jDispatch system

C – Change a driver. The driver record associated with the driverID passed in this document will have its information updated based on the detail passed within the document.

4.2 jDispatchResponse DocType Overviews

deliveryReceipt: The deliveryReceipt transaction is a transaction sent from the JDISPATCH web application to a pre-configured URL defined by the third-party system (if required). This document passes back the delivery time, signature and recipient for use within the third-party system. The signature image is a JPEG image, encoded with base64 encoding, passed through as an ASCII string and to be decompressed and converted to an image by the host system.

deliveryResponse: The deliveryResponse transaction is a transaction sent from the third-party system back to the JDISPATCH api server. This document will pass a status message indicating whether the deliveryReceipt document was accepted and properly processed, and whether to try re-sending. In the case of a failure and re-send request, the JDISPATCH api server will begin attempting to re-send the document. Upon 5 failures, the admin email on the sponsor’s account will be notified of the error.

deliveryDispatchResponse: This document will be in the format of the general jDispatchResponse. The basic SUCCESS or FAIL status will be reported by the <Status> tag, a <Code> tag will report a more detailed status with a response based on the response status table found in Appendix C for a deliveryDispatch document. Any detailed failure information is contained in the <Message> tag.

jdCustomerResponse: This document will be in the format of the general jDispatchResponse. The basic SUCCESS or FAIL status will be reported by the <Status> tag, a <Code> tag will report a more detailed status with a response based on the response status table found in Appendix C for a jdCustomer document. Any detailed failure information is contained in the <Message> tag.

jdDriverResponse: This document will be in the format of the general jDispatchResponse. The basic SUCCESS or FAIL status will be reported by the <Status> tag, a <Code> tag will report a more detailed status with a response based on the response status table found in Appendix C for a jdDriver document. Any detailed failure information is contained in the <Message> tag.

4.3 Notable Field Limits

CustomerID – Alpha/Numeric, Limit 15 characters.

DriverID – Alpha/Numeric, Limit 6 Characters.

BranchID = Numeric, Limit 4 digits.

5 Appendix A

5.1 XML Request Transaction Examples

deliveryDispatch

<DocType>deliveryDispatch</DocType>

</DocHeader>

<Items>

</Items>

</OverrideAddress>

</Delivery>

</DocContent>

</jDispatchRequest>

jdCustomer

<DocType>jdCustomer</DocType>

</DocHeader>

</Customer>

</DocContent>

</jDispatchRequest>

jdDriver

<DocType>jdDriver</DocType>

</DocHeader>

</Drivers>

</DocContent>

</jDispatchRequest>

5.2 XML Response Transaction Examples

deliveryReceipt

<DocType>deliveryReceipt</DocType>

</DocHeader>

</Delivery>

</DocContent>

</jDispatchResponse>

jdispatchResponse

</DocHeader>

</DocContent>

</jDispatchResponse>

deliveryResponse

<DocType>deliveryResponse</DocType>

</DocHeader>

</DocContent>

</jDispatchResponse>

6 Appendix B

6.1 JSON Request Examples

deliveryDispatch

{

"jDispatchRequest": {

"DocHeader": {

"DocID": "",

"DocType": "deliveryDispatch",

"SenderID": "",

"apiKey": "",

"env": "",

"Date": ""

"DocContent": {

"DeliveryCount": "",

"Delivery": {

"BranchID": "",

"Status": "",

"OrderDate": "",

"CustomerID": "",

"DriverID": "",

"Invoice": "",

"SubTotal": "",

"Taxes": "",

"Freight": "",

"OtherChg": "",

"DeliveryType": "",

"Total": "",

"Items": {

"LineCode": "",

"PartNumber": "",

"Qty": "",

"Price": "",

"Discount": "",

"Extend": ""

"OverrideAddress": {

"Address": "",

"City": "",

"Province": "",

"PostalCode": ""

"SignatureRequired": ""

}

jdCustomer

{

"jDispatchRequest": {

"DocHeader": {

"DocID": "",

"DocType": "jdCustomer",

"SenderID": "",

"apiKey": "",

"env": "",

"Date": ""

"DocContent": {

"BranchID": "",

"Customer": {

"Status": "",

"CustomerID": "",

"CustomerName": "",

"Address": "",

"City": "",

"Province": "",

"Country": "",

"PhoneNumber": ""

}

jdDriver

{

"jDispatchRequest": {

"DocHeader": {

"DocID": "",

"DocType": "jdDriver",

"SenderID": "",

"apiKey": "",

"env": "",

"Date": ""

"DocContent": {

"Driver": {

"Status": "",

"BranchID": "",

"DriverID": "",

"DriverName": ""

}

6.2 XML Response Transaction Examples

deliveryReceipt

{

"jDispatchResponse": {

"DocHeader": {

"DocID": "",

"DocType": "deliveryReceipt",

"SenderID": "",

"apiKey": "",

"env": "",

"Date": ""

"DocContent": {

"CustomerID": "",

"DriverID": "",

"DeliveryDate": "",

"DeliveryTime": "",

"Recipient": "",

"SignatureCode": "",

"Delivery": {

"Invoice": ""

}

jdispatchResponse

{

"jDispatchResponse": {

"DocHeader": {

"DocID": "",

"DocType": "",

"SenderID": "",

"apiKey": "",

"env": "",

"Date": ""

"DocContent": {

"Status": "",

"Code": "",

"Message": ""

}

deliveryReceipt

{

"jDispatchResponse": {

"DocHeader": {

"DocID": "",

"DocType": "deliveryResponse",

"SenderID": "",

"apiKey": "",

"env": "",

"Date": ""

"DocContent": {

"Status": "",

"Code": "",

"Message": ""

}

7 Appendix C

7.1 Status Codes

The status codes below are used to report the status of requests sent to this API.

2XX - Success of some kind

4XX - Error occurred in client’s part

5XX - Error occurred in server’s part

Status Code	Description
200	OK
400	Bad request
401	Authentication failure
403	Improper Data Format
404	Invalid Document Type Passed
405	Invalid Document Structure
412	Condition Failed
413	Request Entity Too Large
460	dispatchReceipt failed – Resend requested
465	dispatchReceipt failed – Resend not required
500	Internal Server Error
501	Not Implemented
503	Service Unavailable