...

Requirements

• X Dispatch 21.0 or newer.
• TLS 1.2
  • When calling the web services for CXT hosted 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

...

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

_{Back to top.}

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. 

...

_{Back to top.}

Authenticate

Most endpoints require authentication from the following user types:

...

You can see which user type(s) are required for an endpoint under "Implementation Notes". For example, "Allowed requestors: [Inet user]" requires an authenticated internet user and  "Allowed requestors: [Mobile Users]" requires an authenticated driver user.  

Image Modified

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

 Token Based Authentication 

...

• Driver endpoint: /v1/Authentication/Drivers 

  Div
  Valid duration of an authentication token: 30 days   Note title X Dispatch User Note "Allow web access" must be enabled on the driver record in the X Dispatch application. See Drivers - New / Edit Driver.

  
  

• Internet User endpoint: /v1/Authentication/InetUser 

  Div
  Valid duration of an authentication token: 20 minutes Note title X 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.

  
  

• Human Resources endpoint: /v1/Authentication/Worker  

  Div
  Valid duration of an authentication token: 30 days Note See Human Resources - New / Edit Human Resource.

  
  

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

  Div
  Valid duration of an authentication token: 60 minutes

  
  

...

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

_{Back to top.}

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:

...

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.

...

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

Creating a New Order with known order type(s)

...

How to Create a Route Stop

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

Endpoint URL: https://XXXX0.cxtsoftware.net/CxtWebService/CXTWCF.svc/api-docs/index.html?url=/CxtWebService/CXTWCF.svc/v2/swagger.json#!/Route_Stops/CxtSoftware_MiddleTier_WebService_CXTWCF_PostRouteStopV2

Section: Route Stops

Endpoint: /v2/RouteStops

Implementation Notes: Allowed requestors: [XD User]

...

_{Back to top.}

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.

<system.diagnostics>
    <trace autoflush="true" />
    <sources>
      <source name="System.Net" maxdatasize="1024">
        <listeners>
          <add name="MyTraceFile"/>
          <add name="MyConsole"/>
          <add name="MyText"/>
        </listeners>
      </source>
    </sources>
    <sharedListeners>
      <add
        name="MyTraceFile"
        type="System.Diagnostics.TextWriterTraceListener"
        initializeData="System.Net.trace.log" />
      <add name="MyConsole" type="System.Diagnostics.ConsoleTraceListener" />
      <add name="MyText" type="System.Diagnostics.TextWriterTraceListener" initializeData="C:\Temp\RequestTrace.log"></add>
    </sharedListeners>

    <switches>
      <add name="System.Net" value="Verbose" />
    </switches>
  </system.diagnostics>

...