Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Removed the "X" from "X Web" we don't officially have any products or line items called "X Web", also fixed a small grammar issue and updated the description to say the "CXT Software suite" rather than "X Dispatch"

...

Our web service allows for consistent integrations and services, making it easier for third parties to integrate with X Dispatchthe CXT Software suite. It is accessible by both REST and SOAP and accepts both XML and JSON requests.

...

Panel
titleImportant Items to Note
  • Authentication is needed for most endpoints. You will need to send an authorization token or do a basic authentication with the call.
  • Dates entered should be in milliseconds in UTC for JSON requests (e.g. 1559651878000) and ISO-8601 standard for XML requests (e.g. 2019-06-04T07:36:53).
  • Dates returned are formatted according to X Dispatch global options settings and localized to where the order was picked up/delivered with the timezone noted.
  • When entering the workOrderId parameter it must be in the following format:

    • route stop: r<stopID>
    • on demand pickup: p<orderID>
    • on demand delivery: d<orderID>

How will versioning be handled?

CXT Software will support the latest version, plus one previous previously published version. Response and Request objects, in addition to URLs, may have properties added with new releases. Business logic within the endpoints may change, and/or permission hardening may be applicable to existing endpoints with new releases 

Requirements

  • X Dispatch 21.0 or newer.
  • TLS 1.2
    • When calling the web services for CXT hosted Cloud customers (designated by a domain in the format <CXTID>0.cxtsoftware.net), the calling system must connect with TLS 1.2
    • TLS 1.2 is not supported on Windows 2008 R2 or below. The calling system can run Windows 7, 8.1 or 2012 or newer, all of which support TLS 1.2

Throttling API Calls

By default, API calls are throttled based on individual users and collectively to all users per the following default intervals:

...

If you need to adjust the default values please contact Technical Support.

Getting Started

Our web service is documented with Swagger UI and you can find a list of field definitions to help explain certain API fields. All customers can view this by going to https://<domain>/CxtWebService/CXTWCF.svc/api-docs/. For cloud customers, <domain> would be <CXTID>0.cxtsoftware.net, where <CXTID> is the 4 digit CXT Software account id. For example, if the CXT Software account id is 987, then the endpoint documentation is https://09870.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/

To view the property name, its type, and a brief description of its purpose, click on the 'Model' link for either the request or response object. 

How to Use Swagger

  1. Navigate to URL: https://<domain>/CxtWebService/CXTWCF.svc/api-docs
  2. Authenticate by either getting an authentication token or using basic authentication. See Authenticate. Depending on the user type allowed to access the endpoint, you may need different tokens.  

  3. If getting an authorization token, place token in the Authorization Token box at the top. 

    Div


  4. Make endpoint requests in JSON or XML

Address Validation

  • If the "Enforce Address Validation" global option is checked inside X Dispatch, an order/stop will be successfully placed only if the address is validated; the order will fail if the address cannot be validated. If "Enforce Address Validation" is unchecked, the order placement will succeed regardless of validation.
  • Only the geocode (lat/lon) is updated when the addresses can be validated. 

Attachments

Requirements for uploading a file (attachment creation/update):

  • When creating a new Attachment, do not send in an id.
  • When updating an Attachment, the id must be provided.

Attachment Permissions > Maintenance > Permissions.

TypeList/ViewAddEditDelete
OrderMust have permissions enabled for X Dispatch Functions > Orders

If the order is Invoiced

  • Must have X Dispatch Functions > Orders > Edit Invoiced Orders > Edit Invoiced Attachments permission enabled

If an order is Settled

  • Must have X Dispatch Functions > Orders > Edit Settled Orders > Edit Settled Attachments permission enabled

For uninvoiced and unsettled orders

  • Must have X Dispatch Functions > Orders > Edit Orders permission enabled
Same as Add permissionSame as Add permission
CustomerMust have permissions enabled for X Dispatch Functions > CustomersMust have X Dispatch Functions > Customers > Edit Customers permission enabledSame as Add permissionMust have X Dispatch Functions > Customers > Delete Customers permission enabled
Human Resource

