Batch upload

📘

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.

JSON files are preferred.

Data is sent in the body as multipart/form-data

🚧

.Remember to use correct content-type and mimetype

Data should be sent as a JSON file with the following mimeType: application/json

Batch file required

A JSON file containing the payload (remember the correct mimetype) and Data is sent in the body as multipart/form-data

Table of Contents

1. Introduction
2. Where to find required keys
3. Property descriptions
   3.1. origin, destination, sender, receiver
   3.2. timeWindow
   3.3. timeType
   3.4. lock
   3.5. address, zipCode & city
   3.6. ruleset
   3.7. coordinates
   3.8. cargo.services
   3.9. cargo.barcode
   3.10. pickuped
   3.11. customFields
   3.12. sendSMS & smsSettings
   3.13. comments, commentsFiles & commentsSpecial
   3.14. routingTags
4. Schema
5. Examples

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 preferred. 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

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

🚧

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 2022-12-24T15:30:00Z which will be 2022-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 should be ignore as standard. It's only available if you have new Route functionality enable

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.

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:

3.12. sendSMS & smsSettings

This will be set under origin and destination.

sendSMS is a flag needed to be set to true to be able to send SMS. smsSettings contains all the different types of SMS that can be send. The list is following:

{
  "sendSMS": true,
  "smsSettings": {
    "driveNow": true,
    "taskStatus": true,
    "deliverOrder": true,
    "deliverOrderFailed": true
  }
}

3.13. comments, commentsFiles & commentsSpecial

This will be set under origin and destination

comments is just a string value that contains text that will be visible on the order

commentsSpecial is a boolean that describes if the instructions is required to be read by the driver

commentsFiles

commentsFiles is an array that contains the list of files that the driver can/need to read while picking up or delivering an order

*Is required

{
  "comments": "We're in the middle of the building",
  "commentsFiles": [
    {
      "url": "https://example.com/video.mp4",
      "fileName": "video1",
      "description": "test description"
    }
  ],
    "commentsSpecial": true
}

If there are files extension that's not in the list you want to be supported, please contact support

3.14. routingTags

Type: Array String

The routingTags array is used to store strings representing key-value pairs for routing-related information. Each entry in the array is a string. The key indicates the type of information, and the value contains the corresponding details. These tags are flexible and can be customized based on the use case.

Example:

{
  "routingTags": ["TAG1", "TAG2"]
}

routingTags can contain following:

The routingTagsarray allows for multiple tags to be associated with an order. Each tag should be formatted appropriately to represent the intended routing information.

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

Minimal example

wuxus_minimal_example.json

Full example

wuxus_full_example.json

Postman examples

You need to add your API key in headers sections, and select the file you want to upload.

The export is pointed to the staging environment, but it's just changing the URL to change the environment.

{
	"info": {
		"_postman_id": "9412fbec-2c4a-4e5e-9014-dc4342252f2e",
		"name": "Order batch upload",
		"schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
		"_exporter_id": "870486",
		"_collection_link": "https://dropboy.postman.co/workspace/b8ffb935-ab83-448c-8556-a9f445497503/collection/870486-9412fbec-2c4a-4e5e-9014-dc4342252f2e?action=share&source=collection_link&creator=870486"
	},
	"item": [
		{
			"name": "/public/orders/batch",
			"request": {
				"method": "POST",
				"header": [
					{
						"key": "APIkey",
						"value": "{{apiKey}}",
						"description": "Can be found in the platform under \"Settings-> Developer Tools\""
					},
					{
						"key": "Content-Type",
						"value": "application/json"
					}
				],
				"body": {
					"mode": "formdata",
					"formdata": [
						{
							"key": "batch",
							"description": "This is the batch file as a .json file.",
							"type": "file",
							"src": []
						}
					]
				},
				"url": {
					"raw": "https://api-staging.wuxus.com/public/orders/batch",
					"protocol": "https",
					"host": [
						"api-staging",
						"wuxus",
						"com"
					],
					"path": [
						"public",
						"orders",
						"batch"
					]
				},
				"description": "<a href=\"https://docs.dropboy.com/reference/welcome\" >Documentation</a>"
			},
			"response": []
		}
	]
}

Postman export