API Documentation

The ViaChina API is based on RESTful principles. It uses standard HTTP verbs and URLs to grant access to it's functionality. Requests can be made as www-form-url-encoded or as JSON, all responses will be in the JSON format.

Available objects

In order to use ViaChina it is important to understand the underlying architecture. The system relevant to API customers consists of orders, line items (products) and addresses. Each order has one shipping address and several line items. In order to reduce complexity we created a possibility to create orders, it's address and line items with one API request. This is described in detail below. The current API Version for now only supports creating Order (Parcel) Labels. You will still need to provide the OrderFile, as described in the ViaChina Integrations SOP, to [email protected].

Production and Staging Environments

ViaChina provides completely separate staging and production environments. This way, you can test your implementations against a production-like system without fear of real-world consequences. The URLs for these systems are as follows:

Environment	URL
Staging	http://api.staging.viachina.com
Production	https://api.viachina.com

Whenever this document refers to an URL like https://api.viachina.com, you can substitute the host for the staging host for testing purposes.

Authentication

In order to secure your data, ViaChina requires API users to authenticate before they can access any information. This is done by supplying an API access token in the HTTP header with every request that you make.

Be sure to keep access tokens secret. With great power comes great responsibility!

Authorization Header

To gain API access you must supply an HTTP header with the name “Authorization” and the contents “Token ”, like so:

curl -H “Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f”

Status Codes

The ViaChina API uses standardised HTTP response codes the inform the caller about the status of any requests.

These are the most common codes you’ll get to see:

Code	Text	Description
200	OK	Happy times!
201	Created	You just created a new resource
204	No Content	The update or delete operation you just ran was successful
400	Bad request	The request you made is missing required parameters and cannot be executed
401	Unauthorized	You’re not allowed to access this resource
404	Not found	You probably tried to access a resource that doesn’t exist
422	Unprocessable Entity	The validation of the resource you wanted to create or update failed. The JSON in the body will contain a detailed error description
500	Internal Server Error	Yikes! This is pretty bad and might be our fault. If you encounter one of these, we are automatically informed, but please contact us with some in-depth infos.

Missing Parameters (HTTP 400)

Create and update request have certain requirements regarding the parameters you must submit in order the execute the request. A line item change request for example needs the line item information as parameter. If you do not supply this, you will get the following error:

HTTP/1.1 400 Bad Request
{
  “error_description”: “A required parameter for this request was not supplied”,
  “missing_parameters”: [“line_item”]
}

Validation errors (HTTP 422)

If the creation or alteration of a resource failed because some validation criteria were not met, you will get a HTTP response with the status code 422 which contains error information just like in the following example:

HTTP/1.1 422 Unprocessable Entity
{
  “errors”: {
    “description”: [“is too short (minimum is 1 characters)”],
    “price_in_eur”: [“can’t be blank”]
  }
}

Orders

Attributes

API control attributes

Name	Settable/Readable	Type	Description
pdf_label_paper_size	request	String	Can be either 'A4' for large sheets or 'A6' for thermal printer labels

Main order attributes

Name	Settable/Readable	Type	Description
id	response	Integer	The ID of the order
address_attributes	request	Hash	Data for address, see address for more info
line_items_attributes	request	Array of Hashes	Data for the line items, see line items for more info
service	response/request	String	see "Available Services"
domestic_carrier	response/request	String	see "Available Domestic Carriers"
bag	response/request	Integer	Positive integer, starting at 1
pallet	response/request	Integer	Positive integer, starting at 1
state	response/request	String	Must be one of "pristine", "waiting_for_duty_calculation"
tracking_code	response/request	String	The PostNL bar code
client_reference	response/request	String	Your order number
vc_reference	response	String	The VC reference of the order
weight	response	Float	The total weight of all line items
subtotal_in_eur	response	Integer	Sub total amount in EUR cents
total_in_eur	response	Integer	Total amount in EUR cents
insurance_costs_in_eur	response/request	Integer	Costs for insurance in EUR cents
shipping_costs_international_in_eur	response	Integer	Shipping costs for the international leg in EUR cents
shipping_costs_domestic_in_eur	response	Integer	Shipping costs for the domestic leg in EUR cents
estimated_vat_in_eur	response	Integer	Estimated VAT after import in EUR cents
estimated_duties_in_eur	response	Integer	Estimated price of duties after import in EUR cents
pdf_label_data	response	String	Base64-encoded PDF representation of DPD's label. Only returned once on creation.

