Trademax Restful API documentation

Introduction

Introduction in development...

Requests

Each resource has self-explanatory structure with description and couple examples of usage. Query params can be passed in query string for GET and DELETE methods. For other methods params arrives within body in "x-www-form-urlencoded" format or in json format. In latter case header "Content-Type" must be set to "application/json". Requests examples with just couple params will be in query string format. Request examples will complex structure usually will be displayed in json format. You are free to use any of them.

Authentication

In addition to params in query you'll need to add 5 more params for authentication in each request:

Param name Param type Description
api_key string your public api key received from Trademax
timestamp integer time of request in unix timestamp format (https://en.wikipedia.org/wiki/Unix_time)
signature string request signature. Instruction is below.
method string http verb. For example GET, POST, PATCH...
url string you must specify the requested URL - {protocol}://{host}/{path}

The request is signed this way

  • sort all parameters sent in the request (of course without signature)
  • produce a string in the form of param1=value1&...&param99=value99
  • create the signature by hashing the string using the secret code. In php, for example, looks like this: 
    $signature = hash_hmac('sha256', $string, $secretKey);
  • for hashing pls use sha256 hash method
  • make the request to the server and pass the hashed signature

Signature generation process

1. Sorting

You need to perform "natural order" algorithm (ordering of strings in alphabetical order, except that multi-digit numbers are ordered as a single character) for all keys, including nested parts.

Structure example
"api_key":"YOUR_PUBLIC_KEY",
"external_reference":"",
"method":"POST",
"order_no":"IS0000000",
"order_type":"SO",
"packages[0][external_package_id]":"7499999",
"packages[0][package_id]":"1",
"packages[0][picking_zones][0]":"H",
"packages[0][products][0][artno]":"999",
"packages[0][products][0][line_no]":"20000",
"packages[0][volume]":"2.1",
"packages[0][weight]":"55",
"packages[1][external_package_id]":"7599999",
"packages[1][package_id]":"2",
"packages[1][picking_zones][0]":"H",
"packages[1][products][0][artno]":"998",
"packages[1][products][0][line_no]":"10000",
"packages[1][volume]":"1.5",
"packages[1][weight]":"35",
"products[0][artno]":"998",
"products[0][line_no]":"10000",
"products[0][quantity]":"1",
"products[1][artno]":"999",
"products[1][line_no]":"20000",
"products[1][quantity]":"1",
"timestamp":"1523021209",
"transaction_id":"DDDD1DdDDDDdddfffDF",
"url":"http://api.trademax.com/vendor/dispatch",
"vendor_id":"999999999"

2. Transform data

You should produce a string in the form of param1=value1&...&param99=value99, as in example. Keys order is important.

Prepared string
api_key=YOUR_PUBLIC_KEY&external_reference=&method=POST&order_no=IS0000000&order_type=SO&packages[0][external_package_id]=7499999&packages[0][package_id]=1&packages[0][picking_zones][0]=H&packages[0][products][0][artno]=998&packages[0][products][0][line_no]=20000&packages[0][volume]=2.1&packages[0][weight]=55&packages[1][external_package_id]=7599999&packages[1][package_id]=2&packages[1][picking_zones][0]=H&packages[1][products][0][artno]=999&packages[1][products][0][line_no]=10000&packages[1][volume]=1.5&packages[1][weight]=35&products[0][artno]=998&products[0][line_no]=10000&products[0][quantity]=1&products[1][artno]=999&products[1][line_no]=20000&products[1][quantity]=1×tamp=1523021209&transaction_id=DDDD1DdDDDDdddfffDF&url=http://api.trademax.com/vendor/dispatch&vendor_id=999999999

3. Generate signature

Create the signature by hashing the string using the secret code. You should use HMAC with hash function sha256.

PHP example
$signature = hash_hmac('sha256', $paramsString, $secretKey);

where:

$paramsString - transformed data from perevious step

$secretKey - your secret key provided by Trademax

4. Request

Make the request to the server and pass the hashed signature. Keys order doesn't matter.

Responses

Responses are in json format. Basic example:

{
    "error": {
        "error_code": 0,
        "error_messages": []
    },
    "data": []
}

"data" attribute will contain requested data. After updating and creating resources it contains data of created|updated element. Scope "error" is always present. On success request [error_code] will be [0] and [error_messages] will be empty.

Http status codes

Status code Description
200 Success request
400 Some client error was occurred. For example some required field was not specified
401 Authentication failed. For example signature is bad
403 Authorization failed. You may not have access to requested action
404 Resource not found
500 Server-side error

Error codes

Error code Description
1 general error code (if error code was not explicitly set in sources then error code will be equal 1)
Authentication/Authorization errors (400-449)
401 one or more of mandatory params not specified
402 one or more params have invalid values
404 public key is invalid
405 signature validation failed
406 client has not access to requested resource
407 client has not access to requested action
Input params validation failed (450-499)
450 required param not specified
451 param is invalid - some of params has bad format
452 request duplication (based on transaction_id value)
Server-side error occurred (500-599)
500 general server-side error
501 database error

Resourses

Basic api url is http://dashboard.trademax.se/api/

inventory

Getting current quantity of product for warehouse

GET
inventory/{artno}/stock-adjustment
Path params:
Param name Param type Required Description
artno string yes Product's article number
Query params:
Param name Param type Required Description
warehouse_id string yes Warehouse alias
Request Examples:

Getting current quantity of product for specified warehouse

GET
inventory/123/stock-adjustment?warehouse_id=nw
Response example: 
{
    "error": {
        "error_code": 0,
        "error_messages": []
    },
    "data": {
        'artno': 2145,
        'quantity': 542,
    }
}

Changing product quantity for one provider

PATCH
inventory/{artno}/stock-adjustment
Path params:
Param name Param type Required Description
artno string yes Article number of product
Root params:
Param name Param type Required Description
quantity int yes Quantity
type string:enum(absolute, relative) yes Possible values: absolute, relative
warehouse_id string yes Alias of warehouse
reason int yes(if type=relative) Change reason code
Request Examples:

Changing quantity absolutely

PATCH
inventory/123/stock-adjustment

Request body

{
    "warehouse_id": "nw",
    "quantity": 77,
    "type": "absolute",
    "reason": 2
}

Changing quantity relatively (increasing)

PATCH
inventory/123/stock-adjustment

Request body

{
    "warehouse_id": "nw",
    "quantity": 7,
    "type": "relative",
    "reason": 2
}

Changing quantity relatively (decreasing)

PATCH
inventory/123/stock-adjustment

Request body

{
    "warehouse_id": "nw",
    "quantity": "-7",
    "type": "relative",
    "reason": 2
}
Response example: 
{
    "error": {
        "error_code": 0,
        "error_messages": []
    },
    "data": {
        'artno': 123,
        'old_quantity': 456,
        'new_quantity': 449
    }
}

Getting product data

GET
inventory/{artno}
Path params:
Param name Param type Required Description
artno string yes Product's article number
Query params:
Param name Param type Required Description
warehouse_id string yes Warehouse alias
Request Examples:

Getting product data (currently only about packages)

GET
inventory/123?warehouse_id=nw
Response example: 
{
    "error": {
        "error_code": 0,
        "error_messages": []
    },
    "data": {
        "artno": 123,
        "packages": [
            {
                "number": 1,
                "quantity": 1,
                "volume": 35,
                "weight": 12,
            },
            ...
        ]
    }
}

Changing product data

Package data can be only clarified, mean values can be changed little.

PATCH
inventory/{artno}
Path params:
Param name Param type Required Description
artno string yes Product's article number
Request structure data in wsdl-like format:
Product (root element)
Param name Param type Required Description
warehouse_id string yes Warehouse alias
packages Package[] yes Packages data
Package
Param name Param type Required Description
number int yes Package number
quantity int yes Quantity of similar packages
weight numeric yes Weight of product in kilograms
volume numeric yes without height|width|length Total volume of package
height numeric yes without volume Package height
width numeric yes without volume Package width
length numeric yes without volume Package length
Request Examples:

Updating product data (currently only about packages)

PATCH
inventory/123

Request body

{
    "warehouse_id": "nw",
    "packages": [
        {
            "number": 1,
            "quantity": 1,
            "volume": 35,
            "weight": 12,
        },
        ...
    ]
}
Response example (will contain updated data): 
{
    "error": {
        "error_code": 0,
        "error_messages": []
    },
    "data": {
        "artno": 123,
        "packages": [
            {
                "number": 1,
                "quantity": 1,
                "volume": 35,
                "weight": 12,
            },
            ...
        ]
    }
}

dispatch

Creating new dispatch for outgoing order

POST
dispatch
Path params:

No path params

Updating dispatch for outgoing order

PATCH
dispatch/{dispatch_id}
Path params:
Param name Param type Required Description
dispatch_id string yes Dispatch id


Update request allow to add more packages, update existed packages, update dispatch header values.
This route will return an error for published dispatches.
To add package add it to "packages" property with a unique package_id;
No need to send previous packages;
If there is no such package id inside this dispatch - it will be added;

Dispatch with flag "draft" = true have to be published.
To publish draft dispatch - send PATCH request with property "draft" = false.
Also, send all data left to create a valid dispatch, if you didn't do it while picking.
Don't have to create draft dispatches everytime. By sending draft = false or ignoring this property will make dispatch route work as previously.
It's forbidden to switch published dispatches back to draft.
Root params
Param name Param type Required Description
warehouse_id string yes Warehouse alias
order_no string yes Order No.
order_type string:enum(SO, PRO, TO) yes Type of outgoing order
draft boolean no (default=false) Turn on/turn off the draft mode for a dispatch
transaction_id string yes Unique reference of shipment in your system
packages Package[] yes Packages data
products DispatchProduct[] yes Data about products in dispatch
Package
Param name Param type Required Description
package_id int yes Unique package id (within dispatch)
external_package_id string no Unique package id (globally)
weight float yes Total weight of package
volume float yes Total volume of package
picking_zones string[] no Warehouse picking location
products PackageProduct[] yes Information about products/products parts in package
PackageProduct
Param name Param type Required Description
line_no string yes Line number of related order line
artno string yes Artno of product in related order line
DispatchProduct
Param name Param type Required Description
line_no string yes Line number of related order line
artno string yes Artno of product in related order line
quantity int yes Quantity of product in dispatch
Response:

Response will contain data in the same structure that you send us, but it will be filled with some values from our side: to root node will be added next properties: dispatch_id, shipping_agent_code, tracking_code, dispatch_date, total_weight, total_volume, logtrade_consignment_id, labels_url_pdf, labels_url_web, haulier_id and products (data that can be get from api/inventory/{artno} api endpoint); to each package object will be added label_url property.
You can access this data anytime you want from GET api/dispatch/{dispatch_id} api endpoint

Request Examples:

Creating new dispatch

POST
dispatch

Request body

{
   "warehouse_id":"nw",
   "order_no":"FO123456",
   "transaction_id":"8723GYSFD52F32T",
   "order_type":"SO",
   "draft": true,
   "external_reference":null,
   "packages":[
      {
         "package_id":1,
         "external_package_id":123,
         "weight":34,
         "volume":2,
         "picking_zones": [
             "A"
         ],
         "products":[
            {
               "line_no":1000,
               "artno":"123-45",
               "label":"701203"
            }
         ]
      }
   ],
   "products":[
      {
         "line_no":1000,
         "artno":"123-45",
         "quantity":12
      }
   ]
}

Response body

{
   "error":{
      "error_code":0,
      "error_messages":[]
   },
   "data":{
      "order_no":"FO123456",
      "transaction_id":"8723GYSFD52F32T11",
      "order_type":"SO",
      "dispatch_id":123,
      "shipping_agent_code":"DHL",
      "tracking_code":1234567780,
      "dispatch_date":"2014-11-06",
      "total_weight":94,
      "total_volume":9,
      "haulier_id": 3,
      "draft": true,
      "logtrade_consignment_id":"12345",
      "labels_url_pdf":"http://logtrade/all-labels.pdf",
      "labels_url_web":"http://logtrade/web-version-path",
      "packages":[
         {
            "package_id":1,
            "external_package_id":123,
            "weight":34,
            "volume":2,
            "label_url":"http://trademax.se/label_url.pdf",
            "picking_zones": [
                "A"
            ],
            "products":[
               {
                  "line_no":1000,
                  "artno":"123-45"
               }
            ]
         }
      ],
      "products":[
         {
            "line_no":1000,
            "artno":"123-45",
            "quantity":12
         }
      ]
   }
}

Updating the dispatch

PATCH
dispatch/123

Request body

{
   "warehouse_id":"nw",
   "order_no":"FO123456",
   "transaction_id":"8723GYSFD52F32T",
   "order_type":"SO",
   "draft": true,
   "external_reference":null,
   "packages":[
      {
         "package_id":2,
         "external_package_id":124,
         "weight":16,
         "volume":0.4,
         "products":[
            {
               "line_no":1000,
               "artno":"123-45"
            },
            {
               "line_no":2000,
               "artno":"123-46"
            }
         ]
      }
   ],
   "products":[
      {
         "line_no":1000,
         "artno":"123-45",
         "quantity":12
      },
      {
         "line_no":2000,
         "artno":"123-46",
         "quantity":12
      }
   ]
}

Response body

{
   "error":{
      "error_code":0,
      "error_messages":[]
   },
   "data":{
      "order_no":"FO123456",
      "transaction_id":"8723GYSFD52F32T11",
      "order_type":"SO",
      "dispatch_id":123,
      "shipping_agent_code":"DHL",
      "tracking_code":1234567780,
      "dispatch_date":"2014-11-06",
      "total_weight":94,
      "total_volume":9,
      "haulier_id": 3,
      "draft": true,
      "logtrade_consignment_id":"12345",
      "labels_url_pdf":"http://logtrade/all-labels.pdf",
      "labels_url_web":"http://logtrade/web-version-path",
      "packages":[
         {
            "package_id":1,
            "external_package_id":123,
            "weight":34,
            "volume":2,
            "label_url":"http://trademax.se/label_url.pdf",
            "picking_zones": [
                "A"
            ],
            "products":[
               {
                  "line_no":1000,
                  "artno":"123-45"
               }
            ]
         },
         {
            "package_id":2,
            "external_package_id":124,
            "weight":16,
            "volume":0.4,
            "label_url":"http://trademax.se/label_url.pdf",
            "products":[
               {
                  "line_no":1000,
                  "artno":"123-45"
               },
               {
                  "line_no":2000,
                  "artno":"123-46"
               }
            ]
         }
      ],
      "products":[
         {
            "line_no":1000,
            "artno":"123-45",
            "quantity":12
         },
         {
            "line_no":1000,
            "artno":"123-46",
            "quantity":12
         }
      ]
   }
}

Getting dispatch data

GET
dispatch/{dispatch_id}
Path params:
Param name Param type Required Description
dispatch_id int yes Dispatch identifier generated by us within creating request
Request Examples:

Getting data about dispatch

GET
dispatch/123

Response body will be the same as in creating example

Creating new dispatch for outgoing order by vendor

POST
/vendor/dispatch
Path params:

No path params

Request structure data in wsdl-like format:
Root params
Param name Param type Required Description
order_no string yes Order No.
labels_quantity int yes Label Quantity
Response:

Response will contain data in the same structure that you send us, but it will be filled with some values from our side: to root node will be added next properties: dispatch_id, shipping_agent_code, tracking_code, dispatch_date, total_weight, total_volume, logtrade_consignment_id, labels_url_pdf, labels_url_web, haulier_id and products (data that can be get from api/inventory/{artno} api endpoint); to each package object will be added label_url property.
You can access this data anytime you want from GET api/dispatch/{dispatch_id} api endpoint

Request Examples:

Creating new dispatch

POST
dispatch

Request body

{
   "order_no":"FO123456",
   "labels_quantity": 2
}

Response body

{
    "error": {
        "code": 0,
        "error_messages": []
    },
    "data": {
        "vendor_id": "5432232",
        "dispatch_id": 390333,
        "order_no": "IO1036240",
        "order_type": "SO",
        "external_reference": null,
        "dispatch_date": "2018-06-04",
        "draft": true,
        "logtrade_consignment_id": "11246720",
        "labels_url_web": "http://distribution.logtrade.info/controltower/status.aspx?u=LTD8101189&e=a5874e5c&s=6615122964",
        "tracking_code": "6615122964",
        "shipping_agent_code": "DhlSweden_HomeDelivery",
        "haulier_id": 7,
        "labels_url_pdf": "http://api.trademax.se/get-dispatch-label/b99a778aa7a444424e9b6ca8c8a00d70a1ad69a8",
        "total_weight": 7.8799999999999999,
        "total_volume": 0.47999999999999998,
        "packages": [
            {
                "package_id": 1,
                "external_package_id": 1,
                "weight": 3.9399999999999999,
                "volume": 0.23999999999999999,
                "label_url": "http://api.trademax.se/get-dispatch-package-label/504ffd03ff45d418d2822ab6703b17c54c4ba104",
                "label_sscc": "00373400306205750407",
                "picking_zones": [
                    "H"
                ],
                "products": [
                    {
                        "line_no": 10000,
                        "artno": "585491"
                    },
                    {
                        "line_no": 20000,
                        "artno": "120535"
                    }
                ]
            },
            {
                "package_id": 2,
                "external_package_id": 2,
                "weight": 3.9399999999999999,
                "volume": 0.23999999999999999,
                "label_url": "http://api.trademax.se/get-dispatch-package-label/a413c3f5a017dc96ff47ca9f6d6315bfe704017c",
                "label_sscc": "00373400306205750414",
                "picking_zones": [
                    "H"
                ],
                "products": [
                    {
                        "line_no": 30000,
                        "artno": "PK"
                    }
                ]
            }
        ],
        "products": [
            {
                "artno": "585491",
                "line_no": 10000,
                "quantity": 1
            },
            {
                "artno": "120535",
                "line_no": 20000,
                "quantity": 1
            },
            {
                "artno": "PK",
                "line_no": 30000,
                "quantity": 1
            }
        ]
    }
}

Deleting draft dispatch

DELETE
dispatch/{dispatch_id}
Path params:
Param name Param type Required Description
dispatch_id string yes Dispatch id

To delete draft dispatch send delete request with dispatch id
This route will return an error for published dispatches.

receipt

Reporting receive of goods

POST
receipt
Path params:

No path params

Request structure data in wsdl-like format:
Root params
Param name Param type Required Description
warehouse_id string yes Warehouse alias
order_no string yes Order No.
transaction_id string yes Unique reference of receipt in your system
order_type string:enum(PO, SRO, TO) yes Type of incoming order
received_date date yes Date when goods were received. Format: [YYYY-MM-DD]
products Product[] yes List of products that arrive
Product
Param name Param type Required Description
line_no int yes Line number of incoming order
artno string yes Article number
quantity int yes Quantity of received goods
vendor_shipment_no string no Vendor shipment number
Response:

Response will contain same data that you send us but with some extra fields from our side.

Request Examples:

Creating new receipt

POST
receipt

Request body

{
    "order_no": "IO12345",
    "transaction_id":"8723GYSFD52F32T123",
    "order_type":"PO",
    "warehouse_id": "NW",
    "received_date": "2015-07-26",
    "products": [
        {
            "line_no": 1000,
            "artno": "113-11",
            "quantity": 3,
            "vendor_shipment_no": "34435673456"
        },
        {
            "line_no": 2000,
            "artno": "44572",
            "quantity": 2
        },
        {
            "line_no": 3000,
            "artno": "4456-77",
            "quantity": 2
        }
    ]
}

Response body

{
    "error": {
        "error_code": 0,
        "error_messages": []
    },
    "data": {
        "receipt_id": 123,
        "order_no": "IO12345",
        "transaction_id":"8723GYSFD52F32T",
        "order_type":"PO",
        "warehouse_id": "NW",
        "received_date": "2015-07-26",
        "products": [
            {
                "line_no": 1000,
                "artno": "113-11",
                "quantity": 3,
                "vendor_shipment_no": "34435673456"
            },
            {
                "line_no": 2000,
                "artno": "44572",
                "quantity": 2
            },
            {
                "line_no": 3000,
                "artno": "4456-77",
                "quantity": 2
            }
        ]
    }

}

Getting receipt data

GET
receipt/{receipt_id}
Path params:
Param name Param type Required Description
receipt_id int yes Receipt identifier generated by us within creating request
Request Examples:

Getting data about dispatch

GET
receipt/123

Response body will be the same as in creating example

order

Locking order lines

PATCH
order/outgoing/{order_no}
Path params:
Param name Param type Required Description
order_no string yes Order number
Request structure data in wsdl-like format:
Root params
Param name Param type Required Description
warehouse_id string yes Warehouse alias
lines Line[] yes List of lines
Line
Param name Param type Required Description
line_no int yes Line number of outgoing order
processing int yes 1 for set status "processing", 0 to release
Request Examples:

Locking order lines:

PATCH
order/outgoing/IO12345

Request body

{
    "warehouse_id": "nw",
    "lines": [
        {
            "line_no": 1000,
            "processing": 1
        },
        {
            "line_no": 2000,
            "processing": 0
        }
    ]
}

Response body

{
    "warehouse_id": "nw",
    "lines": [
        {
            "line_no": 1000,
            "processing": 1
        },
        {
            "line_no": 2000,
            "processing": 0
        }
    ]
}

Getting data about processing status of order

GET
order/outgoing/{order_no}
Path params:
Param name Param type Required Description
order_no string yes Number of outgoing order
Query params:
Param name Param type Required Description
warehouse_id string yes Warehouse alias
Request Examples:

Getting data about order lines status

GET
order/outgoing/IO12345?warehouse_id=nw

Response body will be the same as in creating example

Latest changes

2015-07-27
  • Inventory resource now has article number of product as identifier (instead of warehouse code)
  • Stock adjustment got new url (added suffix 'stock-adjustment')
  • Support requests in json format
2015-08-05
  • Added dispatch endpoint
2015-08-13
  • Added fields logtrade_consignment_id, labels_url_pdf, labels_url_web to GET api/dispatch/{dispatch_id}
  • Added receipt endpoint
2015-09-11
  • Added orders (outgoing) endpoint - ability to lock order lines while they are in processing at warehouse
2015-09-16
  • Added haulier_id to dispatch response
2018-04-05
  • Added vendor dispatch endpoint
2020-01-16
  • Added dispatch delete endpoint
  • Added dispatch update endpoint