DropBoy

The Dropboy Developer Hub

Welcome to the Dropboy developer hub. Here you'll find guides and documentation to help you get started with the Dropboy API. We are also ready to provide you with support if you get stuck. Go right ahead!

Get Started
Suggest Edits

Welcome

to the Dropboy Public API Reference Guide

 

Using the Reference Guide

The reference guide is structured into the various sections of API categories containing their relevant endpoints.

At each endpoint it is possible to see example code and run requests to see the results.

No examples in your coding language?

Let us know and we might be able to help you out.

Maintaining and Improving our Reference Guide

We are constantly evolving and adding more API integrations, allowing you to integrate the Dropboy platform into your own systems. We would love to get your feedback in one of the following ways:

  • Suggested edits to our documentation can be made right here in the documentation. (Top right corner of a section).
  • Feature requests (API or otherwise) should be sent to support@dropboy.com. (The better you describe your needs and why it is needed, the more likely it is that we are able to help you).
  • Any comments on what we generally could do better (or are doing well) are also welcome at support@dropboy.com - just remember to provide the proper context (API documentation).

Below you will find all the reference material regarding usage of the Dropboy API.

Suggest Edits

Getting started

What is Dropboy and what does the API do?

 

Dropboy is a digital infrastructure for the transport industry. By using Dropboy, companies who either provide or consume transport services can connect and collaborate in a more efficient way.

Aside from connecting transportation partners, Dropboy also supplies a simple TMS solution that is suitable for smaller transportation companies.

The API enables integration with Dropboy and makes it possible to upload orders and interact with existing orders within Dropboy.

The API is a RESTful API based on HTTPS requests and JSON responses. If you have a Dropboy account, you can find your API key in Upload orders within your Dropboy account.

Suggest Edits

Using the API

All the basics

 

Endpoints

The API is accessed by making HTTPS requests a specific endpoint URL, in which GET, POST, PUT, PATCH, and DELETE methods dictate how your interact with the information available. Every endpoint is accessed only via the SSL-enabled HTTPS (port 443) protocol.

An example of an endpoint:
https://api.wuxus.com/public/orders

Requests

Requests must be sent over HTTPS with any payload formatted in JSON. All requests must include the APIkey header to authenticate.

Authentication

In order to use the API you need an API key for authentication. This is sent along in the headers as APIkey. If you have an account, you can find your API key in Upload orders within your Dropboy account.

Find the API key here

Find the API key here

Missing API key

If you try to send a request to our API without an API key, you will receive this error:

{
    "success": false,
    "errors": [
        "Missing API key"
    ],
    "error": "Missing API key",
    "result": null
}

Invalid API key

If you try to send a request to our API with an invalid API key, you will receive this error:

{
    "success": false,
    "errors": [
        "Invalid API key"
    ],
    "error": "Invalid API key",
    "result": null
}

Content-types & mimetypes

Make sure to use the correct content types and mimetypes when making a request. The correct content types and mimetypes can be found in each endpoint reference.

Pagination

Depending on your request, the results returned may be limited. You can page through the returned results with the following query parameters.

Key
Description

take

Defines how many results to take. If the number is 200, it will respond with max 200 results. Usually this number is constant

skip

Defines how many results to skip. Usually this number changes. To get page one, start with 0, and then add the value of take on the last skip, to get the next page.

If take is 50, skip will act this way:
Page 1: 0
Page 2: 50
Page 3: 100
Page 4: 150

Rate Limiting

Currently there is no rate limiting, however, you are requested to only poll our API with reasonable frequency. Note that Rate limiting will be implemented within the foreseeable future.

Unsure what reasonable is?

Please contact us, and tell us what you want to do. Then we can find out if it's reasonable, or find a solution for your use case.

Responses

Each response from the API will be a JSON object. The response object will contain following:

Key
Description

success

A boolean that is true if the request was a success

errors

An array containing all the error messages regarding the request. Is empty if there was no errors

result

Is an object or an array depending the result, but will contain the result of the request

info

An object that contains information about the request, example the query parameters.

Information about the result

All date returning from the API, will be in UTC ISO-8601 format containing milliseconds, forexample:
2017-12-24T16:31:25.860Z

Example of a success response

{
  "success": true,
  "errors": null,
  "result": {
    "batchFileId": "58a014865b09850011050000"
  }
}

Example of an error response

{
    "success": false,
    "errors": [
        "File upload failed"
    ],
    "error": "File upload failed",
    "result": null
}

HTTP Content-Type

The response format can be determined from the HTTP Content-Type header. Most API responses are JSON (Content-Type: application/json).

Content-Type
Description

application/json

Response is a JSON object

text/plain

Response is a textual item

application/x-yaml

Response is a YAML object

application/octet-stream

Response is raw data (reserved for later use)

HTTP response codes

The status of a response can be determined from the HTTP status code.

Code
Status
Description

200

OK

Request successful

304

Not modified

400

Bad Request

Request was invalid

401

Unauthorized

User does not have permission

403

Forbidden

Request not authenticated

429

Too many requests

Client is rate limited

405

Method Not Allowed

Incorrect HTTP method provided

415

Unsupported Media Type

Response is not valid JSON

Identifiers

The API provides access to the data stored in documents. Each document is uniquely identified with an Object ID that will be saved in the data in various ways. You can almost always use this ID to interact with a given data document (fx an order).

How to get an Order ID

Nearly every resource in the API may be uniquely identified by a 32-byte string of hex characters ([a-f0-9]). Identifier values are usually captured during resource creation (POST requests) or when fetching entire collections (GET requests) of resources. Typically they appear as an id field in the JSON resource.

{
  "result": {
    "id":"2d4d028de3015345da9420df5514dad0",
    "type":"example"
  }
}

You can always find the IDs for API resources by making a GET request to its corresponding collection endpoint. For example, to list all Order objects, a GET request may be sent to https://api.wuxus.com/public/orders. All objects listed in the result array will contain an id field; this is also known as an orderId.

The SSL certificate for Wuxus domains are changing automatically about every 6 months

Suggest Edits

Introduction to Orders

The basics of the Orders endpoints

 

The Orders API is used for sending and retrieving order related data.

With this API you can:

  1. Retrieve one or more orders, with full order history.
  2. Batch-upload orders to the Wuxus platform.
  3. Get upload status of an order batch.

For simple Track and Trace requests, please use the "Track and Trace" API instead, to lower the amount of redundant data sent.

Suggest Edits