Attributes for address

Name	Settable/Readable	Type	Description
name	response/request	String	Name of the addressee
company	response/request	String (optional)	Company name of the addressee
street1	response/request	String	First line of the address
street2	response/request	String (optional)	Second line of the address
zip_code	response/request	String	Postal code
town	response/request	String	City or Town
country_code	response/request	String	2 digit ISO country code
state_or_province	response/request	String (optional)	The province or state the addressee resides in

Attributes for line items

Name	Settable/Readable	Type	Description
original_description	response/request	String	Description of the line item
kind	response/request	String	Type of the line item, like Clothing, Electronics
url	response/request	String (optional)	URL to the product in the web shop
hs_code	response/request	String (optional, depending on service)	The HS code of the item, must be provided for DDP services, must be 10 digits long
qty	response/request	Integer	Number of items purchased, must be positive integer
weight	response/request	Float	Weight of the item in kg
price_in_eur	response/request	Integer	Price per unit in EUR cents

Available Services

Service	Description
DDP2_R	Under 2 Kg, Registered (tracked), Duties Paid
DDP2_NR	Under 2 Kg, Non-Registered (not-tracked), Duties Paid
DDP31_R	Between 0 and 30 Kg, Registered (tracked), Duties Paid
DDU_R	Under 2 Kg, Registered (tracked), Duties Unpaid
DDU_NR	Under 2 Kg, Non-Registered (not-tracked), Duties Unpaid

Available Domestic Carriers

Carrier
PostNL
DPD
Deutsche Post
DHL

Create Address Label

To create an Address label you need to send an HTTP Post request to https://api.viachina.com/v1/orders. Please note that in this case we ourselves have to call several APIs, thus request run time might be in the region of 1s to 2s, while all other API calls are usually answered well under 100ms.

In the response you will receive Base64-encoded PDF representation in the field "pdf_label_data". This will allow you to create the Label for the order. Please note that you will also receive the Tracking Code in the response. This Tracking Code must be used in the OrderFile to the right corresponding order.

Examples

Creating an order, getting back a label

$ curl -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X POST \
  -d "pdf_label_paper_size=A4&\
  order[client_reference]=ABCDEFG1234&\
  order[service]=DDP2&\
  order[bag]=12&\
  order[pallet]=38&\
  order[domestic_carrier]=DPD&\
  order[address_attributes][name]=Frank Gallikanokus&\
  order[address_attributes][street1]=183 Testing Avenue&\
  order[address_attributes][street2]=Appartment 32&\
  order[address_attributes][zip_code]=90210&\
  order[address_attributes][town]=Beverly Hills&\
  order[address_attributes][country_code]=US&\
  order[line_items_attributes][][original_description]=USB Flash drive&\
  order[line_items_attributes][][kind]=Computer Accesory&\
  order[line_items_attributes][][hs_code]=6208291010&\
  order[line_items_attributes][][price_in_eur]=2500&\
  order[line_items_attributes][][qty]=2&\
  order[line_items_attributes][][weight]=0.100" \
  https://api.viachina.com/v1/orders

Response

{
  "id":4,
  "client_id":1,
  "shipment_id":null,
  "service":"DDP2",
  "bag":"1",
  "pallet":"1",
  "domestic_carrier":"DPD", 
  "tracking_code":"RC777676679NL",
  "client_reference":"ABCDEFG1234",
  "vc_reference":"563A5D3E28",
  "weight":"0.200",
  "subtotal_in_eur":5000,
  "total_in_eur":5500,
  "insurance_costs_in_eur":null,
  "estimated_vat_in_eur":250,
  "estimated_duties_in_eur":250,
  "shipping_costs_international_in_eur":null,
  "shipping_costs_domestic_in_eur":null,
  "created_at":"2015-03-18T14:56:31.086+01:00",
  "updated_at":"2015-03-18T14:56:31.086+01:00",
  "pdf_label_data":"AAAA[…]"
}

Updating an Order

$ curl -H "Authorization: Bearer 4b00c2cbffba2d16d24dd8adf0e843e6b143b54dbf800ce7ef12d431927ef63f" \
  -X PATCH \
  -d "order[tracking_code]=RC777676679NL"
  https://api.viachina.com/v1/orders/124

Response

HTTP/1.1 204 No Content