Home
To access and manage your Despatch Bay (www.despatchbay.com) account using the Despatch Bay API, you build a client application that connects to one or more of the provided web services. While each service can be used independently, most real-world scenarios require that a client application uses multiple services.
The core messaging technology for the Despatch Bay API is SOAP 1.1, which is an XML and HTTP-based protocol supported by most programming languages and frameworks.
Note: The API uses the Document/literal style. Attempting to consume the API using RPC style messages will result in failure
The web services are secured by means of HTTP Basic Authentication.
Within the Despatch Bay API settings control panel (despatchbay.com/account/api-integration) it is possible to generate one or more sets of API credentials. A single set of API credentials consists of two tokens, an apiuser and an apikey. These tokens must be used as the values of login and password respectively when authenticating against the API.
Example using the native PHP SoapClient
$apiuser = 'YOUR_API_USER';
$apikey = 'YOUR_API_KEY';
$soapUrl = "https://api.despatchbay.com/soap/v15/shipping?wsdl";
$soapOptions = array ('login' => $apiuser,'password' => $apikey);
$client = new SoapClient($soapUrl, $soapOptions);For more details on how to use HTTP Basic Authentication with SOAP you should consult the documentation for your chosen SOAP client.
To ensure quality of service for all customers we have implemented a system of rate limiting within each of the services. Each service has a rate limiting window and a corresponding maximum number of requests.
None of the services currently support returning rate limiting headers so your application will need to monitor it's own usage in order to prevent running into rate limits. When a rate limit is exceeded, the service will return HTTP/1.1 429 Too Many Requests
| Service | Window | Max Requests |
|---|---|---|
| Account | 1 hour | 300 |
| Addressing | 1 min | 60 |
| Shipping | 1 min | 300 |
| Tracking | 1 min | 10 |
Note: If you would like to discuss increased rate limits with us, please get in touch. We will assess requests for increased limits on a case by case basis.
Please consider setting a custom user agent string which will identify your application when making requests to the Despatch Bay API. This especially applies if you are building a 3rd party integration which will be used by others. Setting a unique user agent string which identifies your application will help us to provide better technical support for you and your users should the need arise.
Information to consider including in your user agent string
- The name of your application
- The version number of your application
- Information about the operating system and runtime environment
- A technical support email address
Examples of custom user agents strings might be
Acme Magento Extension 1.0.2; PHP-SOAP/5.5.9-1ubuntu4.25
Bob's Bargain Web Shop; development@bobsbargainwebshop.co.uk
WarehouseWizard 6.2; Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client Protocol 4.0.30319.42000)
Despatch Bay uses the ISO 8601 combined format for dateTime stamps being submitted to and returned from the API. Please be sure to submit all dateTime values as yyyy-mm-dd hh:mm:ss (24 hour notation). Example - 2016-11-29 23:59:59
The time zone represented in all API responses is Europe/London. We ask that you make any time zone conversions before submitting DateTime data to the Despatch Bay API.
The Documents API works in conjunction with the SOAP to provide labels in PDF or Base64 format for your application to consume.
For more information please see Documents API