NAV
bash javascript

Developers Documentation

Easy Marketplace 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

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 info@nocnocgroup.com .

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 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":"george.walker@nocnoc.com.ar",
    "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":"george.walker@nocnoc.com.ar",
        "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://www.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": "george.walker@nocnoc.com.ar"
        },
    "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 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://www.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": "george.walker@nocnoc.com.ar"
        },
    "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://www.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": "george.walker@nocnoc.com.ar"
        },
    "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://www.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": "george.walker@nocnoc.com.ar"
        },
    "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 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

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 Printer Parts & Supplies
220 Cable Management
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

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
307 DIY Parts & Components
308 Plugs & Sockets
309 Switches & Adapters
310 Gadgets
311 Hand Tools

Cellphones & Accesories

400 Cellphones
401 Cases & Protectors
402 Cables & Chargers
403 Adapters & Converters
404 Batteries
405 DIY Parts & Tools
406 Gadgets
407 Mounts & Holders
408 Stylus Touch Gloves
409 iPhone Accesories
410 Samsung 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

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

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
804 Pet Supplies
805 Gardening Supplies
806 Baby Care
807 Faucets & Accesories
808 Lightings
809 Decor
810 Household Goods

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

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

Body Shop

1200 Skin Care
1201 Hair Care
1202 Men's Fragrance
1203 Women's Fragrance
1204 Home Scent
1205 Make Up

Wedding & Events

1301 Dresses
1302 Suits
1303 Wedding Supplies and Accessories

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.