J&T API

LET'S GET STARTED

Overview

    Welcome to J&T Express API Integration Platform. In order to give a better services for our customers, J&T make this platform to provide a standard access for API so it can improve convenience between customer and JNT side in term of direct data interaction between customers and J&T data. This articles will describe the process and steps of J&T API Integration that can help customers to access J&T API more quickly and accurately.

Integration flow Process?

    Start – Cooperation Agreement - Test API Integration - Mapping Process - Production API Integration - Finish.



First Step : Start

    Before client started to integrate, client needs to fill Information Form and choose what API does client need in their business process. Also, client needs to change their password. There are several kinds of API, to understand it, you can go to Documentation page. On that page, it provides all Updated J&T API documentation.

Second Step : Cooperation Agreement

    Customer who wants to use J&T API must make an Agreement between Client and J&T Agent first. While waiting the agreement to complete, client can start to integrate their test / sandbox API by using the credential in the client’s dashboard.

Third step : Test API Integration

    After getting the test/sandbox API has been integrated, client can start doing testing on J&T testing environment. After success in request to our API and place order, client need to communicate to J&T team so they can check whether the data that client sent already correct or not. If client have any trouble during a test, client can directly contact J&T team and they will help to solve it.

Fourth Step : Mapping Process

    Before moving to production, if client uses the order or tariff check API, J&T need to do mapping process between client’s and J&T list of district, city, and province name. Client can provide client's list of districts, cities, and provinces name then will be returned to the client with additional area codes, otherwise client can proceed to production API integration. In this step, there will also some test to check the mapping that has been saved on client's side. Client can communicate to J&T team to do the test.

Fifth Step : Production API Integration

    Client can use their API production key and endpoint that will be shown in client’s dashboard, client need to do the final testing on production environment, J&T staff will verify the data accuracy that send by client to the production environment before the API going live.

Note: Please make sure that the port that was used in production endpoints are open on client side

Last Step : Finish

    After all the step before already passed, the process development is completed, the API already connected to the J&T platform and it can go online.

Terminology

    Below this the main terminology that J&T use for signature and sending data.

Terminology

Description

Signature

MD5,Base64

Key

6a35d330a55de6883ceeaca03cc4871c

 



API BASIC ORDER

This API are used to place an order from marketplace or ecommerce to J&T, then J&T will generate waybill number as feedback.

PROCESS FLOW



    Above is the simple process of Basic order:

    1.Customer make an order from client website,

    2.From client system will placed an order to J&T system using API

    3.J&T system will give Waybill Number as the result to client 

    4.Client will give J&T AWB number to Customer

    5.Customer Dropoff package.

Parameter

Parameter Request
Parameter Type Null(Y/N) Description
data_param String N Request data, JSON of an array of request data which is JSON encoded in detail parameter

Please take a look at the example below for PHP example code .
data_sign String N Signature on data_param + key (Encryption)

Parameter Request Data
Parameter Type Null(Y/N) Description
username String N ((Please Contact Us))
api_key String N ((Please Contact Us))
orderid String (20) N Ecommerce/onlineshop order ID