Get orders

 
gethttps://api.wuxus.com/public/orders
?filter={"search":"not found"}&take=200&skip=0
?filter={"search":"found"}&take=200&skip=0
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "errors": null,
    "result": [],
    "info": {
        "skip": 0,
        "take": 200,
        "count": false,
        "export": false,
        "filter": {
            "search": "not found",
            "owner": "creator"
        }
    }
}
{
    "success": true,
    "errors": null,
    "result": [
        {
            "_id": "5a293ff736896b6c21db600b",
            "orderNumber": "TEST-ORDER-NUMBER-1",
            "requisition": "TEST_REQUISITION",
            "orderType": "adhoc",
            "paidBy": "Wuxus A/S",
            "origin": {
                "companyName": "Example Sender A/S",
                "attention": "John Doe",
                "address": "Klausdalsbrovej 601",
                "extraInfo": "Gate 5",
                "zipCode": "2750",
                "city": "Ballerup",
                "countryCode": "DK",
                "email": "john.doe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 123456789
                },
                "timeWindow": {
                    "start": "2017-08-11T10:00:00.000Z",
                    "end": "2017-08-11T12:00:00.000Z",
                    "timeType": "between",
                    "lock": true
                },
                "comments": "Just walk in and to the second floor. We'll be there",
                "timeZone": "Europe/Copenhagen",
                "geoWarn": false,
                "coordinates": {
                    "lat": 55.738892,
                    "lng": 12.3999657
                }
            },
            "destination": {
                "companyName": "Example Production A/S",
                "attention": "Mike",
                "address": "Gammel Lyngvej 2",
                "extraInfo": "Delivery Entrance",
                "zipCode": "4600",
                "city": "Køge",
                "countryCode": "DK",
                "email": "jane.doe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 234567894
                },
                "timeWindow": {
                    "start": "2017-08-11T10:00:00.000Z",
                    "end": "2017-08-11T12:00:00.000Z",
                    "timeType": "between",
                    "lock": true
                },
                "comments": "We're in the middle of the building",
                "timeZone": "Europe/Copenhagen",
                "geoWarn": false,
                "coordinates": {
                    "lat": 55.4826613,
                    "lng": 12.1846249
                }
            },
            "sender": {
                "companyName": "Example Sender A/S",
                "attention": "John Roe",
                "address": "Klausdalsbrovej 615",
                "extraInfo": "The Camp",
                "zipCode": "4600",
                "city": "Køge",
                "countryCode": "DK",
                "email": "john.roe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 345678901
                },
                "comments": "Contact John if there are any problems",
                "timeZone": "utc"
            },
            "receiver": {
                "companyName": "Example Production A/S",
                "attention": "Jane Roe",
                "address": "Galoche Alle 15",
                "extraInfo": "Den hvide by",
                "zipCode": "4600",
                "city": "Køge",
                "countryCode": "DK",
                "email": "jane.roe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 456789012
                },
                "comments": "If door closed, just put it in front of the door",
                "timeZone": "utc"
            },
            "cargo": [
                {
                    "cargoReference": "CARGO-BIG",
                    "cargoNr": "10000#12345",
                    "description": "A little big box",
                    "type": "box",
                    "amount": 1,
                    "weight": 10,
                    "volume": 0.001,
                    "dimensions": {
                        "height": 10,
                        "width": 10,
                        "length": 10
                    },
                    "barcode": "BARCODE#SCAN#1",
                    "services": [
                        {
                            "serviceId": "588ef7efccf9b6fd26e38941",
                            "companyId": "5a293ff736896b6c21db6007"
                        },
                        {
                            "serviceId": "5912f89202bdd2626ba7ebf9",
                            "companyId": "5a293ff736896b6c21db6008"
                        }
                    ],
                    "cargoId": "5a293ff736896b6c21db6006"
                },
                {
                    "cargoReference": "CARGO-SMALL",
                    "cargoNr": "20000#12345",
                    "description": "A little small box",
                    "type": "box",
                    "amount": 2,
                    "barcode": "BARCODE#SCAN#11",
                    "services": [
                        {
                            "serviceId": "5912f89202bdd2626ba7ebf9",
                            "companyId": "5a293ff736896b6c21db600a"
                        }
                    ],
                    "volume": 0,
                    "cargoId": "5a293ff736896b6c21db6009"
                }
            ],
            "status": "todo",
            "haulier": {
                "companyId": "58c134d70f72205b78f70c52",
                "name": "Hauler Name"
            },
            "history": [
                {
                    "historyId": "5a293ff736896b6c21db6005",
                    "created": "2017-12-07T13:19:51.876Z",
                    "action": "batchUpload",
                    "status": "validated",
                    "reporter": {
                        "reportedAt": "2017-12-07T13:19:51.876Z",
                        "companyId": "58c134d70f72205b78f70c52"
                    }
                },
                {
                    "historyId": "5a29400036896b6c21db603d",
                    "created": "2017-12-07T13:20:00.277Z",
                    "action": "traySorted",
                    "status": "todo",
                    "subStatusData": {
                        "ruleId": "58c14a976e0ab87da6e22ab8",
                        "trayId": "58c14a896e0ab87da6e22ab5",
                        "trayName": "Tray1"
                    },
                    "reporter": {
                        "reportedAt": "2017-12-07T13:20:00.277Z",
                        "companyId": "58c134d70f72205b78f70c52"
                    }
                }
            ],
            "amountTotal": 3,
            "totalWeight": 10,
            "totalVolume": 0.001,
            "batchFileId": "5a293ff4154052689695975c",
            "tntKey": "0cde7e17-0a2f-4482-b13e-7bbee9536e9a",
            "wuxusNumber": "HAU-169-51591878",
            "created": "2017-12-07T13:19:51.880Z",
            "modified": "2017-12-07T13:20:00.277Z",
            "creator": {
                "companyId": "58c134d70f72205b78f70c52",
                "companyName": "Hauler Name"
            }
        },
        {
            "_id": "5a293ff736896b6c21db6004",
            "orderNumber": "TEST-ORDER-NUMBER-1",
            "requisition": "TEST_REQUISITION",
            "orderType": "adhoc",
            "paidBy": "Wuxus A/S",
            "origin": {
                "companyName": "Example Sender A/S",
                "attention": "John Doe",
                "address": "Klausdalsbrovej 601",
                "extraInfo": "Gate 5",
                "zipCode": "2750",
                "city": "Ballerup",
                "countryCode": "DK",
                "email": "john.doe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 123456789
                },
                "timeWindow": {
                    "start": "2017-08-11T10:00:00.000Z",
                    "end": "2017-08-11T12:00:00.000Z",
                    "timeType": "between",
                    "lock": true
                },
                "comments": "Just walk in and to the second floor. We'll be there",
                "timeZone": "Europe/Copenhagen",
                "geoWarn": false,
                "coordinates": {
                    "lat": 55.738892,
                    "lng": 12.3999657
                }
            },
            "destination": {
                "companyName": "Example Production A/S",
                "attention": "Mike",
                "address": "Gammel Lyngvej 2",
                "extraInfo": "Delivery Entrance",
                "zipCode": "4600",
                "city": "Køge",
                "countryCode": "DK",
                "email": "jane.doe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 234567894
                },
                "timeWindow": {
                    "start": "2017-08-11T10:00:00.000Z",
                    "end": "2017-08-11T12:00:00.000Z",
                    "timeType": "between",
                    "lock": true
                },
                "comments": "We're in the middle of the building",
                "timeZone": "Europe/Copenhagen",
                "geoWarn": false,
                "coordinates": {
                    "lat": 55.4826613,
                    "lng": 12.1846249
                }
            },
            "sender": {
                "companyName": "Example Sender A/S",
                "attention": "John Roe",
                "address": "Klausdalsbrovej 615",
                "extraInfo": "The Camp",
                "zipCode": "4600",
                "city": "Køge",
                "countryCode": "DK",
                "email": "john.roe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 345678901
                },
                "comments": "Contact John if there are any problems",
                "timeZone": "utc"
            },
            "receiver": {
                "companyName": "Example Production A/S",
                "attention": "Jane Roe",
                "address": "Galoche Alle 15",
                "extraInfo": "Den hvide by",
                "zipCode": "4600",
                "city": "Køge",
                "countryCode": "DK",
                "email": "jane.roe@example.com",
                "phone": {
                    "prefix": 45,
                    "number": 456789012
                },
                "comments": "If door closed, just put it in front of the door",
                "timeZone": "utc"
            },
            "cargo": [
                {
                    "cargoReference": "CARGO-BIG",
                    "cargoNr": "10000#12345",
                    "description": "A little big box",
                    "type": "box",
                    "amount": 1,
                    "weight": 10,
                    "volume": 0.001,
                    "dimensions": {
                        "height": 10,
                        "width": 10,
                        "length": 10
                    },
                    "barcode": "BARCODE#SCAN#1",
                    "services": [
                        {
                            "serviceId": "588ef7efccf9b6fd26e38941",
                            "companyId": "5a293ff736896b6c21db6000"
                        },
                        {
                            "serviceId": "5912f89202bdd2626ba7ebf9",
                            "companyId": "5a293ff736896b6c21db6001"
                        }
                    ],
                    "cargoId": "5a293ff736896b6c21db5fff"
                },
                {
                    "cargoReference": "CARGO-SMALL",
                    "cargoNr": "20000#12345",
                    "description": "A little small box",
                    "type": "box",
                    "amount": 2,
                    "barcode": "BARCODE#SCAN#11",
                    "services": [
                        {
                            "serviceId": "5912f89202bdd2626ba7ebf9",
                            "companyId": "5a293ff736896b6c21db6003"
                        }
                    ],
                    "volume": 0,
                    "cargoId": "5a293ff736896b6c21db6002"
                }
            ],
            "status": "todo",
            "haulier": {
                "companyId": "58c134d70f72205b78f70c52",
                "name": "Hauler Name"
            },
            "history": [
                {
                    "historyId": "5a293ff736896b6c21db5ffe",
                    "created": "2017-12-07T13:19:51.866Z",
                    "action": "batchUpload",
                    "status": "validated",
                    "reporter": {
                        "reportedAt": "2017-12-07T13:19:51.866Z",
                        "companyId": "58c134d70f72205b78f70c52"
                    }
                },
                {
                    "historyId": "5a29400036896b6c21db603b",
                    "created": "2017-12-07T13:20:00.271Z",
                    "action": "traySorted",
                    "status": "todo",
                    "subStatusData": {
                        "ruleId": "58c14a976e0ab87da6e22ab8",
                        "trayId": "58c14a896e0ab87da6e22ab5",
                        "trayName": "Tray1"
                    },
                    "reporter": {
                        "reportedAt": "2017-12-07T13:20:00.271Z",
                        "companyId": "58c134d70f72205b78f70c52"
                    }
                }
            ],
            "amountTotal": 3,
            "totalWeight": 10,
            "totalVolume": 0.001,
            "batchFileId": "5a293ff4154052689695975c",
            "tntKey": "a97d4872-c697-47d0-b010-981a11e95df9",
            "wuxusNumber": "HAU-168-51591868",
            "created": "2017-12-07T13:19:51.870Z",
            "modified": "2017-12-07T13:20:00.272Z",
            "creator": {
                "companyId": "58c134d70f72205b78f70c52",
                "companyName": "Hauler Name"
            },
          	"customFields": {
                "specialTransport": "Computers",
              	"customDate": "2018-04-13T13:30:00.000Z",
              	"customCondition": true,
              	"customNumber": 123
            }
        }
    ],
    "info": {
        "skip": 0,
        "take": 200,
        "count": false,
        "export": false,
        "filter": {
            "search": "example",
            "owner": "creator"
        }
    }
}

