Developers Documentation
Easy Logistic API integration
Introduction
In the following documentation you will find nocnoc’s fundamentals for order processing. In order to accomplish a successful integration, we highlight the most relevant technical and conceptual aspects that should be applied. Also, we include practical examples and key notes for a deeper understanding of the API.
Tecnical Requirements
- The protocol used is HTTPS
- All communications between Merchant and nocnoc receive and return JSON
- All communications should be made exclusively through registered IPs
Environments
You can have access to two different environments: Sandbox and Live.
Sandbox
Testing environment available for integration development. Simulates all requests available in the API.
URL: sandbox.nocnocgroup.com
Live
Product environment. Here, requests generate real orders for real customers.
URL: live.nocnocgroup.com
Authentication
Nocnoc uses API keys to allow access to the API. You can get your API key, sending an email to [email protected] .
Nocnoc expects for the API key to be included in all API requests to the server in a header that looks as follows:
X-Api-Key: MERCHANT_KEY
Localization
We allow error message localization. The default error language is en-US.
In case you want to change this, you have to send in the request, a header that looks as follows:
X-Lang: LANGUAGE_CODE
| Language Code | Meaning |
|---|---|
| es-AR | Spanish - Argentina |
| pt-BR | Portuguese - Brasil |
| es-PE | Spanish - Peru |
| en-US | English - United States |
Order
Quote Order
"Quote Order" function only gives information about taxes, shipping and handling costs for products that want to be shipped to an specific country.
curl -X POST 'https://URL/api/order/quote' \
-H 'content-type: application/json' \
-H 'x-api-key: MERCHANT_KEY' \
-H 'x-lang: LANGUAGE_CODE' \
-d '{
"products":
[
{
"name":"nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description":"Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"sku":"4807703",
"weight":700,
"dimension":{
"length":20,
"width":10,
"height":30
},
"amount_usd":57.55,
"subcategory_id":200,
"hs_code":"84713090000P",
"quantity":1
}
],
"customer":{
"full_name":"George Walker",
"country":"AR",
"tax_id":"20-01234567-5"
},
"address":{
"zipcode":"1009",
"country":"AR"
},
"pickup":{
"country":"CN"
}
}'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://URL/api/order/quote",
"method": "POST",
"dataType": "json",
"headers": {
"content-type": "application/json",
"x-api-key": "MERCHANT_KEY",
"x-lang": "en-US"
},
"data": {
"products":
[
{
"name":"nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description":"Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"sku":"4807703",
"weight":700,
"dimension":{
"length":20,
"width":10,
"height":30
},
"amount_usd":57.55,
"subcategory_id":200,
"hs_code":"84713090000P",
"quantity":1
}
],
"customer":{
"full_name":"George Walker",
"country":"AR",
"tax_id":"20-01234567-5"
},
"address":{
"zipcode":"1009",
"country":"AR"
}
},
"pickup":{
"country":"CN"
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
The above command returns JSON structured like this:
{
"total_weight": 700,
"total_volume": 6000,
"amount_usd": 57.55,
"shipping_usd": 16,
"tax_handling_usd": 46.04,
"total_amount_usd": 119.59,
"address": {
"zipcode":"1009",
"country": "AR"
},
"pickup": {
"country": "CN"
},
"customer": {
"full_name": "George Walker",
"tax_id": "20-01234567-5",
"country": "AR"
},
"products": [
{
"name": "nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description": "Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"hs_code": "84713090000P",
"subcategory_id": 200,
"subcategory_name": "Tablets",
"sku": "4807703",
"weight": 700,
"dimension": {
"height": 30,
"length": 20,
"width": 10
},
"amount_usd": 57.55,
"tax_handling_usd": 46.04,
"total_amount_usd": 103.59,
"quantity": 1
}
]
}
HTTP Request
POST - https://URL/api/order/quote
Query Parameters
| Parameter | Type | Status | Description |
|---|---|---|---|
| address.country | String (max. length 2 chars) | Required | Country, where the products want to be shipped, in ISO 3166-1 alpha-2 codes |
| address.zipcode | String (max. length 45 chars) | Required | Address's zip code |
| pickup.country | String (max. length 2 chars) | Optional | Address's country in ISO 3166-1 alpha-2 codes. Required if pick up address is different to default one |
| products.name | String (max. length 100 chars) | Required | Name of the product |
| products.description | String (max. length 255 chars) | Required | Detailed description of the product |
| products.sku | String (max. length 20 chars) | Required | Merchant's product SKU |
| products.weight | Integer | Required | Product's shipping box weight in grams (g) |
| products.dimension.height | Integer | Required | Product's shipping box height in centimeter (cm) |
| products.dimension.length | Integer | Required | Product's shipping box length in centimeter (cm) |
| products.dimension.width | Integer | Required | Product's shipping box width in centimeter (cm) |
| products.amount_usd | Decimal (max. 2 decimal numbers) | Required | Product's amount in USD (unit FOB amount) |
| products.subcategory_id | Integer | Required | Product's subcategory identification. Find the list of subcategories in the "Categories" section |
| products.hs_code | String (max. length 20 chars) | Optional | Product's Harmonized System code, without dots (.), only characters. |
| products.quantity | Integer | Required | Product's quantity |
| customer.full_name | String (max. length 45 chars) | Required | Customer's names and surnames |
| customer.country | String (max. length 2 chars) | Required | Customer's country in ISO 3166-1 alpha-2 codes |
| customer.tax_id | String (max. length 45 chars) | Required | Customer's tax identification number (needed for local customs) |
Create Order
This function gives all the necessary data for creating new orders. By providing accurate information to nocnoc when you place a new order, nocnoc will be able to calculate the exact quotation related to shipping costs, local taxes and handling costs.
The "Create Order" request is composed of products, a customer and an address. In the table below, you can see the list of parameters included in each object.
Pick up date and address could be specified in each product. In case an address is not specified, the default pick up address arranged with nocnoc will be assigned automatically.
curl -X PUT 'https://URL/api/order' \
-H 'content-type: application/json' \
-H 'x-api-key: MERCHANT_KEY' \
-H 'x-lang: LANGUAGE_CODE' \
-d '{
"merchant_invoice_id":"200",
"notification_url":"https://www.merchantsite.com/api",
"products":
[
{
"name":"nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description":"Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"sku":"4807703",
"weight":700,
"dimension":{
"length":20,
"width":10,
"height":30
},
"amount_usd":57.55,
"subcategory_id":200,
"hs_code":"84713090000P",
"quantity":1,
"native_description":"个人平板电脑"
},{
"name":"nocnoc - Standard Drone with camera - White",
"description":"Standard quadcopter include HD-4K action camera that capture shake-free videos. Integrated touch display in remote controller.",
"sku":"123409",
"weight":3000,
"dimension":{
"length":200,
"width":100,
"height":300
},
"amount_usd":100.8,
"subcategory_id":600,
"hs_code":"85258029919J",
"quantity":2
}
],
"pickup":{
"date":"2017-04-15",
"contact_name":"Benjamin Ortiz",
"contact_phone":"+86 123 4567 8900",
"street":"8750 Main Street",
"street_2":"2nd Floor",
"zipcode":"C1234",
"region":"Guangdong",
"city":"Shenzhen",
"country":"CN",
"packages":1
},
"customer":{
"full_name":"George Walker",
"country":"AR",
"email":"[email protected]",
"tax_id":"20-01234567-5",
"personal_id":"1234567"
},
"address":{
"recipient_name":"John Walker",
"phone":"+541100000000",
"street":"San Martin 1234",
"street_2":"Apartment 2B",
"zipcode":"C1104AKD",
"region":"CABA",
"city":"Buenos Aires",
"country":"AR"
}
}'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://URL/api/order",
"method": "PUT",
"dataType": "json",
"headers": {
"content-type": "application/json",
"x-api-key": "MERCHANT_KEY",
"x-lang": "es-AR"
},
"data": {
"merchant_invoice_id":"200",
"notification_url":"https://www.merchantsite.com/api",
"expiration_date":"2017-04-10",
"products":
[
{
"name":"nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description":"Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"sku":"4807703",
"weight":700,
"dimension":{
"length":20,
"width":10,
"height":30
},
"amount_usd":57.55,
"subcategory_id":200,
"hs_code":"84713090000P",
"quantity":1,
"native_description":"个人平板电脑"
},{
"name":"nocnoc - Standard Drone with camera - White",
"description":"Standard quadcopter include HD-4K action camera that capture shake-free videos. Integrated touch display in remote controller.",
"sku":"123409",
"weight":3000,
"dimension":{
"length":200,
"width":100,
"height":300
},
"amount_usd":100.8,
"subcategory_id":600,
"hs_code":"85258029919J",
"quantity":2
}
],
"pickup":{
"date":"2017-04-15",
"contact_name":"Benjamin Ortiz",
"contact_phone":"+86 123 4567 8900",
"street":"8750 Main Street",
"street_2":"2nd Floor",
"zipcode":"C1234",
"region":"Guangdong",
"city":"Shenzhen",
"country":"CN",
"packages":2
},
"customer":{
"full_name":"George Walker",
"country":"AR",
"email":"[email protected]",
"tax_id":"20-01234567-5",
"personal_id":"1234567"
},
"address":{
"recipient_name":"John Walker",
"phone":"+541100000000",
"street":"San Martin 1234",
"street_2":"Apartment 2B",
"zipcode":"C1104AKD",
"region":"CABA",
"city":"Buenos Aires",
"country":"AR"
}
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
The above command returns JSON structured like this:
{
"id": 10000001,
"merchant_invoice_id": "200",
"tracking_id":"NC10000001",
"notification_url":"https://www.merchantsite.com/api",
"label_url":"https://nocnocgroup.com/labelurn",
"created_at":"2017-04-08 10:00:00",
"expiration_date":"2017-04-10",
"status": "created",
"estimated_time_arrival": "2017-05-31",
"total_weight": 6700,
"total_volume": 12006000,
"amount_usd": 259.15,
"shipping_usd": 16,
"tax_handling_usd": 117.14,
"total_amount_usd": 392.29,
"total_packages": 2,
"pickup":{
"date":"2017-04-15",
"contact_name":"Benjamin Ortiz",
"contact_phone":"+86 123 4567 8900",
"street":"8750 Main Street",
"street_2":"2nd Floor",
"zipcode":"C1234",
"region":"Guangdong",
"city":"Shenzhen",
"country":"CN",
},
"customer": {
"full_name": "George Walker",
"personal_id": "1234567",
"tax_id": "20-01234567-5",
"country": "AR",
"email": "[email protected]"
},
"address": {
"recipient_name": "John Walker",
"phone": "+541100000000",
"street": "San Martin 1234",
"street_2": "Apartment 2B",
"zipcode": "C1104AKD",
"region": "CABA",
"city": "Buenos Aires",
"country": "AR"
},
"products":
[
{
"name": "nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description": "Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"hs_code": "84713090000P",
"subcategory_id":200,
"subcategory_name":"Tablets",
"sku": "4807703",
"weight": 700,
"dimension": {
"height": 30,
"length": 20,
"width": 10
},
"amount_usd": 57.55,
"tax_handling_usd": 6.62,
"total_amount_usd": 64.17,
"quantity": 1,
"native_description":"个人平板电脑"
},
{
"name": "nocnoc - Standard Drone with camera - White",
"description": "Standard quadcopter include HD-4K action camera that capture shake-free videos. Integrated touch display in remote controller.",
"hs_code": "85258029919J",
"subcategory_id":600,
"subcategory_name":"R/C Airplanes & Quadcopters",
"sku": "123409",
"weight": 3000,
"dimension": {
"height": 300,
"length": 200,
"width": 100
},
"amount_usd": 100.8,
"tax_handling_usd": 55.26,
"total_amount_usd": 156.06,
"quantity": 2
}
]
}
HTTP Request
PUT - https://URL/api/order
Query Parameters
| Parameter | Type | Status | Description |
|---|---|---|---|
| merchant_invoice_id | String (max. length 20 chars) | Required | Order identification at the merchant site |
| notification_url | String (max. length 256 chars) | Optional | Merchant's URL, where tracking notifications will be send |
| expiration_date | Date | Optional | The date the order will expire if it is not placed |
| customer.full_name | String (max. length 45 chars) | Required | Customer's names and surnames |
| customer.country | String (max. length 2 chars) | Required | Customer's country in ISO 3166-1 alpha-2 codes |
| customer.email | String (max. length 100 chars) | Required | Customer's email |
| customer.tax_id | String (max. length 45 chars) | Required | Customer's tax identification number (needed for local customs) |
| customer.personal_id | String (max. length 20 chars) | Optional | Customer's personal identification number |
| address.recipient_name | String (max. length 45 chars) | Required | Name of the person that receives the order |
| address.phone | String (max. length 45 chars) | Required | Phone of the address where the order will be shipped |
| address.street | String (max. length 60 chars) | Required | Street and number |
| address.street_2 | String (max. length 60 chars) | Optional | Apartment, suite, unit, building, floor, etc |
| address.zipcode | String (max. length 45 chars) | Required | Address's zip code |
| address.region | String (max. length 45 chars) | Optional | Region where the street is located |
| address.city | String (max. length 45 chars) | Required | City where the street is located |
| address.country | String (max. length 2 chars) | Required | Address's country in ISO 3166-1 alpha-2 codes |
| products.name | String (max. length 100 chars) | Required | Name of the product |
| products.description | String (max. length 255 chars) | Required | Detailed description of the product |
| products.sku | String (max. length 20 chars) | Required | Merchant's product SKU |
| products.weight | Integer | Required | Product's shipping box weight in grams (g) |
| products.dimension.height | Integer | Required | Product's shipping box height in centimeter (cm) |
| products.dimension.length | Integer | Required | Product's shipping box length in centimeter (cm) |
| products.dimension.width | Integer | Required | Product's shipping box width in centimeter (cm) |
| products.amount_usd | Decimal (max. 2 decimal numbers) | Required | Product's amount in USD (unit FOB amount) |
| products.subcategory_id | Integer | Required | Product's subcategory identification. Find the list of subcategories in the "Categories" section |
| products.hs_code | String (max. length 20 chars) | Optional | Product's Harmonized System code, without dots (.), only characters. |
| products.quantity | Integer | Required | Product's quantity |
| products.native_description | String (max. length 255 chars) | Optional | Required for orders which origin is CN/HK. Detailed description of the product in its native language (e.g. chinese). |
| pickup.date | Date | Optional | Arranged date, when nocnoc will pick up the product from the pick up address |
| pickup.contact_name | String (max. length 45 chars) | Optional | Name of the person of reference at pick up time. Required if pick up address is different to default one |
| pickup.contact_phone | String (max. length 45 chars) | Optional | Phone of the person of reference at pickup time |
| pickup.street | String (max. length 60 chars) | Optional | Street and number of pick up place. Required if pick up address is different to default one |
| pickup.street_2 | String (max. length 60 chars) | Optional | Apartment, suite, unit, building, floor, etc |
| pickup.zipcode | String (max. length 45 chars) | Optional | Pick up address zip code. Required if pick up address is different to default one |
| pickup.region | String (max. length 45 chars) | Optional | Region where the street is located |
| pickup.city | String (max. length 45 chars) | Optional | City where the street of the pick up address is located. Required if pick up address is different to default one |
| pickup.country | String (max. length 2 chars) | Optional | Address's country in ISO 3166-1 alpha-2 codes. Required if pick up address is different to default one |
| pickup.packages | Integer | Optional | Amount of packages to pickup. By default is the same as "products.quantity" parameter. |
Place Order
The “Place Order” function returns an order confirmation. Once this function is executed, the transaction in place will be processed to be shipped.
curl -X POST "https://URL/api/order/ORDER_ID" \
-H 'x-api-key: MERCHANT_KEY' \
-H 'x-lang: LANGUAGE_CODE'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://URL/api/order/ORDER_ID",
"method": "POST",
"headers": {
"x-api-key": "MERCHANT_KEY",
"x-lang": "en-US"
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
The above command returns JSON structured like this:
{
"id": 10000001,
"merchant_invoice_id": "200",
"tracking_id":"NC10000001",
"notification_url":"https://www.merchantsite.com/api",
"label_url":"https://nocnocgroup.com/labelurn",
"created_at":"2017-04-08 10:00:00",
"expiration_date":"2017-04-10",
"status": "placed",
"estimated_time_arrival": "2017-05-31",
"total_weight": 6700,
"total_volume": 12006000,
"amount_usd": 259.15,
"shipping_usd": 16,
"tax_handling_usd": 117.14,
"total_amount_usd": 392.29,
"total_packages": 2,
"customer": {
"full_name": "George Walker",
"personal_id": "1234567",
"tax_id": "20-01234567-5",
"country": "AR",
"email": "[email protected]"
},
"address": {
"recipient_name": "John Walker",
"phone": "+541100000000",
"street": "San Martin 1234",
"street_2": "Apartment 2B",
"zipcode": "C1104AKD",
"region": "CABA",
"city": "Buenos Aires",
"country": "AR"
},
"products":
[
{
"name": "nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description": "Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"hs_code": "84713090000P",
"subcategory_id":200,
"subcategory_name":"Tablets",
"sku": "4807703",
"weight": 700,
"dimension": {
"height": 30,
"length": 20,
"width": 10
},
"pickup":{
"date":"2017-04-15",
"contact_name":"Benjamin Ortiz",
"contact_phone":"+86 123 4567 8900",
"street":"8750 Main Street",
"street_2":"2nd Floor",
"zipcode":"C1234",
"region":"Guangdong",
"city":"Shenzhen",
"country":"CN",
"packages":1
},
"amount_usd": 57.55,
"tax_handling_usd": 6.62,
"total_amount_usd": 64.17,
"quantity": 1,
"native_description":"个人平板电脑"
},
{
"name": "nocnoc - Standard Drone with camera - White",
"description": "Standard quadcopter include HD-4K action camera that capture shake-free videos. Integrated touch display in remote controller.",
"hs_code": "85258029919J",
"subcategory_id":600,
"subcategory_name":"R/C Airplanes & Quadcopters",
"sku": "123409",
"weight": 3000,
"dimension": {
"height": 300,
"length": 200,
"width": 100
},
"pickup":{
"date":"2017-04-16",
"contact_name":"Jessica Johnson",
"contact_phone":"+852 1234 5678",
"street":"5050 Alternative Street",
"street_2":"Apt. 101",
"zipcode":"9876",
"city":"City of Victoria",
"country":"HK",
"packages":1
},
"amount_usd": 100.8,
"tax_handling_usd": 55.26,
"total_amount_usd": 156.06,
"quantity": 2
}
]
}
HTTP Request
POST - https://URL/api/order/ORDER_ID
Cancel Order
The “Cancel Order” returns an order cancellation, which will disable a certain transaction.
Cancellations can be done before the order is in "picked_up" status.
curl -X DELETE "https://URL/api/order/ORDER_ID" \
-H 'x-api-key: MERCHANT_KEY' \
-H 'x-lang: LANGUAGE_CODE'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://URL/api/order/ORDER_ID",
"method": "DELETE",
"headers": {
"x-api-key": "MERCHANT_KEY",
"x-lang": "es-AR"
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
The above command returns JSON structured like this:
{
"id": 10000001,
"merchant_invoice_id": "200",
"tracking_id":"NC10000001",
"notification_url":"https://www.merchantsite.com/api",
"label_url":"https://nocnocgroup.com/labelurn",
"created_at":"2017-04-08 10:00:00",
"expiration_date":"2017-04-10",
"status": "cancelled",
"estimated_time_arrival": "2017-05-31",
"total_weight": 6700,
"total_volume": 12006000,
"amount_usd": 259.15,
"shipping_usd": 16,
"tax_handling_usd": 117.14,
"total_amount_usd": 392.29,
"total_packages": 2,
"customer": {
"full_name": "George Walker",
"personal_id": "1234567",
"tax_id": "20-01234567-5",
"country": "AR",
"email": "[email protected]"
},
"address": {
"recipient_name": "John Walker",
"phone": "+541100000000",
"street": "San Martin 1234",
"street_2": "Apartment 2B",
"zipcode": "C1104AKD",
"region": "CABA",
"city": "Buenos Aires",
"country": "AR"
},
"products":
[
{
"name": "nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description": "Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"hs_code": "84713090000P",
"subcategory_id":200,
"subcategory_name":"Tablets",
"sku": "4807703",
"weight": 700,
"dimension": {
"height": 30,
"length": 20,
"width": 10
},
"pickup":{
"date":"2017-04-15",
"contact_name":"Benjamin Ortiz",
"contact_phone":"+86 123 4567 8900",
"street":"8750 Main Street",
"street_2":"2nd Floor",
"zipcode":"C1234",
"region":"Guangdong",
"city":"Shenzhen",
"country":"CN",
"packages":1
},
"amount_usd": 57.55,
"tax_handling_usd": 6.62,
"total_amount_usd": 64.17,
"quantity": 1,
"native_description":"个人平板电脑"
},
{
"name": "nocnoc - Standard Drone with camera - White",
"description": "Standard quadcopter include HD-4K action camera that capture shake-free videos. Integrated touch display in remote controller.",
"hs_code": "85258029919J",
"subcategory_id":600,
"subcategory_name":"R/C Airplanes & Quadcopters",
"sku": "123409",
"weight": 3000,
"dimension": {
"height": 300,
"length": 200,
"width": 100
},
"pickup":{
"date":"2017-04-16",
"contact_name":"Jessica Johnson",
"contact_phone":"+852 1234 5678",
"street":"5050 Alternative Street",
"street_2":"Apt. 101",
"zipcode":"9876",
"city":"City of Victoria",
"country":"HK",
"packages":1
},
"amount_usd": 100.8,
"tax_handling_usd": 55.26,
"total_amount_usd": 156.06,
"quantity": 2
}
]
}
HTTP Request
DELETE - https://URL/api/order/ORDER_ID
Get Order
The “Get Order” function returns an updated status of a certain order.
curl -X GET "https://URL/api/order/ORDER_ID" \
-H 'x-api-key: MERCHANT_KEY' \
-H 'x-lang: LANGUAGE_CODE'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://URL/api/order/ORDER_ID",
"method": "GET",
"headers": {
"x-api-key": "MERCHANT_KEY",
"x-lang": "en-US"
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
The above command returns JSON structured like this:
{
"id": 10000001,
"merchant_invoice_id": "200",
"tracking_id":"NC10000001",
"notification_url":"https://www.merchantsite.com/api",
"label_url":"https://nocnocgroup.com/labelurn",
"created_at":"2017-04-08 10:00:00",
"expiration_date":"2017-04-10",
"status": "cancelled",
"description":"",
"date":"2017-04-20",
"estimated_time_arrival": "2017-05-31",
"total_weight": 6700,
"total_volume": 12006000,
"amount_usd": 259.15,
"shipping_usd": 16,
"tax_handling_usd": 117.14,
"total_amount_usd": 392.29,
"total_packages": 2,
"customer": {
"full_name": "George Walker",
"personal_id": "1234567",
"tax_id": "20-01234567-5",
"country": "AR",
"email": "[email protected]"
},
"address": {
"recipient_name": "John Walker",
"phone": "+541100000000",
"street": "San Martin 1234",
"street_2": "Apartment 2B",
"zipcode": "C1104AKD",
"region": "CABA",
"city": "Buenos Aires",
"country": "AR"
},
"products":
[
{
"name": "nocnoc - Tablet 5.5-inch with WiFi - 32gb - Black",
"description": "Personal tablet, with 5.5-inch retina display in a thin aluminum design that weighs a pound. Contains N9 chip, 8MP camera, HD camera, Touch ID, bluetooth, Wi-Fi, all-day battery life, and millions of apps on the store",
"hs_code": "84713090000P",
"subcategory_id":200,
"subcategory_name":"Tablets",
"sku": "4807703",
"weight": 700,
"dimension": {
"height": 30,
"length": 20,
"width": 10
},
"pickup":{
"date":"2017-04-15",
"contact_name":"Benjamin Ortiz",
"contact_phone":"+86 123 4567 8900",
"street":"8750 Main Street",
"street_2":"2nd Floor",
"zipcode":"C1234",
"region":"Guangdong",
"city":"Shenzhen",
"country":"CN",
"packages":1
},
"amount_usd": 57.55,
"tax_handling_usd": 6.62,
"total_amount_usd": 64.17,
"quantity": 1,
"native_description":"个人平板电脑"
},
{
"name": "nocnoc - Standard Drone with camera - White",
"description": "Standard quadcopter include HD-4K action camera that capture shake-free videos. Integrated touch display in remote controller.",
"hs_code": "85258029919J",
"subcategory_id":600,
"subcategory_name":"R/C Airplanes & Quadcopters",
"sku": "123409",
"weight": 3000,
"dimension": {
"height": 300,
"length": 200,
"width": 100
},
"pickup":{
"date":"2017-04-16",
"contact_name":"Jessica Johnson",
"contact_phone":"+852 1234 5678",
"street":"5050 Alternative Street",
"street_2":"Apt. 101",
"zipcode":"9876",
"city":"City of Victoria",
"country":"HK",
"packages":1
},
"amount_usd": 100.8,
"tax_handling_usd": 55.26,
"total_amount_usd": 156.06,
"quantity": 2
}
],
"historic":
[
{
"status":"arrived",
"description":"Buenos Aires, AR",
"date":"2017-04-14"
},
{
"status":"shipped",
"description":"City of Victoria, HK",
"date":"2017-04-11"
},
{
"status":"in_warehouse",
"description":"Shenzhen, CN",
"date":"2017-04-10"
},
{
"status":"picked_up",
"description":"Shenzhen, CN",
"date":"2017-04-10"
},
{
"status":"in_process",
"description":"",
"date":"2017-04-09"
},
{
"status":"placed",
"description":"",
"date":"2017-04-08"
},
{
"status":"created",
"description":"",
"date":"2017-04-08"
}
]
}
HTTP Request
GET - https://URL/api/order/ORDER_ID
Track Order
The “Track Order” function returns a detailed tracking status of a certain order. Tracking notifications that are sent to notification_url will have the same structure as shown below.
Go to "Order Status" section, to see the status dictionary.
curl -X POST "https://URL/api/order/tracking/TRACKING_ID" \
-H 'x-api-key: MERCHANT_KEY' \
-H 'x-lang: LANGUAGE_CODE'
var settings = {
"async": true,
"crossDomain": true,
"url": "https://URL/api/order/tracking/TRACKING_ID",
"method": "POST",
"headers": {
"x-api-key": "MERCHANT_KEY",
"x-lang": "es-AR"
}
};
$.ajax(settings).done(function (response) {
console.log(response);
});
The above command returns JSON structured like this:
{
"id":10000001,
"tracking_id":"NC10000001",
"estimated_time_arrival":"2017-04-22",
"status":"cleared_by_customs",
"description":"Buenos Aires, AR",
"date":"2017-04-20",
"historic":[
{
"status":"arrived",
"description":"Buenos Aires, AR",
"date":"2017-04-19 23:05:14"
},
{
"status":"shipped",
"description":"City of Victoria, HK",
"date":"2017-04-17 216:03:14"
},
{
"status":"in_warehouse",
"description":"Shenzhen, CN",
"date":"2017-04-16 13:05:44"
},
{
"status":"picked_up",
"description":"Shenzhen, CN",
"date":"2017-04-16 21:17:34"
},
{
"status":"in_process",
"description":"",
"date":"2017-04-15 02:41:33"
},
{
"status":"placed",
"description":"",
"date":"2017-04-14 15:05:24"
},
{
"status":"created",
"description":"",
"date":"2017-04-14 07:25:23"
}
]
}
HTTP Request
POST - https://URL/api/order/tracking/TRACKING_ID
Order Status
The status of the order, changes during the whole process. Nocnoc will notify you about those changes with a POST request to the url specified in the notification_url parameter.
The response to that request, should be OK (200), in case everything received was correct. The structure of the request we send is like the one you get in the "Tracking Status" function.
Nocnoc uses the following order status:
| Status | Meaning |
|---|---|
| created | The order was created, and quoted. In order to be shipped, it has to be placed first. |
| placed | The order has been placed. Pick up process starts. |
| in_process | The order is being processed before it can be picked up. |
| picked_up | The order was picked up by nocnoc. |
| in_warehouse | The order is in nocnoc’s warehouse prior to departure. |
| shipped | The order was shipped from an origin to a destination. |
| arrived | The order arrived at the destination. |
| cleared_by_customs | The order was cleared by customs. |
| address_delivery | The order is being delivered to the final destination. |
| delivery_failure | The delivery failed. The reason is given in the description of the status at "Track Order" function. |
| delivered | The order arrived to the final destination, and was received by the customer. |
| cancelled | The order was cancelled. |
| expired | The order has expired. Merchant did not placed it before "expiration_date" came. |
API Response
In this following list, you can find all parameters, that appear on our function's responses.
| Parameter | Type | Description |
|---|---|---|
| id | Integer | Order id (ORDER_ID) |
| merchant_invoice_id | String (max. length 20 chars) | Order identification at the merchant site |
| tracking_id | String (max. length 12 chars) | Order's tracking identification |
| notification_url | String (max. length 256 chars) | Merchant's URL, where tracking notifications will be send |
| created_at | Date | The time when the order was created |
| expiration_date | Date | The date the order will expire if it is not placed |
| label_url | String (max. length 256 chars) | Nocnoc's URL where you can get labels for each order's package |
| status | String (max. lenght 45) | Order actual status. Find the list of order status in the "Order Status" section |
| description | String (max. lenght 45) | Additional information about the current status |
| date | Date | Order actual status. Find the list of order status in the "Order Status" section |
| estimated_time_arrival | Date | The estimated time when the order will arrive |
| total_weight | Integer | Total weight of the order |
| total_volume | Integer | Total volume of the order |
| amount_usd | Decimal (max. 2 decimal numbers) | Order's amount in USD |
| shipping_usd | Decimal (max. 2 decimal numbers) | Order's shipping cost |
| tax_handling_usd | Decimal (max. 2 decimal numbers) | Amount paid by the order for tax and handling |
| total_amount_usd | Decimal (max. 2 decimal numbers) | Total amount of the order |
| total_packages | Integer | Order's amount of packages |
| historic | Array | Array that contains order's status changes |
| customer.full_name | String (max. length 45 chars) | Customer's names and surnames |
| customer.country | String (max. length 2 chars) | Customer's country in ISO 3166-1 alpha-2 codes |
| customer.email | String (max. length 100 chars) | Customer's email |
| customer.tax_id | String (max. length 45 chars) | Customer's tax identification number (needed for local customs) |
| customer.personal_id | String (max. length 20 chars) | Customer's personal identification number |
| address.recipient_name | String (max. length 45 chars) | Name of the person that receives the order |
| address.phone | String (max. length 45 chars) | Phone of the address where the order will be shipped |
| address.street | String (max. length 60 chars) | Street and number |
| address.street_2 | String (max. length 60 chars) | Apartment, suite, unit, building, floor, etc |
| address.zipcode | String (max. length 45 chars) | Address's zip code |
| address.region | String (max. length 45 chars) | Region where the street is located |
| address.city | String (max. length 45 chars) | City where the street is located |
| address.country | String (max. length 2 chars) | Address's country in ISO 3166-1 alpha-2 codes |
| products.name | String (max. length 100 chars) | Name of the product |
| products.description | String (max. length 255 chars) | Detailed description of the product |
| products.hs_code | String (max. length 20 chars) | Product's Harmonized System code, without dots (.), only characters. |
| products.subcategory_id | Integer | Product's subcategory identification. Find the list of subcategories in the "Categories" section |
| products.subcategory_name | Integer | Product's subcategory name. Find the list of subcategories in the "Categories" section |
| products.sku | String (max. length 20 chars) | Merchant's product SKU |
| products.weight | Integer | Product's shipping box weight in grams (g) |
| products.dimension.height | Integer | Product's shipping box height in centimeter (cm) |
| products.dimension.length | Integer | Product's shipping box length in centimeter (cm) |
| products.dimension.width | Integer | Product's shipping box width in centimeter (cm) |
| products.pickup.date | Date | Arranged date, when nocnoc will pick up the product from the pick up address |
| products.pickup.contact_name | String (max. length 45 chars) | Name of the person of reference at pick up time |
| products.pickup.contact_phone | String (max. length 45 chars) | Phone of the person of reference at pickup time |
| products.pickup.street | String (max. length 60 chars) | Street and number of pick up place |
| products.pickup.street_2 | String (max. length 60 chars) | Apartment, suite, unit, building, floor, etc |
| products.pickup.zipcode | String (max. length 45 chars) | Pick up address zip code |
| products.pickup.region | String (max. length 45 chars) | Region where the street is located |
| products.pickup.city | String (max. length 45 chars) | City where the street of the pick up address is located |
| products.pickup.country | String (max. length 2 chars) | Address's country in ISO 3166-1 alpha-2 codes |
| products.pickup.packages | Integer | Amount of packages to pickup |
| products.amount_usd | Decimal (max. 2 decimal numbers) | Product's amount in USD (unit FOB amount) |
| products.tax_handling_usd | Decimal (max. 2 decimal numbers) | Amount paid by product for tax and handling |
| products.total_amount_usd | Decimal (max. 2 decimal numbers) | Total amount of the product |
| products.quantity | Integer | Product's quantity |
| products.native_description | String (max. length 255 chars) | Detailed description of the product in its native language (e.g. chinese). |
Categories
To specify the subcategory_id of each product, look at the list and choose the id of the subcategory that adjusts better:
| Id | Category | Subcategory |
|---|---|---|
Consumer Electronics |
||
| 100 | Internet & Media Streamers | |
| 101 | Smart Devices | |
| 102 | Headphones & Accesories | |
| 103 | Bluetooth Devices | |
| 104 | Amplifiers | |
| 105 | Memory Cards | |
| 106 | Card Readers | |
| 107 | USB Flash Drives | |
| 108 | Projectors & Accesories | |
| 109 | TV Receivers & Accesories | |
| 110 | Portable Audio & Video | |
| 111 | Audio & Video Cables | |
| 112 | A/V Adapters & Converters | |
| 113 | USB Accesories | |
| 114 | Handheld GPS | |
| 115 | Remote Controllers | |
| 116 | Speakers | |
| 117 | Cameras, Photo & Video | |
| 118 | Video Games | |
| 119 | Other Consumer Electronics | |
| 120 | Smart Watches | |
| 121 | Video Game Console | |
| 122 | Robot Vacuum | |
| 123 | Smart TV | |
| 124 | Smart Speakers | |
| 125 | Smart Lock | |
| 126 | Bluetooth Locators | |
| 127 | DashCam | |
PCs / Tablets & Networking |
||
| 200 | Tablets | |
| 201 | Cables & Adapters | |
| 202 | Networking | |
| 203 | HDD & Enclosures | |
| 204 | Keyboards | |
| 205 | Tablet Accesories | |
| 206 | Hardware Parts | |
| 207 | USB Hubs & Switches | |
| 208 | Power Adapters | |
| 209 | Cases | |
| 210 | Mouse | |
| 211 | USB Gadgets | |
| 212 | Other Accesories | |
| 213 | Scanners | |
| 214 | Presenters | |
| 215 | Mounts & Stands | |
| 216 | Microphone | |
| 217 | Hardware & Replacement Parts | |
| 218 | Bags & Pouches | |
| 219 | Printers | |
| 220 | Printer Supplies | |
| 221 | Screen Protectors | |
| 222 | Netbook & Laptops | |
| 223 | iPad Accesories | |
| 224 | CD & DVD Drives | |
| 225 | PC Game Controllers | |
| 226 | Cooling Gear | |
| 227 | Mouse Pads | |
| 228 | Modems & Routers | |
| 229 | Cable Management | |
| 230 | Motherboards | |
| 231 | CPU | |
| 232 | Monitors | |
Electrical & Tools |
||
| 300 | Arduino & SCM Supplies | |
| 301 | 3D Printer & Supplies | |
| 302 | Walkie Talkies | |
| 303 | Walkie Talkies Supplies | |
| 304 | Measurement & Analysis Instruments | |
| 305 | Batteries | |
| 306 | Chargers (Electrical & Tools) | |
| 307 | DIY Parts & Components | |
| 308 | Plugs & Sockets | |
| 309 | Switches & Adapters | |
| 310 | Gadgets | |
| 311 | Hand Tools | |
| 312 | Clock, Thermometer & Hygrometer | |
| 313 | Microscop | |
Cellphones & Accesories |
||
| 400 | Cellphones | |
| 401 | Cases & Protectors | |
| 402 | Cables | |
| 403 | Adapters & Converters | |
| 404 | Batteries | |
| 405 | DIY Parts & Tools | |
| 406 | Gadgets | |
| 407 | Mounts & Holders | |
| 408 | Stylus Touch Gloves | |
| 409 | iPhone Accesories | |
| 410 | Samsung Accesories | |
| 411 | Chargers (Cellphones & Accesories) | |
Car Accesories |
||
| 500 | Motorcycle Gadgets | |
| 501 | Car GPS | |
| 502 | Car Audio Systems | |
| 503 | Car Care | |
| 504 | Exterior Accesories | |
| 505 | Interior Accesories | |
| 506 | Car Alarm & Security | |
| 507 | Vehicle Tracking Systems | |
| 508 | Diagnostic Tools & Equipment | |
| 509 | Gadgets & Auto Parts | |
| 510 | Car Video Systems | |
| 511 | Car Lights | |
| 512 | Security Cameras | |
Hobbies & Toys |
||
| 600 | R/C Airplanes & Quadcopters | |
| 601 | Cosplay & Costumes | |
| 602 | R/C Toys | |
| 603 | Toys for All Ages | |
| 604 | Gifts | |
| 605 | Lighters | |
| 606 | Music & Performance | |
| 607 | Smoking Accesories | |
| 608 | Anime & Movie Figures | |
| 609 | Kung Fu & Martial Arts | |
| 610 | Flags | |
| 611 | BB Guns & Accesories | |
| 612 | Holidays / Events Gadgets | |
| 613 | Keychains | |
| 614 | Dolls & Stuffed Toys | |
| 615 | Gadget Toys | |
| 616 | Music | |
| 617 | Art | |
| 618 | Books | |
| 619 | Pet Toys | |
| 620 | Miniatures and Collectibles | |
| 621 | Funkos | |
| 622 | Wooden Toys | |
Lights & Lighting |
||
| 700 | Indoor Lightings | |
| 701 | Flashlights | |
| 702 | LED Gadgets | |
| 703 | Bulbs and Strips | |
| 704 | Car LED Bulbs | |
| 705 | Holiday & Stage Lights | |
| 706 | Outdoor Lightings | |
| 707 | Brand Smart Lighting | |
Home & Office |
||
| 800 | Alarm & Protection | |
| 801 | Office Supplies | |
| 802 | Electronics | |
| 803 | Kitchen Supplies | |
| 805 | Gardening Supplies | |
| 806 | Baby Care | |
| 807 | Faucets & Accesories | |
| 808 | Lightings | |
| 809 | Decor | |
| 810 | Household Goods | |
| 811 | Painting | |
| 812 | School Supplies | |
Appeal & Accesories |
||
| 900 | Bracelets | |
| 901 | Necklaces | |
| 902 | Eyewear | |
| 903 | Earrings | |
| 904 | Watches | |
| 905 | Rings | |
| 906 | Men's Clothes & Shoes | |
| 907 | Women's Clothes & Shoes | |
| 908 | Bags | |
| 909 | Caps/Hats | |
| 910 | Body Jewelry | |
| 911 | Wallets & Purses | |
| 912 | Gloves | |
| 913 | Scarves | |
| 914 | Belts & Buckles | |
Sports & Outdoors |
||
| 1000 | Knives & Multi-Tools | |
| 1001 | Airsoft & Guns Supplies | |
| 1002 | Fitness | |
| 1003 | Outdoor Recreation | |
| 1004 | Camping | |
| 1005 | Cycling | |
| 1006 | Fishing Gear | |
| 1007 | Other Sports Gadgets | |
| 1008 | War Games Accesories | |
| 1009 | Travelling Needs | |
| 1010 | Ball Game | |
| 1011 | Water Sport | |
| 1012 | Men's Outdoor Clothing | |
| 1013 | Women's Outdoor Clothing | |
| 1014 | Footwear | |
| 1015 | Swimwear | |
| 1016 | Sport Watches | |
| 1017 | Sports Safety | |
| 1018 | Headwears Sport Scarves | |
| 1019 | Sports Clothing | |
| 1020 | Hunting War Games | |
| 1021 | Sports Bags | |
| 1022 | Gym Supplies | |
| 1023 | Binoculars & Monoculars | |
Health & Beauty |
||
| 1100 | Relaxers & Massagers | |
| 1101 | Wigs | |
| 1102 | Health Monitors | |
| 1103 | Health Care Assistants | |
| 1104 | Hairdressing Supplies | |
| 1105 | Makeup Supplies & Tools | |
| 1106 | Skin Care | |
| 1107 | Shaving Hair Removal | |
| 1108 | Beauty Electronics | |
Body Shop |
||
| 1200 | Skin Care | |
| 1201 | Hair Care | |
| 1202 | Men's Fragrance | |
| 1203 | Women's Fragrance | |
| 1204 | Home Scent | |
| 1205 | Make Up | |
| 1206 | Unisex Fragrance | |
Wedding & Events |
||
| 1301 | Dresses | |
| 1302 | Suits | |
| 1303 | Wedding Supplies and Accessories | |
Cats |
||
| 1400 | Cat Clothing & Shoes | |
| 1401 | Cat Toys | |
| 1402 | Cat Food Supplies | |
| 1403 | Cat Cleaning Supplies | |
| 1404 | Cat Training & Behaviour | |
| 1405 | Cat Others | |
| 1406 | Cat Collars, Harnesses & Leashes | |
Dogs |
||
| 1500 | Dog Clothing & Shoes | |
| 1501 | Dog Collars, Harnesses & Leashes | |
| 1502 | Dog Food Supplies | |
| 1503 | Dog Others | |
| 1504 | Dog Toys | |
| 1505 | Dog Training & Behavior | |
| 1506 | Dog Cleaning Supplies | |
Pets |
||
| 1600 | Pet Others | |
Birds |
||
| 1700 | Birds | |
| 1701 | Bird Others | |
Fish & Aquatic Pets |
||
| 1800 | Fish & Aquatic Pets | |
| 1801 | Fish & Aquatic Pets Others | |
Promotions |
||
| 1900 | Promotions | |
Adults |
||
| 2000 | Adults |
Errors
Structure
Nocnoc uses the following error response structure:
{"code":401,"message":"Authentication failed","key":"authentication_failed"}
In code you can find the error's HTTP code, and in message, details of the error.
Error List
| Code | Meaning |
|---|---|
| 310 | Invalid Param - An invalid param was sent in the request |
| 311 | Invalid Order Status Change - The order cannot change to the status requested |
| 312 | Order Not Found - An invalid order id was sent in the request |
| 313 | Order Already Exists - An order with the same merchant_invoice_id already exists |
| 314 | Order Cannot Be Processed - The order does not fullfil custom regulations |
| 315 | Invalid Request Header - The request arrives with an invalid header value |
| 316 | Order Amount Exceeded - Order's amount exceeds local regulations |
| 317 | Order Weight Exceeded - Order's weight exceeds local regulations |
| 318 | Product Quantity Exceeded - One or more product's quantity exceeds local regulations |
| 319 | Customer Not Allowed - Customer is not allowed to buy because of local regulations |
| 320 | Invalid Customer's Tax Id - Customer's tax id is not valid |
| 321 | Subcategory Forbidden - Product's subcategory is forbidden |
| 322 | Address Unavailable - Customer's delivery address location is not available yet |
| 323 | SKU Forbidden - SKU is forbidden |
| 400 | Bad Request |
| 401 | Unauthorized - An invalid API key was sent in the header of the request |
| 404 | Not Found |
| 405 | Method Not Allowed |
| 500 | Internal Error - Please contact support |
Download Packing Guide
This guide must be provided to logistics department for necessary guidelines when attaching invoice, label and packing items. Click here in order to download the file.