note : for separators between code, please use "-" as the separators,
for example use TEST-ORDER-001 instead of TEST/ORDER/001
shipper_name String (30) N Sender Name
shipper_contact String (30) N Sender Name
shipper_phone String (15) N Phone No. from Sender (format +62xxx)
shipper_addr String (200) N Sender Address
origin_code String (3) N Origin City code ex: SDA (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of   Integration flow process
receiver_name String (30) N Recipient Name
receiver_phone String (15) N Phone No. from Recipient (format +62xxx)
receiver_addr String (200) N Recipient Address
receiver_zip String (5) N Postal Code Recipient

note : in case if the user didn't input the postal code, this parameter can be filled with 00000 instead
destination_code String (3) N Destination City code e.g : SDA (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of   Integration flow process
receiver_area String (10) N District Code e.g : SDA001 (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of   Integration flow process
qty String (3) N Total Package
weight String (5) N Total Weight
goodsdesc String (40) N Description (No Special Character Allowed)
servicetype INT(4) N Fill with 1 : for pickup service or 6: for drop off service 
insurance String Y Insurance value calculated from the percentages by agreement with product advisor 
orderdate String N Customer order date (using format YYYY ? MM ? DD hh:mm:ss
and UTC + 7)
item_name String (50) N Item name e.g : Phone

note : No Special Character Allowed, and please
limit the length to just 50 characters
cod String Y COD value
sendstarttime String Y Start Pickup Time (using format YYYY ? MM ? DD hh:mm:ss
dan and UTC + 7)
sendendtime String Y End Pickup Time (using format YYYY ? MM ? DD hh:mm:ss
and UTC + 7)
expresstype String Y Filled with : "1" = REGULAR
goodsvalue String N Goods value
Note: if the parameter want to be sent with a null value, please fill with just an empty value ("").

How To Do Signature


key = (( Please call us ))

base64 (md5 hash ( data_param + key ))



Request Method : POST

Header                 : Content-Type: application/x-www-form-urlencoded

Example Request PHP code

 

key = << Please call us >>

 

$data = array

(

   'username'=>'username',

   'api_key'=>'api_key',

   'orderid'=>'ORDERID-0001'

   'shipper_name'=>'PENGIRIM',

   'shipper_contact'=>'PENGIRIM',

   'shipper_phone'=> '+628123456789',

   'shipper_addr'=>'JL. Pengirim no.88, RT/RW:001/010, Pluit',

   'origin_code'=>'JKT',

   'receiver_name'=>'PENERIMA',

   'receiver_phone'=>'+62812348888',

   'receiver_addr'=>'JL. Penerima no.1, RT/RW:04/07, Sidoarjo',     

   'receiver_zip'=>'40123',

   'destination_code'=>'SDA',

   'receiver_area'=>'SDA001',

   'qty'=>'1',

   'weight'=>'1',

   'goodsdesc'=>'TESTING!!',

   'servicetype'=>'1',

   'insurance'=>'50000',

  'orderdate'=>'2017-08-01 22:02:00',

  'item_name'=>'topi',

  'cod'=>'200000',

  'sendstarttime'=>'2017-08-01 08:00:00',

  'sendendtime'=>'2017-08-01 22:00:00',

  'expresstype'=>'1',

  'goodsvalue'=>'1000',

);

 

data_json = json_encode(array('detail'=>array($data)));

$data_request = array

(

   'data_param'=>$data_json,

   'data_sign'=> base64_encode(md5($data_json.$key))

);

 

 

Return Format

Success Return


{

    "success": true,

    "desc": "Request berhasil",

    "detail": [

        {

            "awb_no": "JO0027364832",

            "orderid": "ORDERID-0001",

            "desCode": "JKT-JKT001",

            "etd": "2-4",

            "status": "Sukses",

        }

    ]

}

 


Error Return


{

    "success": true,

    "desc": "Request berhasil",

    "detail": [

        {

            "orderid": "ORDERID-0001",

            "desCode": "JKT-JKT001",

            "etd": "No Data",

            "status": "Error",

            "reason": "Orderid tidak boleh sama"

        }

    ]

}

 

    

The responses above are an example of return code success request. True response indicates that the request is successful; false response indicates that the request is fail, and an error message is returned when failure occur, if there is no error message, the response will be AWB number.


TRACKING API

This API are used to track the shipping progress.

Parameter

Parameter Request
ParameterTypeNull(Y/N)Description
awbStringNAWB Number
eccompanyidStringNgiven by J&T

Request Method         : POST

Authorization              : Basic Authorization

Example Request code


{"awb":"JO0009700042","eccompanyid":"given by J&T"}


 

Return Format
Success Return

 

{

    "awb": "JO0009700042",

    "orderid": "STARSHOP00024",

    "detail": {

        "shipped_date": "",

        "services_code": "",

        "services_type": "",

        "actual_amount": 20000,

        "weight": 2120,

        "qty": 3,

        "itemname": "Phone",

        "detail_cost": {

            "shipping_cost": 0,

            "add_cost": 0,

            "insurance_cost": 10000,

            "cod": 100000

        },

        "sender": {

            "name": "STAR SHOP",

            "addr": "Jakarta,Jakarta Utara",

            "zipcode": "",

            "city": "JAKARTA",

            "geoloc": ""

       },

        "receiver": {

            "name": "Yanuar Gozali",

            "addr": "Lengkong rt 14 rw 05 donomulyo nanggulan Kulonprogo Yogyakarta, Nanggulan, Kulon Progo, DI Yogyakarta",

            "zipcode": "11223",

            "city": "JAKARTA",

            "geoloc": ""

        },

        "driver": {

            "id": "",

            "name": "Training 18",

            "phone": "+6282261991837",

            "photo": ""

        },

        "delivDriver": {

            "id": "",

            "name": "",

            "phone": "",

            "photo": ""

        }

    },

    "history": [

        {

            "date_time": "2019-04-05 12:52:27",

            "city_name": "JAKARTA",

            "status": "Manifes",

            "status_code": 101,

            "storeName": "",

            "nextSiteName": "SLIPI",

            "note": "",

            "receiver": "",

            "driverName": "",

            "driverPhone": "",

            "presenter": "",

            "agentName": ""

        },

        {

            "date_time": "2019-04-09 17:14:15",

            "city_name": "JAKARTA",

            "status": "Paket telah diterima oleh SLIPI",

            "status_code": 100,

            "storeName": "SLIPI",

            "nextSiteName": "SLIPI",

            "note": "",

            "receiver": "",

              "driverName": "Training 18",

            "driverPhone": "+6282261991837",

            "presenter": "FALSE",

            "agentName": ""

        }

    ]

}


 

Failed Return 


{"error_id":"404","error_message":"Invalid Eccompanyid Parameter"}


 

Code Status 

    Code Description

Code Status

Code Description

100

Shipping on process

101

Order Created

150

Problem with shipment / Onhold 

151

Problem on pickup process 

152

Problem on delivery process

162

AWB Cancelled by ecommerce or onlineShop

163

AWB Cancelled by J&T

401

Package will be returned to seller

402

Package returned to seller

200

Delivered

TARIFF CHECKING

This API are used to check shipping rates.

Parameter

Parameter Request
ParameterTypeNull(Y/N)Description
dataStringNRequest data, format JSON
signStringNSee machanism of Signature

Data Parameter Request
ParameterTypeNull(Y/N)Description
weight
StringNTotal Weight
sendSiteCode
StringNOrigin Code-City eq: JAKARTA(Case sensitive, must use upper case),
in order to get this code list, see the fourth step of the integration 
flow process

destAreaCode
String
NDestination Code- District eq: KALIDERES (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of the integration 
flow process

cusName
String
NPlease call us
productTypeStringNFilled with "EZ"

How To Do Signature

 

key = (( Please call us ))

base64 (md5 hash ( data + key ))

 


Request Method : POST

Header                 : Content-Type: application/x-www-form-urlencoded

Example Request code

 

$key = ‘CONTACT US’

$datakey = array(

  ‘cusName’ => ‘HR’,

  ‘sendSiteCode’ => ‘JAKARTA’,

   ‘destAreaCode’ => ‘KALIDERES’,

   ‘weight’ => 1.31,

  'productType'=>'EZ'

);

$data=array(

‘data’ => json_encode($datakey),

‘sign’ => base64_encode(md5(json_encode($datakey).$key)),

);


 

Return Format

Success Return


{  

   "is_success":"true",

   "message":"",

   "content":"[{\"name\":\"EZ\",\"cost\":\"10000\"}]"

}


 

Error Return


{

"is_success":"false",

"message":"fail"

}




API Cancel Order

Notes: Order can be canceled if the order hasn't been pickup by our courier.

Parameter

Parameter Request
ParameterTypeNull(Y/N)Description
data_paramStringNRequest data, format JSON
data_signStringNSignature on data_param + key (Encryption)

Data Parameter Request
ParameterTypeNull(Y/N)Description
usernameStringN((Please Contact Us))
api_keyStringN((Please Contact Us))
orderidString (20)NEcommerce/onlineshop order ID
remarkString (30)NCanceled by E-Commerce
How To Do Signature


key = (( Please call us ))

base64 (md5 hash ( data_param + key ))



Example Request code


key = << Please call us >>

 

$data = array

(

   'username'=>'username',

   'api_key'=>'api_key',

   'orderid'=>'ORDERID-0001'

   'remark'=>'Canceled by E-Commerce',

);

 

data_json = json_encode(array('detail'=>array($data)));

$data_request = array

(

   'data_param'=>$data_json,

   'data_sign'=> base64_encode(md5($data_json.$key))

);


 

Return Format


{

   "success":true,

   "desc":"request berhasil",

   "detail":

   [

      {

         "orderid" : "ORDERID-0001",

         "status"  : "Error",

         "reason"  : "Tidak dapat dibatalkan,Status pesanan adalah:GOT",

      }

      {

         "orderid" : "ORDERID-0002",

         "status"  : "Success",

      }

   ]

}

 

 

    The response above are an example of return code success request. True response indicates that the request is successful; false response indicates that the request is fail, and an error message is returned when failure occur, if there is no error message,the order has been canceled.