Query Params

filter
json

A JSON object containing the search query. For a complete list of searchable keys, look further down.

take
int32

Defines how many orders that should to received in one take. The maximum value is 200.

skip
int32

Defines how many orders to skip. Is useful with pagination

Headers

APIkey
string
required

Your company's API key to Wuxus

 

Used to retrieve an array of orders satisfying the search criteria. Will only get orders for which the user is either creator or hauler.

Searchable keys in filter

This is a table containing all the searchable keys, that can be used in the filter query parameter.

Key
Description

fliterBy

Filter by the orders status. Can be todo, planned, inTransit, canceled, done, archived, failedTask, unknownTask or unassign

vehicle

The id of a vehicle. Can only be string

geoWarn

A boolean if you want to filter on geo warns. If geo warn is true, the address might be wrong

orderIds

An array of orderIds to filter on

dateFrom

String containing a date in UTC format. Is filtering on time windows in an order

dateTo

String containing a date in UTC format. Is filtering on time windows in an order

createdFrom

String containing a date in UTC format. Is filtering on when the order was created

createdTo

String containing a date in UTC format. Is filtering on when the order was created

modifiedFrom

String containing a date in UTC format. Is filtering on when the order last was modified

modifiedTo

String containing a date in UTC format. Is filtering on when the order last was modified

search

An string that search on addresses, company names, requisition, order numbers, cargo descriptions and attention

batchFileId

A string containing an id of a batch file that have been uploaded. Can be used to filter on batch file uploads

contractKey

A string containing a key of a contract. Can be used to filter on orders that's assign to a contract

owner

String that can be haulier, forwarder or creator. This is used to filter on orders where you are haulier, forwarder or creator

combo

An array where different combination can be listed. The options for combo is down below

Options for combo

This is a table containing all the options for combo.

Key
Description

origin.address

The address of the origin

origin.zipCode

Zip code of the origin

origin.city

City of the origin

origin.companyName

The name of the company under origin

origin.attention

The name of the attention under origin

destination.address

The address of the origin

destination.zipCode

Zip code of the origin

destination.city

City of the destination

destination.companyName

The name of the company under destination

destination.attention

The name of the attention under destination

cargo.description

The description of any of the cargos

requisition

Requisition

orderNumber

The order number provided by the creator of the order

wuxusNumber

The number of the Wuxus generates for all orders

Suggest Edits

Batch upload

 
posthttps://api.wuxus.com/public/orders/batch
curl --request POST \
  --url https://api.wuxus.com/public/orders/batch \
  --header 'apikey: APIkey'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.wuxus.com/public/orders/batch',
  headers: { apikey: 'APIkey' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.wuxus.com/public/orders/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["apikey"] = 'APIkey'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.wuxus.com/public/orders/batch");
xhr.setRequestHeader("apikey", "APIkey");

xhr.send(data);
import requests

url = "https://api.wuxus.com/public/orders/batch"

headers = {'apikey': 'APIkey'}

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "errors": null,
  "result": {
    "batchFileId": "58a014865b09850011050000"
  }
}
{
    "success": false,
    "errors": [
        "File upload failed"
    ],
    "error": "File upload failed",
    "result": null
}

Body Params

batch
file
required

A JSON file containing the payload (remember the correct mimetype)

Headers

APIkey
string
required

Your company's API key to Wuxus

 

Uploading multiple orders?

If the use case is to upload multiple orders at once, it's recommended to only upload one file with multiple orders in it

Remember to use correct content-type and mimetype

The request should be with the following content-type: application/octet-stream
Data should be sent as a JSON file with the following mimeType: application/json

Table of Contents

1. Introduction

This API is used to batch upload one or more orders into the Wuxus platform.

Uploads a file with multiple orders. The file must be a JSON file meeting the model or an XLSX file in accordance with the template, which can be found on the page Find Transport -> Upload file in the Wuxus platform.

JSON files are prefered. The size is smaller, the handling is faster and more robust, since it does not need converting first. If the file is a JSON the mimeType MUST be application/json. Orders will be created with the uploading company(user) as creator and with the user matching the contract key in the file as the performing hauler. If the contract key is not present or does not match, the orders will be assigned to the uploading user instead.

Data is sent in the body as form-data.

Progress monitoring

You can check the progress of the orders uploading when you upload orders. When you make a request to the batch upload and it's a success (check above for the 200 OK example), you will get a batchFileId out. You can use this, to make a request to Batch upload status to check for the progress.

2. Where to find required keys

The require keys can be found in the same place where the APIkey can be found, on the page "File upload" under "Orders".

The contractKey is used in the JSON file or the Excel file, to determined which of companies you have contracts with, should received the order.

3. Property descriptions

Some properties/keys need a more thorough description, which follows here.

3.1. origin, destination, sender, receiver

Key
Description

origin (required)

Is where the goods will be picked up.

destination (required)

Is where the goods will be delivered.

sender (optional)

Is the entity that is responsible for the shipping of the goods.

receiver (optional)

Is the entity that is responsible for the receiving the goods.

