This document outlines the purpose, technology, use cases, methods, objects and examples for using the Dispatch API.
This document focuses on the SOAP interface to this API.
The Dispatch API provides programmatic access to the dispatch database and allows for progressing orders through the dispatch process.
The Dispatch API exposes two primary native interfaces via .NET and SOAP.
Full documentation for this interface is available in the API Reference.
This section documents the SOAP interface to the API.
The SOAP API endpoint for any site is located at https://[siteurl]/global/api/Dispatch.asmx
This endpoint is enabled for access via SOAP as well as HTTP GET and POST. The Service Description is also available directly via this endpoint.
Note: For systems with satellite sites, the API will be available only under the primary site URL.
The Dispatch API via SOAP uses the Permissions System to allow and deny access to users. Use of the API requires a user to be granted the various actions (under iSAMS / API / Dispatch) to be able to authenticate and perform the various actions available under this API.
Error handling is primarily left to the caller. Any methods that return an ApiResponse object will provide additional details that can be used to assist when debugging problems.
Where a "Call Identifier" is returned in the Message field of the ApiResponse, then a full exception trace will be available from http://[siteurl]/logs/api/{Call Identifier}.txt
Available methods are listed below.
Available objects are listed below.
Dispatch API usage examples are available. These examples demonstrate the use of the API via a SOAP interface and are available in C# and Java.
Allocate one unit to the oldest OrderItem with specified barcode. If there's no item with the specified barcode assigned, a historic barcode search will be performed in case the barcode on the item has changed.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| barcode | String(20) | Unique barcode or APN of the OrderItem to allocate. |
Returns an ApiResponse indicating the outcome of the call.
Allocate specified quantity to specified OrderItem.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderItemID | Integer | Unique identifier of the OrderItem to allocate. |
| quantity | Integer | The unit to allocate to the OrderItem. |
Returns an ApiResponse indicating the outcome of the call.
Assign the specified Order to the specified DispatchPoint
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderID | Integer | Unique identifier of the Order to assign. |
Returns an ApiResponse indicating the outcome of the call.
See Authenticate.
Perform collection of a click and collect Order progressing the order to "Complete" status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| orderID | Integer | Unique identifier of the Order that is being collected. |
| orderCollectionData | OrderCollectionData | OrderCollectionData to upload against the Order. |
Returns an ApiResponse indicating the outcome of the call.
Confirms all allocations made to specified Order and progresses Order to "Pending Payment Processing" status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderID | Integer | Unique identifier of the Order to confirm. Use zero (0) to confirm all applicable Orders in specified DispatchPoint. |
Returns an ApiResponse indicating the outcome of the call.
List all available DispatchPoints.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
Returns a DispatchPointApiResponse indicating the outcome of the call. If successful, it contains the list of DispatchPoints.
List all OrderItems with allocations (partially or fully) for all Orders at "In Progress" status in the specified DispatchPoint.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. Leave blank to list for all applicable DispatchPoints. |
Returns an IntegerArrayApiResponse indicating the outcome of the call. If successful, it contains the list of OrderItem IDs.
List all OrderItems with pending allocations for all Orders at "In Progress" status in the specified DispatchPoint.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. Leave blank to list for all applicable DispatchPoints. |
Returns an IntegerArrayApiResponse indicating the outcome of the call. If successful, it contains the list of OrderItem IDs.
List all Orders currently in progress in the specified DispatchPoint.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. Leave blank to list for all Orders without a DispatchPoint assignment. |
Returns an IntegerArrayApiResponse indicating the outcome of the call. If successful, it contains the list of Order IDs.
List all Orders with all OrderItems fully allocated (ready for confirmation and payment capture) in the specified DispatchPoint.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. Leave blank to list for all applicable DispatchPoints. |
Returns an IntegerArrayApiResponse indicating the outcome of the call. If successful, it contains the list of Order IDs.
List all Orders with successful payment capture and are ready for invoice printing in the specified DispatchPoint.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. Leave blank to list for all applicable DispatchPoints. |
Returns an IntegerArrayApiResponse indicating the outcome of the call. If successful, it contains the list of Order IDs.
List all Orders with invoice printed and are ready for shipping in the specified DispatchPoint.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. Leave blank to list for all applicable DispatchPoints. |
Returns an IntegerArrayApiResponse indicating the outcome of the call. If successful, it contains the list of Order IDs.
Prints the invoice for the specified Order and progresses Order to "Ready To Ship" status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderID | Integer | Unique identifier of the Order to confirm. Use zero (0) to print all applicable Orders in specified DispatchPoint. |
Returns an ApiResponse indicating the outcome of the call.
Progress an Order to the "ReceivedInStore" status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| orderID | Integer | Unique identifier of the Order to progress. |
Returns an NVPApiResponse indicating the outcome of the call.
Retrieve a DispatchPoint for the specified dispatch point name.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
Returns a DispatchPointApiResponse indicating the outcome of the call. If successful, it contains the a single item of DispatchPoint.
Reverse allocate the specified quantity from the specified OrderItem.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderItemID | Integer | Unique identifier of the OrderItem to reverse allocate. |
| quantity | Integer | The unit to reverse allocate from the OrderItem. |
Returns an ApiResponse indicating the outcome of the call.
Ships and uploads the specified shipping reference against the specified Order, and progresses Order to the "Completed" status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderID | Integer | Unique identifier of the Order to ship. |
| shippingReference | String(50) | Courier ticket reference to upload against the Order. |
| sendDispatchEmail | Boolean | Indicate if a dispatch email should be triggered to notify customer that the Order is shipped. |
Returns an ApiResponse indicating the outcome of the call.
Ships and uploads the specified shipping references against the specified Order, and progresses Order to the "Completed" status.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderID | Integer | Unique identifier of the Order to ship. |
| shippingReference | String(50)[] | Courier ticket references to upload against the Order. |
| sendDispatchEmail | Boolean | Indicate if a dispatch email should be triggered to notify customer that the Order is shipped. |
Returns an ApiResponse indicating the outcome of the call.
Ships and uploads the specified tracking details against the specified Order, and progresses Order to the "Completed" status for delivery orders or the "ShippedToStore" status for click and collect orders.
| Name | Type | Description |
|---|---|---|
| authenticationToken | String(50) | Authentication token to use for this call. |
| dispatchPointName | String(50) | Unique identifying name of the DispatchPoint to execute this call. |
| orderID | Integer | Unique identifier of the Order to ship. |
| trackingDetails | TrackingDetail[] | Array of TrackingDetail to upload against the Order. |
| sendDispatchEmail | Boolean | Indicate if a dispatch email should be triggered to notify customer that the Order is shipped. |
Returns an ApiResponse indicating the outcome of the call.
See ApiResponse.
Represents a dispatch point.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Code | String(10) | The dispatch point unique identifier. | |
| Name | String(50) | The dispatch point name. | |
| Active | Boolean | Indicates if the dispatch point is still in use. |
Contains basic information about the result of a method call, along with an array of DispatchPoint objects.
| Field Name | Type | Description | Notes |
|---|---|---|---|
| Success | Boolean | Indicates the success or failure of an API method call. | A failure (false) response should contain a failure Code and Message in the respective fields. |
| Code | Integer | A response code for the method call. | |
| Message | String | Message or output from the method call. | |
| Data | DispatchPoint[] | Array of DispatchPoint objects returned from the method call. |
Contains tracking information about the order.
| Field Name | Type | Description |
|---|---|---|
| TrackingReference | String(50) | Courier ticket reference to upload against the trackingDetail Object. |
| CarrierName | String(50) | Carrier Name to upload against the trackingDetail Object. |
| TrackingURL | String(200) | Tracking URL to upload against the trackingDetail Object. |
Contains details about the collection of a click and collect order.
| Field Name | Type | Description |
|---|---|---|
| OrderPersonCollected | Boolean | Flag indicating whether the order person collected the order (true) or another person collected the order on their behalf (false). |
| OrderPersonComment | String(1024) | Any comments or notes from the order person. |
| StaffPin | String(32) | PIN number of the staff member performing the collection. |
| CollectionPersonFirstName | String(50) | The first name of the person who collected the order if this was not the order person. |
| CollectionPersonLastName | String(50) | The last name of the person who collected the order if this was not the order person. |
| CollectionPersonPhone | String(50) | The phone number of the person who collected the order if this was not the order person. |
| CollectionPersonComment | String(1024) | Any comments or notes from the collection person. |
See NVPApiResponse.
The Dispatch API returns standard API response codes.