Must have permission enabled for Maintenance Functions > Human Resources > View Contractor

Maintenance Functions > Human Resources > View Employees

Maintenance Functions > Human Resources > View HR Advanced Information

Must have Maintenance Functions' -> Human Resources > Edit Human Resources permissions enabled
Same as Add permissionSame as Add permission
Customer ContractMust have X Route Functions > ContractsMust have Contracts > Add Contracts permission enabled
Must have Contracts > Edit Contracts permission enabled
Same as Edit permission

Authenticate

Most endpoints require authentication from the following user types:

...

To authenticate, select sending an authorization token or doing a basic authentication with the call.

Image Modified Token Based Authentication 

Token based authentication uses one of the following endpoints to get the authorization token for the user:

  • Driver endpoint: /v2/Authentication/Drivers 

    Div

    Valid duration of an authentication token: 30 days  

    Note
    titleX Dispatch User Note

    "Allow web access" must be enabled on the driver record in the X Dispatch application. See Drivers - New / Edit Driver(Desktop Operations App).



  • Internet User endpoint: /v2/Authentication/InetUser 

    Div

    Valid duration of an authentication token: 20 minutes

    Note
    titleX Dispatch User Note

    "Allow Web Service API" must be enabled on the internet user record in the X Dispatch application. See Internet Users - New / Edit Internet User(Desktop Operations App).



  • Human Resources endpoint: /v2/Authentication/Worker  

    Div

    Valid duration of an authentication token: 30 days

    Note

    See Human Resources - New / Edit Human Resource



  • X Dispatch User endpoint: /v2/Authentication/XdUser 

    Div

    Valid duration of an authentication token: 60 minutes 


Token expiration is automatically extended with each call. 

Authenticate Driver Example

Paste code macro
titleCurl
curl -X POST --header "Content-Type: application/json" --header "Accept: application/json" -d "{
  \"driverId\": 123,
  \"password\": \"password\",
}" "https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/v2/Authentication/Drivers"

Including Tokens in Subsequent Requests

After generating a token, include it in subsequent requests as a value for the Authorization header, in the form 'Token 12345'.

Paste code macro
titleExample
curl -X GET --header "Accept: application/json" --header "Authorization: Token b1661ab49e5d42139b99a4a0ee741f0a" "https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/v2/Orders/9876"

Basic Authentication

Basic authentication credentials must be sent with every request, base64 encoded and the username must be prefixed with 1 or 4 values to distinguish user type:

...

An example of an internet user with the username "cxtsupport" is "INET-cxtsupport".

Basic Auth Example

Paste code macro
languagecs
titleC# Code to construct a WebRequest using Basic Auth
System.Net.ServicePointManager.SecurityProtocol = System.Net.SecurityProtocolType.Tls12 | (SecurityProtocolType)3072; //TLS1.2 for for Windows 2012+, and 3072 is for Windows 2008 R2; Both can be left in place here without problem

string url = "url"
var request = System.Net.WebRequest.Create(url);
request.Method = HttpMethod.Get.ToString();

string username = "username";
string password = "password";
string encoded = System.Convert.ToBase64String(System.Text.Encoding.ASCII.GetBytes(username + ":" + password));
request.Headers.Add("Authorization", "Basic " + encoded);
((System.Net.HttpWebRequest)request).Accept = "application/json";
return request;

Examples

The following are examples to help you get started and is not an inclusive list. Use the endpoint URL examples to find documentation in the Swagger UI for details and testing.

Creating a New Order without known order type(s)

Creating a new order creates a new on demand order in X Dispatch and requires an internet user authorization token. Before creating an order you will need a list of order types if a static order type is not provided. Order types in X Dispatch define the timing and level of service for on demand orders. 

Image ModifiedHow to Retrieve An Order Type

To get a list of available order types, use the  /v2/Orders/RatesWithTimeWindows endpoint.

...