3.2. timeWindow

If no timeWindow object is present, timeframe will be defined as "Whenever".
timeWindow consists of the following fields: start, end, timetype & lock.

3.3. timeType

timeType
Description

anytime

Is used to keep the timeframe as only a date - this requires start to be filled.

before

Is used to keep the timeframe on a date, before a given time - this requires end to be filled.

after

Is used to keep the timeframe on a date, after a given time - this requires start to be filled.

between

Is used to keep the timeframe on a date, between two given points in time - this requires both start and end to be filled.

Date time format

All the date times needs to be converted from local time, to UTC ISO-8601 format. For example:
The time in Denmark is 2017-12-24T15:30:00Z which will be 2017-12-24T14:30:00Z in UTC ISO-8601 format.

3.4. lock

lock is used to highlight the timeframe within the Wuxus platform. We recommend using this for anything out of the usual or highly important, and not on all timeframes.

3.5. address, zipCode & city

Wuxus validates and fetches GeoCode data for addresses using Google Maps APIs. Therefore an address must be of a Google Maps valid format, to be properly recognised by Google Maps.

If an address is not recognised by Google Maps, Wuxus marks the address with a geoWarn flag, which informs users that there is an issue with the address. This creates extra work for the dispatchers as they need to correct the address to get reliable delivery time estimations.

In most cases this issue is due to extra address information being added in the address field, such as 'Gate 4' or '2. floor right'. To help minimise the number of geoWarns in the system we recommend that all extra address information is added to the extraInfo field whenever possible.

3.6. ruleset

This is only for origin and destination
This define what ruleset that should be used for either origin or destination.
An example:

{
  "ruleset": {
    "rulesetId": "588ef4a2ccf9b6fd37f14561",
    "name": "Name of the ruleset
  }
}

The name is the name of the ruleset that you have created in the system.

3.7. coordinates

If you have your own coordinates for an address that you want to use, you can specified them in the coordinates object. This can be added to origin, destination, sender and receiver: An example:

{
  "coordinates": {
    "lat": 55.736501,
    "lng": 12.398360
  }
}

3.8. cargo.services

Array String

A piece of cargo can have from zero to multiple services. The choice of services are limited to the list below. Send each desired Service ID as a String in the services array.

Service Type
Service ID

Carry-down

588ef489ccf9b6fd26e38935

Carry-down 2-man

588ef4a2ccf9b6fd26e38936

Return

588ef51bccf9b6fd26e38937

Return carry-down

5912e2e802bdd2626ba7ebf7

Return carry-down 2-man

5912e2f402bdd2626ba7ebf8

Curbstone Delivery

5912e2bb02bdd2626ba7ebf5

Delivery vehicleside

5912e2db02bdd2626ba7ebf6

Carry-up

588ef5b9ccf9b6fd26e38938

Carry-up 2-man

588ef5c7ccf9b6fd26e38939

Installation

588ef5e6ccf9b6fd26e3893a

Installation 2-man

588ef5f5ccf9b6fd26e3893b

Assembly

588ef605ccf9b6fd26e3893c

Disassembly

588ef612ccf9b6fd26e3893d

Adjustment

588ef6f9ccf9b6fd26e3893e

Disposal

588ef7c7ccf9b6fd26e3893f

Fragile

588ef7efccf9b6fd26e38941

Repair

588ef7fdccf9b6fd26e38942

Manual service

5954f19d259c6e114a8f1c33

Unknown service

5912f89202bdd2626ba7ebf9

3.9. cargo.barcode

Each item can have one barcode. Any barcode can be added as a string, but we only support the following in the app:

  • UPC-A
  • UPC-E
  • Code 39
  • Code 93
  • Code 128
  • EAN-8
  • EAN-13
  • QR
  • Data Matrix

3.10. pickuped

Boolean

An order is built up as both a pickup and a delivery task. In some distribution situations the users only consider deliveries as a single task, with a collection at a hub.

This property is used to adjust where the order is in the proces. It is mainly used for orders of the type "distribution". By setting this property to true, the order is "already considered picked up", meaning that only a delivery task remains.

3.11. customFields

Object String

An order can have customFields, which is key-value. key describe the information, value is the information. An example could be:

"customFields": {
	"specialTransport": "Computers"
}

customFields can contain following:

String

Can contain any string.

Date

Should be in UTC ISO-8601 format. Will be shown as the web clients local time on the website.

Number

Can contain any number.

Checkbox (boolean)

Is an boolean. The web client will see this as an checkbox

3.12. orderReference

The orderReference is an reference for the order that you have in your own system.

It is your responsibility to keep orderReference unique when uploading orders.

4. Schema

This is a basic guide to indicate how to use the API.

JSON Schema

Version 1.0

wuxus_json_schema.json

Test your JSON with this schema

Input your JSON in the right side.
JSON schema list

Alternate guide

wuxus_json_guide.json

5. Examples

Suggest Edits

Batch upload status

