Submit

Submit new declaration.

2 Declaration Types

There are 2 types of declarations: Normal, VIP. Please check with your assigned technical support personnel to identify your declaration type.

Checking Declaration Status

Certain declarations may be approved immediately, while others might take some time to process. Upon submitting new declaration if status is not "APPROVED"/"REJECTED", you may check for change in status at a later time. There are 2 ways to check status: declaration/query API and callback.

Recommended apporach is to define a callback URl in declaration/submit API. Whenever there is a change in declaration status, declaration information will be sent to the defined callback URL via HTTP POST. This is more efficient than constantly polling declaration/query API.

Second approach is to call the declaration/query API. Repeated call to should be kept minimal, in order to reduce unnecessary load on both yours and XpressCover server.

Endpoint

/api/declaration/submit

Request

Request Parameter

Name	Mandatory	Description	Type	Default
type	Y	Declaration Type	char ( 1 )
		N: Normal
		C: VIP
user	Y	User ID	string ( 255 )
consignment_note	Y	Consignment Note	string ( 100 )
cover_date	Y	Cover Date	date ( YYYYMMDD )
from_country	Y	"Deliver from" country	ISO 3166-1 alpha-3 country code
to_country	Y	"Deliver to" country	ISO 3166-1 alpha-3 country code
remark	N	Remark	string ( 255 )
courier_code	Y	Courier Code	string ( 100 )
courier_others	Mandatory if courier_code == "OTHERS"	Courier Name	string ( 255 )
callback_url	N	Callback URL	string ( 255 )

Extra Request Parameter (Type = VIP Only)

Name	Mandatory	Description	Type	Default
from_address	Y	Send From Address	string ( 255 )
to_address	Y	Send To Address	string ( 255 )
goods_description	Y	Goods Description	string ( 255 )
total_value	Y	Total Declare Value	decimal ( 11, 2 )

Extra Request Parameter (Type = Normal Only)

Name	Mandatory	Description	Type	Default
from_city	Y	Send From City	string ( 255 )
to_city	Y	Send To City	string ( 255 )
items	Y	Declaration Items	Array ( Item )

Item Parameter

Name	Mandatory	Description	Type	Default
descriptions	Y	Descriptions	string ( 255 )	​
quantity	N	Quantity	integer	​1
price	Y	Unit Price	decimal ( 11, 2 )	​
commodity_code	Y	Commodity Code	string ( 10 )	​

Example Request (VIP):

{
    "type": "C",
    "user": "marketplace_a_apple",
    "consignment_note": "TESTCN123456",
    "cover_date": "20181225",
    "from_country": "MYS",
    "to_country": "MYS",
    "from_address": "Shah Alam",
    "to_address": "12, Apartment Setia, Jalan ABC 123/2, 23400 PJ, Selangor",
    "goods_description": "1 x Samsung J5, 2 x USB Cable",
    "total_value": 2130.20,
    "courier_code": "OTHERS",
    "courier_others": "Jumbo"
}

Example Request (Normal):

{
    "type": "N",
    "user": "marketplace_a_apple",
    "consignment_note": "TESTCN123457",
    "cover_date": "20181225",
    "from_country": "MYS",
    "to_country": "MYS",
    "from_city": "Shah Alam",
    "to_city": "Kepong",
    "courier_code": "OTHERS",
    "courier_others": "Jumbo",
    "items": [
        {
            "descriptions": "iPhone 6",
            "quantity": 1,
            "price": 3000.00,
            "commodity_code": "1002"
        },
        {
            "descriptions": "iPhone 7",
            "quantity": 1,
            "price": 4000.00,
            "commodity_code": "1002"
        }
    ]
}

Response

Successful Response Params

Name	Description	Type
declaration	Declaration	Declaration Model

Example Response (VIP):

{
    "status": "SUCCESS",
    "declaration": {
        "id": 123,
        "type": "C",
        "user": "marketplace_a_apple",
        "consignment_note": "TESTCN123456",
        "status": "A",
        "cover_date": "20181225",
        "from_country": "MYS",
        "to_country": "MYS",
        "from_address": "Shah Alam",
        "to_address": "12, Apartment Setia, Jalan ABC 123/2, 23400 PJ, Selangor",
        "goods_description": "1 x Samsung J5, 2 x USB Cable",
        "total_value": 2130.20,
        "courier_code": "OTHERS",
        "courier_others": "Jumbo",
        "total_surcharge": 42.60,
        "tax": 2.56,
        "total_charge": 45.16,
        "created_at": 1443349532,
        "cover_note_url": "https://xc-connect-sit.xpresscover.com/api/declaration/pdf/123/65c9041247ca616cc16ee45a11970136b5604725"
    }
}

Example Response (Normal):

{
    "status": "SUCCESS",
    "declaration": {
        "id": 124,
        "type": "N",
        "user": "marketplace_a_apple",
        "consignment_note": "TESTCN123457",
        "status": "A",
        "cover_date": "20181225",
        "from_country": "MYS",
        "to_country": "MYS",
        "from_city": "Shah Alam",
        "to_city": "Kepong",
        "total_value": 7000.00,
        "courier_code": "OTHERS",
        "courier_others": "Jumbo",
        "total_surcharge": 140.00,
        "tax": 8.40,
        "total_charge": 148.40,
        "created_at": 1443349532,
        "cover_note_url": "https://xc-connect-sit.xpresscover.com/api/declaration/pdf/123/65c9041247ca616cc16ee45a11970136b5604725",
        "items": [
            {
                "no": 1,
                "descriptions": "iPhone 6",
                "quantity": 1,
                "price": 3000.00,
                "subtotal": 3000.00,
                "commodity_code": "1002",
                "rate": 2.00,
                "surcharge": 60.00
            },
            {
                "no": 2,
                "descriptions": "iPhone 7",
                "quantity": 1,
                "price": 4000.00,
                "subtotal": 4000.00,
                "commodity_code": "1002",
                "rate": 2.00,
                "surcharge": 80.00
            }
        ]
    }
}

Callback URL

If defined callback_url when submit declaration, any update to declaration will initiate HTTP POST request to callback_url with body content = declaration model in json format.

callback_url must return with HTTP response ( 200 ) and body content in json format with status = OK

{
    "status": "OK"
}

If request to callback_url failed, XpressConnect will retry in 30 seconds interval, for maximum 3 times ( inclusive 1st request )

Example PHP Code

<?php

header('Content-Type: application/json');

$entityBody = file_get_contents('php://input');

$jsonObject = json_decode($entityBody);

// DO anything needed for $jsonObject

// return response status = OK
echo json_encode(['status' => 'OK']);