Implementation Notes: Allowed requestors: [INet user, XDispatch user] The following permissions need to be enabled in X Dispatch on the internet user record in the Options tab, Show Rates to see the initialBaseRate and Show Deliver By Time to see the deliveryTime. To see the initialBaseRate the Global Options in X Dispatch also needs to have Total Charges enabled in the Internet Options tab. 

...

Once you have retrieved a list of order types you can use the /v2/Orders endpoint to create new on demand order. See How to Create an Order.

Creating a New Order with known order type(s)

Creating a new order creates a new on demand order in X Dispatch and requires an internet user authorization token. Use this endpoint if a static order type is provided. Order types in X Dispatch define the timing and level of service for on demand orders. 

Image ModifiedHow to Create an Order

You can use the /v2/Orders endpoint to create new on demand order in X Dispatch.

...

ParameterDescriptionParameter TypeData Type
orderRequestThe on demand order to be created.bodyJSON/XML

Creating a New Route Stop

Creating a new route stop creates a new route stop in X Dispatch and requires an X Dispatch user authentication token.

Image ModifiedHow to Create a Route Stop

You can use the /v2/RouteStops endpoint to create new route stops in X Dispatch.

...

ParameterDescriptionParameter TypeData Type
requestThe data for the new route stop to be createdbodyJSON/XML
creditLimitBypasBoolean indicating whether or not to create the route stop if the customer credit limit is exceededqueryboolean

Image Modified Order Status

Internet and X Dispatch users can get order status data. Including, but not limited to, confirmation, pickup, delivery, and POD details.

For Internet Users

Endpoint URLhttps://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_GetOnDemandOrderV2

...

ParameterDescriptionParameter TypeData Type
orderIdThe ID of the order to retrieve.pathstring
includeItemizedChargesBoolean indicating whether or not to include itemized charges for order.pathstring

For Dispatch Users

Endpoint URLhttps://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Orders/CxtSoftware_MiddleTier_WebService_CXTWCF_GetOnDemandOrderWithItemizedChargesV2

...

ParameterDescriptionParameter TypeData Type
onDemandOrderIdThe ID of the on demand order to be retrieved.pathstring

Image Modified Track an Order

Get order tracking information based on matching tracking numbers, reference1 values, and unique identifiers of orders and route stops with paging. No authorization token is required, however, the information returned will be limited. For more detailed tracking information to be returned, you must have an internet user authorization token.

...

ParameterDescriptionParameter TypeData Type
searchCriteriaString containing comma-separated search criteria (i.e. Tracking Numbers, Locations, Addresses, Cities, States, Postal codes) - ignored for DateOnly searchquerystring
trackingTypeSpecify what fields the trackingNumberList represents (e.g. Tracking(Number, Barcode or Reference), Location, Address, City, State, Postal, or DateOnly)querystring
includePartialMatchSpecify 'true' if partial matches should be included in the search results (default is 'false')queryboolean
beginDateOptionally specify a begin date to limit the search resultsquerystring
endDateOptionally specify an end date to limit the search resultsquerystring
numRecentOrdersSet number of recent orders to view for the current user (Note: if this is used, no other search criteria will apply)queryinteger
pageNumThe offset for the records to return (Default value is 0)queryinteger
pageSizeThe number of records to return (Default and Maximum value is 1000)queryinteger

Image Modified Add Signature to Work Order

Upload a signature image for a work order. 

...

ParameterDescriptionParameter TypeData Type
workOrderSignatureThe signature to be persisted.bodyJSON/XML

Image Modified Update Status/Change Timestamp

Mark a work order as picked up, completed, or add a POD.

...

ParameterDescriptionParameter TypeData Type
onDemandOrderId

The ID of the on demand order to be updated

pathstring

Troubleshooting

If you are experiencing connection issues and need CXT Software to help troubleshoot, add the following to the Web.config file, within the <configuration> tag and adjust the log name/location in the 'initializeData' attribute of the snippet below. Make the problematic call. Then include the resulting log as part of the information provided to CXT for troubleshooting.

...