This is the recommended version of the Batch Upload API.

 
gethttps://api.wuxus.com/public/orders/batch/status/id
curl --request GET \
  --url https://api.wuxus.com/public/orders/batch/status/id \
  --header 'apikey: APIkey'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.wuxus.com/public/orders/batch/status/id',
  headers: { apikey: 'APIkey' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.wuxus.com/public/orders/batch/status/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["apikey"] = 'APIkey'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.wuxus.com/public/orders/batch/status/id");
xhr.setRequestHeader("apikey", "APIkey");

xhr.send(data);
import requests

url = "https://api.wuxus.com/public/orders/batch/status/id"

headers = {'apikey': 'APIkey'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "errors": null,
  "result": {
    "status": "completed",
    "progress": 100,
    "done": 5,
    "failed": 0,
    "createdOrderIds": [
      "5be009cc16d0c80014fa5745",
      "5be009cc16d0c80014fa5748",
      "5be009cc16d0c80014fa574b",
      "5be009cc16d0c80014fa574e",
      "5be009cc16d0c80014fa5751"
    ],
    "errors": []
  },
  "info": {
    "skip": 0,
    "take": 200,
    "count": false,
    "export": false
  }
}
{
  "success": true,
  "errors": null,
  "result": {
    "status": "completed",
    "progress": 100,
    "done": 3,
    "failed": 2,
    "createdOrderIds": [
      "5be009cc16d0c80014fa5745",
      "5be009cc16d0c80014fa5748",
      "5be009cc16d0c80014fa574b"
    ],
    "errors": [
      {
        "index": 0,
        "path": [
          "orderNumber"
        ],
        "message": "missing orderNumber"
      },
      {
        "index": 1,
        "path": [
          "",
          "origin",
          "phone",
          "number"
        ],
        "message": "should be number,null"
      }
    ]
  },
  "info": {
    "skip": 0,
    "take": 200,
    "count": false,
    "export": false
  }
}
{
  "success": true,
  "errors": null,
  "result": {
    "status": "processing",
    "progress": 10,
    "done": 5,
    "failed": 0,
    "createdOrderIds": [
      "5b7fa6b7008403796d69f6a1",
      "5b7fa6b8008403796d69f6a4",
      "5b7fa6b8008403796d69f6a7",
      "5b7fa6b8008403796d69f6aa",
      "5b7fa6b8008403796d69f6ad"
    ],
    "errors": []
  },
  "info": {
    "skip": 0,
    "take": 200,
    "count": false,
    "export": false
  }
}
{
  "success": true,
  "errors": null,
  "result": {
    "status": "processing",
    "progress": 12,
    "done": 5,
    "failed": 1,
    "createdOrderIds": [
      "5b7fa6b7008403796d69f6a1",
      "5b7fa6b8008403796d69f6a4",
      "5b7fa6b8008403796d69f6a7",
      "5b7fa6b8008403796d69f6aa",
      "5b7fa6b8008403796d69f6ad"
    ],
    "errors": [
      {
        "index": 0,
        "path": [
          "orderNumber"
        ],
        "message": "missing orderNumber"
      }
    ]
  },
  "info": {
    "skip": 0,
    "take": 200,
    "count": false,
    "export": false
  }
}
{
  "success": true,
  "errors": null,
  "result": {
    "status": "failed",
    "progress": 0,
    "done": 0,
    "failed": 0,
    "createdOrderIds": [],
    "errors": [
      {
        "index": 0,
        "path": [],
        "message": "No orders in file"
      }
    ]
  },
  "info": {
    "skip": 0,
    "take": 200,
    "count": false,
    "export": false
  }
}

Path Params

id
string
required

The id from batchFileId

Headers

APIkey
string
required

Your company's API key to Wuxus

 

Automate your order upload validation

It is highly recommended to create automated validation on your order upload flow. This API can help you with that.

Based on our experiences, we recommend you set up validation on at least these two 'layers':

  1. Internal validation that the orders your system expects to be sent, have actually been sent to Dropboy.
  2. Use our API to validate that the orders were successfully uploaded into Dropboy and handle any potential errors.
Key
Description

status

The status of the upload

progress

Progress of the upload in percent

done

How many of the orders that's done processing. Only orders without errors will count

failed

How many of the orders that have failed the processing

createdOrderIds

The list of order ids that have been created

errors

An array that contains information of why the failed orders failed. Can be used to correct the errors.

status

This is a list of all the different statuses the batch upload can have

status
Description

completed

The file processing is done. Check createdOrderIds to get the list of created order ids

processing

The file is being processed

failed

The file cannot be used. This is either due to the file being empty or that it does not follow the format

Both completed and processing can contain errors. These errors can be corrected and be uploaded with a new file.

errors

errors is an array containing object of information on what went wrong. An object in errors could look like this:

{
    "index" : 0,
    "path" : [ 
        "", 
        "origin", 
        "phone", 
        "number"
    ],
    "message" : "should be number,null"
}

A more detailed description of the keys in the object:

Key
Description

index

Describes the index of the failed order within the orders array. It starts from 0

path

The path in the order object where the error is detected. In the example it's the origins phone number.

message

Describes what was wrong. In the example the message is that the origins phone number should be a number

Suggest Edits

Batch upload status (Deprecated)

This API is deprecated, please see Batch upload status

 
gethttps://api.wuxus.com/public/orders/batch/id
curl --request GET \
  --url https://api.wuxus.com/public/orders/batch/id \
  --header 'apikey: APIkey'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.wuxus.com/public/orders/batch/id',
  headers: { apikey: 'APIkey' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.wuxus.com/public/orders/batch/id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["apikey"] = 'APIkey'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.wuxus.com/public/orders/batch/id");
xhr.setRequestHeader("apikey", "APIkey");

xhr.send(data);
import requests

url = "https://api.wuxus.com/public/orders/batch/id"

headers = {'apikey': 'APIkey'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "errors": null,
    "result": {
        "_id": "5a313604af52f90014fa38fd",
        "companyId": "57c9417d5a32cb00119b83da",
        "status": "sentToTraySorter",
        "created": "2017-12-13T14:15:32.520Z",
        "modified": "2017-12-13T14:15:33.830Z",
        "originalName": "orders/batch/57c9417d5a32cb00119b83da/b492c639-3da9-4381-ae70-b12009166095.json",
        "convertedName": "orders/batch/57c9417d5a32cb00119b83da/b492c639-3da9-4381-ae70-b12009166095.json",
        "mimeType": "application/json",
        "processPercent": 100,
        "done": 2,
        "failed": 0,
        "orderIds": [
            "5a31360406a63600144c9fd6",
            "5a31360406a63600144c9fdb"
        ]
    }
}
{
    "success": true,
    "errors": null,
    "result": {
        "_id": "5a312f9caf52f90014fa387a",
        "companyId": "57c9417d5a32cb00119b83da",
        "status": "sentToTraySorter",
        "created": "2017-12-13T13:48:12.590Z",
        "modified": "2017-12-13T13:48:13.927Z",
        "originalName": "orders/batch/57c9417d5a32cb00119b83da/be81e091-4a29-4c09-8267-8daca9eee23d.json",
        "convertedName": "orders/batch/57c9417d5a32cb00119b83da/be81e091-4a29-4c09-8267-8daca9eee23d.json",
        "mimeType": "application/json",
        "processPercent": 100,
        "done": 1,
        "failed": 1,
        "orderIds": [
            "5a312f9c06a63600144c9e97"
        ],
        "errors": [
            {
                "index": 0,
                "message": "\"order\" property not found"
            }
        ]
    }
}

Path Params

id
string
required

The id from batchFileId

Headers

APIkey
string
required

Your company's API key to Wuxus

 

Deprecated

This API is deprecated, please see Batch upload status

Key
Description

companyId

Our company id

status

The status of the upload

originalName

The original name of the file you oploaded

convertedName

The converted name of the file. It would only be difference from originalName, if you didn't uploaded a JSON file

mimeType

The mime type of the file you oploaded

processPercent

How many procent of the task that have been processed

done

How many of the orders that's done processing. Only orders without errors will count

failed

How many of the orders that have failed the processing

orderIds

The list of order ids that have been created

errors

An array that contains information of why the failed orders failed. Can be used to correct the errors.

status

This is a list of all the different status the batch upload can have

status
Description

init

This is the status when the upload starts

uploaded

This is the status when the file have been uploaded

uploadFail

This is the status if the file haven't been uploaded

converting

This is the status when the file is being converted

converted

This is the status when the file have been converted

convertFail

This is the status when the file haven't been converted due to an error

processing

The is the status when the file is being processed

processFail

The is the status when the file haven't been processed due to an error

sentToTraySorter

This is the status when all the orders is being send to the tray sorter. This is also the status when the batch upload is finished

errors

errors is an array containing object of information on what went wrong. An object in errors could look like this:

{
    "index" : 0,
    "path" : [ 
        "", 
        "origin", 
        "phone", 
        "number"
    ],
    "message" : "should be number,null"
}

A more detail description of the keys in the object:

Key
Description

index

Tells which order went wrong. It starts from 0

path

The path in the order object where in went wrong. In the example it's the origins phone number.

message

Describes what was wrong. In the example the message is the origins phone number should be a number

Suggest Edits

Cancel orders

 
posthttps://api.wuxus.com/public/orders/cancel
{
  "comments": "This is a very good comment",
  "orderIds": [
    "58988a0dfc3d8c0011fa6298",
    "58b9599df3d15c001111122e"
  ]
}
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "errors": null,
    "result": []
}
{
    "success": true,
    "errors": null,
    "result": [
        {
            "orderId": "5a31360406a63610144c9fd6",
            "message": "no order found"
        }
    ]
}

Body Params

comments
string

The comment that will be added to the orders when canceling them

orderIds
array of strings

All orders ids that should be canceled

Headers

APIKey
string
required

Your company's API key to Wuxus

 

When cancelling an order, the order is retracted from the haulier, and if the order is assigned to a task list, it will also get retracted from there. This means that you should only cancel an order, if you are absolutely sure, that the order should be cancelled, as it will not appear for the haulier or on task list.

We recommend that the users in the integrating system gets a warning when attempting to cancel orders, similar to the warning that is in the Wuxus platform.

Suggest Edits

Edit order

 
patchhttps://api.wuxus.com/public/orders
{
  "order": {
    "destination": {
     	"timeWindow": {
        "start": "2018-03-09T10:30:00.000Z",
        "end": "2018-03-09Y13:30:00.000Z"
      }
    }
  },
  "orderIds": [
    "58f71c7d97b77e0011c14f02",
    "58f71c7d97b77e0011c14f03"
  ]
}
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

order
json
required

The model of the edit order

orderIds
array of strings
required

An array of orderIds that should be updated

Headers

APIKey
string
required

Your company's API key to Wuxus

 

This endpoint is for editing one or more orders.

order is what needs to be edited. It's not necessary to send the whole order, only the data the needs to be edited. For example if you want to edit origin address, you can just send this:

{
  "order": {
    "origin": {
      "address": "Klausdalsbrovej 601",
      "zipCode": "2750",
      "city": "Ballerup"
    }
  }
}

This will only change address, zipCode and city under origin

Recommendation

It is recommended only to send the edited part. It is possible to send unedited data, but to save data it's better to only send the edited data.

Edit cargo

If you want to edit the cargo lines, it is necessary to list all of them, and not the edited one.

Suggest Edits

Send to routing rules

 
gethttps://api.wuxus.com/public/orders/routing/sort
{
  "orderIds": [
    "585cf638e600ae21a8f6f671"
    ]
}
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

orderIds
array of strings
required

Headers

APIkey
string
required

Your company's API key to Wuxus

 

This endpoint let you send the orders through the routing rules again. It is useful if you have edited an order, and what to replace it, or make sure if gets on the correct vehicle if the order have been edited.

You should list all the order(s) you want to send through routing rules in ordersId

Suggest Edits

Introduction to Routes

 

The Route API is used for creating and updating routes.

With this API you can:

  1. Create routes with stops
  2. Update routes
  3. Updates stops
Suggest Edits

Route batch upload

 

Header Auth

 Authentication is required for this endpoint.
posthttps://api.wuxus.com/public/routes/batch
curl --request POST \
  --url https://api.wuxus.com/public/routes/batch \
  --header 'apikey: APIKey' \
  --header 'content-type: multipart/form-data'
var request = require("request");

var options = { method: 'POST',
  url: 'https://api.wuxus.com/public/routes/batch',
  headers: 
   { 'content-type': 'multipart/form-data',
     apikey: 'APIKey' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.wuxus.com/public/routes/batch")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["apikey"] = 'APIKey'
request["content-type"] = 'multipart/form-data'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("POST", "https://api.wuxus.com/public/routes/batch");
xhr.setRequestHeader("apikey", "APIKey");
xhr.setRequestHeader("content-type", "multipart/form-data");

xhr.send(data);
import requests

url = "https://api.wuxus.com/public/routes/batch"

headers = {
    'apikey': "APIKey",
    'content-type': "multipart/form-data"
    }

response = requests.request("POST", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
  "success": true,
  "errors": null,
  "result": {
    "batchFileId": "5bced678eca903b0369e4f37"
  }
}
{
    "success": false,
    "errors": [
        "File upload failed"
    ],
    "error": "File upload failed",
    "result": null
}

Body Params

body
file
required

A JSON file containing the payload (remember the correct mimetype)

Headers

APIKey
string
required

Your company's API key to Dropboy

Content-Type
string
required
 

Uploading multiple routes?

If the use case is to upload multiple routes at once, it's recommended to only upload one file with multiple routes in it

Remember to use the correct content-type and mimetype

The request should be with the following content-type: application/octet-stream
Data should be sent as a JSON file with the following mimeType: application/json

Table of Contents

1. Introduction

The API is used to batch upload one or more routes into the Dropboy platform.

Uploads a file with multiple routes. The file must be a JSON file meeting the model.

2. Property descriptions

2.1. overwrite

This describe if the route should be overwritten. If overwrite is set to true, it would overwrite the route instead of adding to the route.

2.2. route

The route object contains all the information about the route

Key
Description

routeId

If the route already exists, the id of it can be set here

routeTemplateId

If the new route should be created from a route template, the id of the route template can be set here

routeTemplateReference

If the route have a route template reference, the reference can be set here

routeReference

If the route have an reference, it can be set here

date

The date of when the route should be handled

routeName

The name of the route

stops

Contains the list of stop objects

ruleset

Contains the information about ruleset

tags

A list of strings

2.3. stops

The stops array contains all the stops that should be handled on the route

Key
Description

stopId

Set the stopId to update existing stop

stopReference

If the stop have a reference, it can be set here

wayPoint

The way point number. Can only be a number

instructions

If there are instructions for the stop it can be set here

persistent

Can only be a boolean. If set to true, only a user can manual delete this stop.

orders

The list of orders on the stop

customFields

Contains the custom fields that can be set

info

Information about stop, like address and name of the company

locationReference

A reference to the location of the stop

stopType

Set to hub when the stop is used as a terminal

2.3.1 customFields

The customFields is a list of key-value. key describe the information and the value contains the information.

"customFields": {
  "stopType": "house"
}

customFields can contain following:

String

Can contain any string

Date

Should be in UTC ISO-8601 format. Will be shown as the web clients local time on the website.

Number

Can contain any number.

Checkbox (boolean)

Is an boolean. The web client will see this as an checkbox.

2.4. instructions

The instructions object contain the instructions for the stop if there are any

Key
Description

mode

Can be none, optional or required. Define what mode the instructions is in

value

The text the instructions have. This can be in Markdown

2.4.1. mode

When mode is set to none, the user do not have any action to mark the instructions as done. If mode is set to optional or required, the user have the instructions. The difference between these two modes, is that when required is set, the user have to mark the instructions as done.

2.5. orders

The orders array contains the list of orders that should be handled on a specific stop

Key
Description

orderId

The id of the order

orderReference

Your reference to the order

actionType

What type of action. It can be either pickup or delivery

cargo

The list of cargoId's the order should handle

It is not necessary to specify both orderId and orderReference. You can just use one of them.

If cargo is not specified, all cargo items from the order will be part of this pickup/delivery task.

2.6. info

info will contain all the information that are necessary for the stop, like the address and attention if that is necessary for the stop.

2.6.1. timeWindow

The time window where the stop should be handle between.

2.6.2. openWindow

This is an alternative to timeWindow, which is not visible to the driver.

2.6.3. coordinates

If you have your own coordinates for an address, you can specify them here. They are structured by an object contains lat for latitude and lng for longitude. As an example:

{
  "coordinates": {
    "lat": 55.736501,
    "lng": 12.398360
  }
}

2.7. tags

List all the tags in an array of strings. An example:

{
  "tags": ["here", "goes", "all", "the", "tags"]
}

Date time format

All the date times need to be converted from local time to UTC ISO-8601 format

3. Examples

Minimal example

route_minimal.json

New route full example

route_full_new.json

Existing route full example

route_full_existing.json

Suggest Edits

Introduction to Track and Trace

The basics of the Orders endpoints

 

The Track and Trace API is used for retrieving Track and Trace information such as order status.

The same information could be gathered from the Orders API, however, that API supplies a high amount of redundant data and should therefore only be used if there is a need for the order data.

Use the Track and Trace API for continuous updates on order statuses.

Suggest Edits

Order status

 
gethttps://api.wuxus.com/public/orders/status
curl --request GET \
  --url https://api.wuxus.com/public/orders/status \
  --header 'apikey: APIkey'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.wuxus.com/public/orders/status',
  headers: { apikey: 'APIkey' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.wuxus.com/public/orders/status")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["apikey"] = 'APIkey'

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.wuxus.com/public/orders/status");
xhr.setRequestHeader("apikey", "APIkey");

xhr.send(data);
import requests

url = "https://api.wuxus.com/public/orders/status"

headers = {'apikey': 'APIkey'}

response = requests.request("GET", url, headers=headers)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "success": true,
    "errors": null,
    "result": [
        {
            "orderId": "5a31360406a63600144c9fdb",
            "taskType": "pickup",
            "status": "finished",
            "modified": "2017-12-15T09:03:19.880Z",
            "estimated": "2017-12-15T12:00:00.000Z",
            "actual": "2017-12-15T09:01:21.471Z",
            "orderNumber": "TEST-1234"
        },
        {
            "orderId": "5a31360406a63600144c9fdb",
            "taskType": "delivery",
            "status": "finished",
            "modified": "2017-12-15T09:03:19.880Z",
            "estimated": "2017-12-15T09:29:54.471Z",
            "actual": "2017-12-15T09:03:18.471Z",
            "orderNumber": "TEST-1234"
        }
    ]
}
{
    "success": true,
    "errors": null,
    "result": []
}

Path Params

filter
json
required

A JSON object containing the search query. For a complete list of searchable keys, look further down.

Headers

APIkey
string
required

Your company's API key to Wuxus

 

Options in filter

Key
Description

modified

The date for when the tasks last was changed

date

The date for when the tasks was assigned. If modified is set, date is ignored

contract

The contract key the orders was created with

Result description

Key
Description

orderId

The id of the order

taskType

What type of task it is. Can be pickup or delivery

status

What status the task have. Can be todo, finished, failed or partial

modified

The last time the task list was modified

estimated

The estimated time of arrival for the task

actual

The actual time of departure for the task

orderNumber

The orders order number

Suggest Edits

Using webhooks

 

Wuxus have support for some webhooks, which help companies to integrate their own systems with Wuxus.

Wuxus currently support these webhooks:

To enable and setup webhooks, you have to go into Settings (1) in the side menu, and then to Developer tools (2) in the top menu. It should look like this

The list of available webhooks

The list of available webhooks

To enable a webhook, enter the URL of where the webhook should request to, either http:// or https://. Then click to enable the webhooks, and go to the bottom of the site and press Save

It is recommended to use https:// instead of http://, because there could be confidential information in the webhook request.

Output format

The output from a webhook could look like this:

{
  "name": "createOrder",
  "sent": "2018-04-12T10:37:05.601Z",
  "data": [
    {
      "orderId": "5acf36d1a2261f5d4edb91b3",
      "wuxusNumber": "HAU-392-45425580",
      "createType": "order"
    }
  ]
}
Key
Description

name

The name of the type of webhook that have been send. In this case it is Order creation webhook

send

What time Wuxus sent the webhook. The time will always be in UTC ISO-8601 format.

sent

What time Wuxus sent the webhook. The time will always be in UTC ISO-8601 format.

data

The data necessary for the webhook

send is obsolete and will be unavailable after 1st July 2018

Suggest Edits

Order creation

 

This webhook will be called when one or more orders have been created. The request from the webhook would look like this:

{
  "name": "createOrder",
  "sent": "2018-04-13T08:12:56.320Z",
  "data": [
    {
      "orderId": "5ad066886a9deecd679e6ac5",
      "orderNumber": "WUX-123-45678901",
      "wuxusNumber": "HAU-393-36776027",
      "requisition": "this-is-requisition",
      "createType": "order"
    }
  ]
}

The data contains:

Key
Description

orderId

The id of the created order.

orderNumber

The order number the order have been given.

wuxusNumber

The "orderNumber" Wuxus have generated. If orderNumber is not set, this will be displayed as order number within Wuxus.

requisition

The requisition the order have been given.

createType

How the order was created. This can be order which is an order created manually. api is when it is created from API or from a file. truckFinder is when the order is created from a TruckFinder search.

If orderNumber or requisition is not set, it will not be in the payload.

Suggest Edits

On pickup

 

This webhook will be called when one or more orders have been picked up by a driver. The request from the webhook would look like this:

{
  "name": "pickupOrder",
  "sent": "2018-04-13T08:40:28.297Z",
  "data": [
    {
      "orderId": "5ad066886a9deecd679e6ac5",
      "orderNumber": "WUX-123-45678901",
      "wuxusNumber": "HAU-393-36776027",
      "requisition": "this-is-requisition",
      "status": "inTransit"
    }
  ]
}

The data contains:

Key
Description

orderId

The id of the order.

orderNumber

The order number the order have been given.

wuxusNumber

The "orderNumber" Wuxus have generated. If orderNumber is not set, this will be displayed as order number within Wuxus.

requisition

The requisition the order have been given.

status

inTransit is when the order was picked up successfully. onHold is when the order was not picked up successfully.

If orderNumber or requisition is not set, it will not be in the payload.

Suggest Edits

On delivery

 

This webhook will be called when one or more orders have been delivered by a driver. The request from the webhook would look like this:

{
  "name": "deliverOrder",
  "sent": "2018-04-13T09:53:50.178Z",
  "data": [
    {
      "orderId": "5ad066886a9deecd679e6ac5",
      "orderNumber": "WUX-123-45678901",
      "wuxusNumber": "HAU-393-36776027",
      "requisition": "this-is-requisition",
      "status": "done"
    }
  ]
}

The data contains:

Key
Description

orderId

The id of the order.

orderNumber

The order number the order have been given.

wuxusNumber

The "orderNumber" Wuxus have generated. If orderNumber is not set, this will be displayed as order number within Wuxus.

requisition

The requisition the order have been given.

status

done is when the order was delivered successfully. returning is when the order was not delivered successfully.

If orderNumber or requisition is not set, it will not be in the payload.

Suggest Edits

On ETA changed

 

This webhook will be called when an order have changed it's ETA. The request from the webhook would look like this:

{
  "name": "etaChangedOrder",
  "sent": "2018-04-13T10:55:23.623Z",
  "data": [
    {
      "orderId": "5ad066886a9deecd679e6ac5",
      "orderNumber": "WUX-123-45678901",
      "wuxusNumber": "HAU-393-36776027",
      "requisition": "this-is-requisition",
      "origin": {
        "previous": null,
        "current": "2018-04-13T13:00:00.000Z"
      },
      "destination": {
        "previous": null,
        "current": "2018-04-13T13:32:51.000Z"
      }
    }
  ]
}

The data contains:

Key
Description

orderId

The id of the order.

orderNumber

The order number the order have been given.

wuxusNumber

The "orderNumber" Wuxus have generated. If orderNumber is not set, this will be displayed as order number within Wuxus.

requisition

The requisition the order have been given.

origin.previous

Origin's previous ETA time.

origin.current

Origin's current ETA time.

destination.previous

Destination's previous ETA time.

destination.current

Destination's current ETA time.

If orderNumber or requisition is not set, it will not be in the payload.

Suggest Edits

"Driver is on the way"

 

This webhook will be called when a driver either have pressed Is on way button on a Load hub, or when the driver have either picked up or delivered an order, and there are more tasks on his list.

{
  "name": "driverIsOnWayOrder",
  "sent": "2018-04-13T11:20:00.129Z",
  "data": [
    {
      "orderId": "5ad066886a9deecd679e6ac5",
      "orderNumber": "WUX-123-45678901",
      "wuxusNumber": "HAU-393-36776027",
      "requisition": "this-is-requisition",
      "type": "destination",
      "eta": "2018-04-13T11:20:00.087Z"
    }
  ]
}

The data contains:

Key
Description

orderId

The id of the order.

orderNumber

The order number the order have been given.

wuxusNumber

The "orderNumber" Wuxus have generated. If orderNumber is not set, this will be displayed as order number within Wuxus.

requisition

The requisition the order have been given.

type

What type of task the driver is on the way to.

eta

What the ETA for the driver to arrive.

If orderNumber or requisition is not set, it will not be in the payload.

Suggest Edits

Order tracking

 

This webhook will be called when there are a tracking update on a vehicle. It will list all the orders that the vehicle have on it's task list, also them which have not been picked up yet, or have been delivered.

{
  "name": "orderTracking",
  "sent": "2018-04-13T12:38:07.064Z",
  "data": [
    {
      "vehicleId": "58c136a30f72205b78f70c6e",
      "nickname": "Wuxus Vehicle",
      "registryNumber": "WX 12 345",
      "vehicleType": "van",
      "driverId": "57c9417d5a32cb00119b83db",
      "driverName": "John Doe",
      "phone": {
        "prefix": 45,
        "number": 12345678
      },
      "position": {
        "lat": 55.738773,
        "lng": 12.398563,
        "updated": "2018-04-13T12:38:07.041Z"
      },
      "orders": [
        {
          "orderId": "5ad066886a9deecd679e6ac5",
          "orderNumber": "WUX-123-45678901",
          "wuxusNumber": "HAU-393-36776027",
          "requisition": "this-is-requisition-1"
        },
        {
          "orderId": "5ad08f776a9deecd679e6c86",
          "orderNumber": "",
          "wuxusNumber": "HAU-395-47255633",
          "requisition": "this-is-requisition-2"
        }
      ]
    }
  ]
}

The data contains:

Key
Description

vehicleId

The id of the vehicle.

nickname

The nickname of the vehicle.

registryNumber

The registry number of the vehicle.

vehicleType

The type of the vehicle. Can be:
bicycle, motorcycle, car, pickup, van, boxvan, truck, largetruck, flatbed, largeflatbed.

driverId

The id of the driver

driverName

The name of the driver.

phone (May not exist)

The phone number of the driver. This may not exist, if there are no phone number on the driver.

position.lat

The latitude coordinate where the vehicle was.

position.lng

The longitude coordinate where the vehicle was.

position.updated

The time the vehicle send it's tracking update.

orders

The list of orders on the vehicle, including those that have not yet been picked up or delivered.

Suggest Edits

Register stop

 

This webhook will be called when a stop have been registered. The request from the webhook will look like this:

{
  "name": "registerStop",
  "sent": "2019-02-05T14:02:46.433Z",
  "data": [
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERRENCE",
      "stopId": "5b4894a3e215c79fffa4e019",
      "stopReference": "STOP-REFERENCE",
      "registrations": [
        {
          "orderId": "5b4894a3e215c79fffa3e01a",
          "orderReference": "ORDER-REFERENCE",
          "cargoId": "5b4894a3e215c79fffa3e019",
          "cargoReference": "CARGO-REFERENCE",
          "actionType": "pickup",
          "success": false,
          "ruleReferences": [
            {
              "ruleReference": "scan"
            },
            {
              "ruleReference": "damage"
            }
          ]
        }
      ]
    }
  ]
}
{
  "name": "registerStop",
  "sent": "2019-02-05T14:02:46.433Z",
  "data": [
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e019",
      "stopReference": "STOP-REFERENCE",
      "registrations": [
        {
          "orderId": "5b4894a3e215c79fffa3e01a",
          "orderReference": "ORDER-REFERENCE-1",
          "cargoId": "5b4894a3e215c79fffa3e019",
          "cargoReference": "CARGO-REFERENCE-1",
          "actionType": "pickup",
          "success": false,
          "ruleReferences": [
            {
              "ruleReference": "scan"
            },
            {
              "ruleReference": "damage"
            }
          ]
        },
        {
          "orderId": "5b4894a3e215c79fffa3e01b",
          "orderReference": "ORDER-REFERENCE-2",
          "cargoId": "5b4894a3e215c79fffa3e010",
          "cargoReference": "CARGO-REFERENCE-2",
          "actionType": "pickup",
          "success": true
        },
        {
          "orderId": "5b4894a3e215c79fffa3e01c",
          "orderReference": "ORDER-REFERENCE-3",
          "cargoId": "5b4894a3e215c79fffa3e219",
          "cargoReference": "CARGO-REFERENCE-3",
          "actionType": "delivery",
          "success": true,
          "ruleReferences": [
            {
              "ruleReference": "scan"
            },
            {
              "ruleReference": "smallDamage"
            }
          ]
        }
      ]
    }
  ]
}

The data is an array containing each stop that have been registered. Each item in the data array contains:

Key
Description

routeId

The id of the route

routeReference

The reference of the route

stopId

The id of the stop

stopReference

The reference of the stop

registrations

Contains all the registrations for the stop

The registrations is an array containing each cargo that have been registered on the stop. Each item in the data registrations array contains:

Key
Description

orderId

The id of the order

orderReference

The reference of the order

cargoId

The id of the cargo

cargoReference

The reference of the cargo

actionType

Can be either pickup or delivery

success

Tell if the actions went successfully

ruleReferences

Will contains all the information about which rule items that have been used to register this cargo.

Each item in the ruleReferences is an object containing reference to which rule item that have been used inside a ruleset.
An example:

{
  "ruleReference": "scan"
}
Suggest Edits

Register time

 

This webhook will be called when one or more stops get registered time. The request from the webhook can look like this:

{
  "name": "registerTime",
  "sent": "2019-02-05T14:02:46.943Z",
  "data": [
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e019",
      "stopReference": "STOP-REFERENCE",
      "time": {
        "estimated": {
          "arrival": "2019-02-05T13:56:13.435Z",
          "departure": "2019-02-0513:59:34.348Z"
        },
        "actual": {
          "arrival": "2019-02-05T13:59:55.904Z",
          "departure": "2019-02-05T14:04:25.689Z"
        },
        "terminal": {
          "arrival": "2019-02-05T14:00:56.543Z",
          "departure": "2019-02-05T14:04:35.595Z"
        }
      }
    }
  ]
}
{
  "name": "registerTime",
  "sent": "2019-02-05T14:02:46.943Z",
  "data": [
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e019",
      "stopReference": "STOP-REFERENCE",
      "time": {
        "terminal": {
          "arrival": "2019-02-05T14:00:56.543Z"
        }
      }
    }
  ]
}
{
  "name": "registerTime",
  "sent": "2019-02-05T14:02:46.943Z",
  "data": [
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e019",
      "stopReference": "STOP-REFERENCE",
      "time": {
        "actual": {
          "departure": "2019-02-05T14:04:25.689Z"
        }
      }
    }
  ]
}
{
  "name": "registerTime",
  "sent": "2019-02-05T14:02:46.943Z",
  "data": [
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e019",
      "stopReference": "STOP-REFERENCE-1",
      "time": {
        "actual": {
          "departure": "2019-02-05T14:04:25.689Z"
        }
      }
    },
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e026",
      "stopReference": "STOP-REFERENCE-2",
      "time": {
        "estimated": {
          "arrival": "2019-02-05T14:34:65.254Z"
        }
      }
    },
    {
      "routeId": "5b4894a3e215c79fffa4e01a",
      "routeReference": "ROUTE-REFERENCE",
      "stopId": "5b4894a3e215c79fffa4e034",
      "stopReference": "STOP-REFERENCE-3",
      "time": {
        "estimated": {
          "arrival": "2019-02-05T14:42:55.376Z"
        }
      }
    }
  ]
}

Note that all information might not be visible because it is only if the information have been changed that is visible in the output. So if terminal have not been changed, terminal will not be in the data output.

Please note that the "Full example" above, is more theoretical than practical, showing all potential data values instead of what you are likely to receive.

The data contains:

Key
Description

routeId

The id of the route

stopId

The id of the stop

time

An object containing all the information about the time.

The time can contain:

estimated

What have been estimated by the system

actual

What actual time the driver have registered

terminal

What the terminal have registered

Suggest Edits

Getting Started

This page will help you get started with Route Batch API.

 

This is where you show your users how to set it up. You can use code samples, like this:

$http.post('/someUrl', data).success(successCallback);

alert('test');

Try dragging a block from the right to see how easy it is to add more content!