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 need to fill Information Form and choose what API does client need in their business process. There are several kind 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 want 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 a testing on J&T testing environment. After success making and 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 use 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.

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
ParameterTypeNull(Y/N)Description
data_paramStringNRequest 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_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

note : for separators between code, please use "-" as the separators,
for example use TEST-ORDER-001 instead of TEST/ORDER/001
shipper_nameString (30)NSender Name
shipper_contactString (30)NSender Name
shipper_phoneString (15)NPhone No. from Sender (format +62xxx)
shipper_addrString (200)NSender Address
origin_codeString (3)NOrigin City code ex: SDA (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of the integration
flow process
receiver_nameString (30)NRecipient
receiver_phoneString (15)NPhone No. from Recipient (format +62xxx)
receiver_addrString (200)NRecipient Address
receiver_zipString (5)NPostal Code Recipient

note : in case if the user didn't input the postal code, this parameter
can be filled with 00000 instead
destination_codeString (3)NDestination City code e.g : SDA (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of the integration 
flow process

receiver_areaString (10)NDistrict Code e.g : SDA001 (Case sensitive, must use upper case),
in order to get this code list, see the fourth step of the integration 
flow process

qtyString (3)NTotal Package
weightString (5)NTotal Weight
goodsdescString (40)NDescription (No Special Character Allowed)
servicetypeINT(4)NFill with 1 : for pickup service or 6: for drop off service
insuranceStringYPercentages by agreement with product advisor
orderdateStringNCustomer order date (using format YYYY – MM – DD hh:mm:ss
and UTC + 7)
item_nameString (50)NItem name e.g : Phone

note : No Special Character Allowed, and please
limit the length to just 50 characters
codStringYCOD value
sendstarttimeStringYStart Pickup Time (using format YYYY – MM – DD hh:mm:ss
and UTC + 7)
sendendtimeStringYEnd Pickup Time (using format YYYY – MM – DD hh:mm:ss
and UTC + 7)
expresstypeStringYFilled with : "1" = REGULAR
goodsvalueStringNGoods 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 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'=>'MES',

   '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))

);

 

 

Format Return 

Return Sukses


{

    "success": true,

    "desc": "Request berhasil",

    "detail": [

        {

            "awb_no": "JO0027364832",

            "orderid": "ORDERID-0001",

            "desCode": "JKT-JKT001",

            "etd": "2-4",

            "status": "Sukses",

        }

    ]

}

 


Return error


{

    "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.