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.

*Please note if the integration process has completed, each month both client and J&T Express finance will do reconcilliation for shipment fee based on aggreement that have been signed before

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 is used to place an order from marketplace or ecommerce to J&T, then J&T will generate the waybill number as feedback.

Process Flow

 

 

The image above is the simple process of Order, the steps are :

 

  1. Customer make an order from the partner’s website,
  2. Partner system will place the order to J&T through API,
  3. J&T API will give the waybill number as API feedback/return to client,
  4. Partner can give the waybill number to Customer,
  5. Customer can drop the package/ask J&T for pickup.

 

API Details

Request Method : POST
Header : application/x-www-form-urlencoded
URL : {can be seen on dashboard after login}
Body  :  

 

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

 data_sign

 String

 N

Signature on data_param + key (Encryption)

data_param

Parameter

Type

Null

(Y/N)

Description

 username

 String

N

{can be seen on dashboard after login}

 api_key

 String

N

{can be seen on dashboard after login}

 orderid

 String (20)

N

Ecommerce/onlineshop order ID

 

note :

-We recommend to add prefix on the orderid to  differentiate with the other partner

 

-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

Sender phone number (format +62xxxx)

 shipper_addr

 String (200)

N

Sender address

 origin_code

 String (3)

N

Sender’s/origin city code, e.g. JKT (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

Recipient phone number (format +62xxxx)

 receiver_addr

 String (200)

N

Recipient address

 receiver_zip

 String (5)

N

Recipient Postal Code

 

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

Recipient’s/Destination City Code e.g. : JKT (Case sensitive, must upper case),

in order to get this code list, see the fourth step of Integration flow process

 receiver_area

 String(10)

N

Recipient’s/Destination District Code e.g. : JKT001 (Case sensitive, must upper case),

in order to get this code list, see the fourth step of Integration flow process

 qty

 int

N

Total item in package

 weight

 double

N

Package weight in Kg, can be up to 2 decimal places

 goodsdesc

 String (40)

N

Goods description (No special character allowed)

 servicetype

 int

N

Can be filled with :

1 = Pickup service

6 = Drop Off service

 insurance

 int

Y

Insurance value that calculated based from the percentages in agreement with product advisor

 orderdate

 String

N

Place order time to J&T API

(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, please limit the length to just 50 characters

 cod

 int

Y

COD Value, up to 8 digit

 sendstarttime

 String

N

Start pickup range time

(using format YYYY-MM-DD hh:mm:ss and UTC+7)

 sendendtime

 String

N

End pickup range time

(using format YYYY-MM-DD hh:mm:ss and UTC+7)

 expresstype

 String

N

Filled with "1" = EZ (Regular)

 goodsvalue

 int

N

Goods value, up to 8 digit

Note : if the parameter want to sent with a null value, please fill with just an empty value ("").

 

How To Do Signature

Signature can be generated by concatenating data_param and key, then do MD5 and base64 sequentially. Below is the example for the PHP

$signature   = base64_encode(md5(($data_param).$key));

 

Examples

Request from Postman

Request from PHP

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'=>'JKT',
   'receiver_area'=>'JKT001',
   'qty'=>'1',
   'weight'=>'1',
   'goodsdesc'=>'TESTING!!',
   'servicetype'=>'1',
   'insurance'=>'122',
   'orderdate'=>'2021-08-01 22:02:00',
   'item_name'=>'topi',
   'cod'=>'120000',
   'sendstarttime'=>'2021-08-01 08:00:00',
   'sendendtime'=>'2021-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 Example

Success

{
    "success": true,
    "desc": "Request berhasil",
    "detail": [
        {
            "awb_no": "JO0027364832",
            "orderid": "ORDERID-0001",
            "desCode": "JKT-JKT001",
            "etd": "2-4",
            "status": "Sukses",
        }
    ]
}

Failed

{
    "success": true,
    "desc": "Request berhasil",
    "detail": [
        {
            "orderid": "ORDERID-0001",
            "desCode": "JKT-JKT001",
            "etd": "No Data",
            "status": "Error",
            "reason": "Orderid tidak boleh sama"
        }
    ]
}

 

There are several error message responses from Order API

No

Reason

Description

1

Orderid tidak boleh sama

The orderid parameter value is duplicated

2

Username atau Api Key salah

The API credential is incorrect

3

Kesalahan signature

The Signature is incorrect

4

shipper_phone tidak boleh lebih dari 15 character

The shipper_phone parameter exceeds 15 characters

5

shipper_addr tidak boleh lebih dari 250 character

The receiver_addr parameter exceeds 250 characters

6

receiver_addr tidak boleh lebih dari 250 character

The receiver_addr parameter exceeds 250 characters

7

Origin_code salah

The origin_code parameter value is invalid

8

Destination_code salah

The destination_code parameter value is invalid

9

Kecamatan Penerima Error

The receiver_area parameter value is invalid

10

Terdapat kesalahan format data yang dikirimkan

The Json format is invalid

11

Kesalahan pada parameter

The body parameter data is invalid or the data_param is not in detail object

12

Parameter tidak boleh kosong

The body parameter data is invalid or the data_param is not in detail object

13

Parameter orderid tidak boleh kosong

The orderid parameter can’t be empty

14

Parameter api_key tidak boleh kosong

The api_key parameter can’t be empty

15

Parameter username tidak boleh kosong

The username parameter can’t be empty

16

Parameter shipper_name tidak boleh kosong

The shipper_name parameter can’t be empty

17

Parameter shipper_contact tidak boleh kosong

The shipper_contact parameter can’t be empty

18

Parameter shipper_phone tidak boleh kosong

The shipper_phone parameter can’t be empty

19

Parameter shipper_addr tidak boleh kosong

The shipper_addr parameter can’t be empty

20

Parameter origin_code tidak boleh kosong

The origin_code parameter can’t be empty

21

Parameter receiver_name tidak boleh kosong

The receiver_name parameter can’t be empty

22

Parameter receiver_phone tidak boleh kosong

The receiver_phone parameter can’t be empty

23

Parameter receiver_addr tidak boleh kosong

The receiver_addr parameter can’t be empty

24

Parameter receiver_zip tidak boleh kosong

The receiver_zip parameter can’t be empty

25

Parameter receiver_area tidak boleh kosong

The receiver_area parameter can’t be empty

26

Parameter qty tidak boleh kosong

The qty parameter can’t be empty

27

Parameter weight tidak boleh kosong

The weight parameter can’t be empty

28

Parameter weight tidak boleh lebih dari 100 Kg

The weight parameter exceed 100 kg


TRACKING API

This API can be used to track the shipment progress or status.

API Details

Request Method : POST
Authorization : Basic Authorization
URL : {can be seen on dashboard after login}
Body : Raw (Text)

 

Parameter

Type

Null

(Y/N)

Description

 awb

String

N

 AWB Number

 eccompanyid

String

N

 {can be seen on dashboard after login}

 

Request Example

Request from Postman

 

Request from PHP 

$password = '.........'
$billcode ='JD1234567890';        
$data = array
(
                'awb'=>$billcode,
                'eccompanyid'=>'.......'
);
$jsonData = json_encode($data);

 

Response

Response Parameters

Parameter

Type

Description

error_id

String

Error code

error_message

String

Error Message

awb

String

AWB number

orderid

String

Order number

detail

object

the detail of the shipment

-          shipped_date

String

The timestamp of AWB processed by J&T

-          services_code

String

Service code

-          actual_amount

int

The total price of the shipment

-          weight

int

The weight of the package

-          qty

int

The quantity of item inside the package

-          itemname

String

Item Name

-          detail_cost

object

Detail of the costs, these data will be filled when the AWB has been processed by J&T

·         shipping_cost

int

Cost of the shipment

·         add_cost

int

Additional cost of the shipment (Wood Packaging, etc)

·         insurance_cost

int

Insurance cost of the shipment

·         cod

int

COD value of the shipment

·         return_cost

int

Return cost of the shipment

-          sender

object

sender details

·         name

String

Sender name

·         addr

String

Sender address

·         city

String

Sender City

-          receiver

Object

 

·         name

String

Recipient Name

·         addr

String

Recipient Address

·         zipcode

String

Recipient zipcode

·         city

String

Recipient City

-          driver

object

J&T Pickup driver details

·         name

String

J&T Pickup person name

-          delivDriver

Object

J&T Delivery driver details

·         name

String

J&T Delivery person name

·         phone

String

J&T Delivery person phone

history

Object

Shipment Track statuses

-          date_time

String

Timestamp of the status

-          city_name

String

City of the generated status

-          status

String

Shipment status

-          status_code

String

Shipment status code

-          storeName

String

J&T Outlet /sorting center name

-          nextSiteName

String

Next J&T outlet/sorting center name

-          note

String

Note for the shipment status, Problem on shipment reason will be shown here

-          receiver

String

Receiver name

-          driverName

String

J&T Delivery person name

-          driverPhone

String

J&T Delivery person phone

-          presenter

String

Flag for the recipient is represented

 

Status Code lists

Status Code

Status

Description

101

Manifes

Order has been created

100

Paket telah diterima oleh xxxxxxxx

Package has been picked up by J&T

100

Paket akan dikirimkan ke xxxxxxx

Package will be send to station xxxxxx

100

Paket telah sampai di xxxxxxxx

Package arrived at station xxxxx

100

Paket akan dikirim ke alamat penerima

Package is on delivery to receiver

162

Cancelled AWB by Seller

Cancelled AWB by API

163

Cancelled AWB

Cancelled AWB by J&T

150

Paket disimpan di gudang J&T

Problem with shipment / Onhold

151

Pickup Failed

Problem on pickup process

152

Paket disimpan di gudang J&T

Problem on delivery process

200

Paket telah diterima

Delivered

401

Paket akan diretur

Package will be returned to sender

402

Package returned to seller

Package returned to sender

 

Response Examples

Success

{
   "awb":"JD1234567890",
   "orderid":"ASD1234567890",
   "detail":{
      "shipped_date":"2021-09-07 15:34:45",
      "services_code":"EZ",
      "services_type":"",
      "actual_amount":50000,
      "weight":2000,
      "qty":1,
      "itemname":"Kacamata Hitam",
      "detail_cost":{
         "shipping_cost":50000,
         "add_cost":0,
         "insurance_cost":0,
         "cod":2250,
         "return_cost":0
      },
      "sender":{
         "name":"Pengirim",
         "addr":"DKI JAKARTA, JAKARTA, Jalan Raya Pengirim",
         "zipcode":"14310",
         "city":"JAKARTA",
         "geoloc":""
      },
      "receiver":{
         "name":"Penerima",
         "addr":"JAWA BARAT, BEKASI, Jalan Raya Penerima, RT 001, RW 003, Jatiasih",
         "zipcode":"17422",
         "city":"BEKASI",
         "geoloc":""
      },
      "driver":{
         "id":"",
         "name":"Budi",
         "phone":"",
         "photo":""
      },
      "delivDriver":{
         "id":"",
         "name":"Astuti",
         "phone":"+6281234567890",
         "photo":""
      }
   },
   "history":[
      {
         "date_time":"2021-09-07 15:29:37",
         "city_name":"JAKARTA",
         "status":"Manifes",
         "status_code":101,
         "storeName":"",
         "nextSiteName":"KALIDERES",
         "note":"",
         "receiver":"",
         "driverName":"",
         "driverPhone":"",
         "presenter":"",
         "agentName":"",
         "presentername":""
      },
      {
         "date_time":"2021-09-07 15:34:45",
         "city_name":"JAKARTA",
         "status":"Paket telah diterima oleh KALIDERES",
         "status_code":100,
         "storeName":"KALIDERES",
         "nextSiteName":"KALIDERES",
         "note":"",
         "receiver":"",
         "driverName":"Reykalideres",
         "driverPhone":"+6287782000705",
         "presenter":"TRUE",
         "agentName":"",
         "presentername":""
      },
      {
         "date_time":"2021-09-07 15:42:30",
         "city_name":"JAKARTA",
         "status":"Paket akan dikirimkan ke JKT_GATEWAY",
         "status_code":100,
         "storeName":"KALIDERES",
         "nextSiteName":"JKT_GATEWAY",
         "note":"",
         "receiver":"",
         "driverName":"",
         "driverPhone":"",
         "presenter":"TRUE",
         "agentName":"",
         "presentername":""
      },
      {
         "date_time":"2021-09-09 17:44:31",
         "city_name":"JAKARTA",
         "status":"Paket akan dikirim ke alamat penerima",
         "status_code":100,
         "storeName":"KALIDERES",
         "nextSiteName":"KALIDERES",
         "note":"",
         "receiver":"",
         "driverName":"Astuti",
         "driverPhone":"+6281234567890",
         "presenter":"TRUE",
         "agentName":"",
         "presentername":""
      },
      {
         "date_time":"2021-09-09 17:47:36",
         "city_name":"JAKARTA",
         "status":"Paket telah diterima",
         "status_code":200,
         "storeName":"KALIDERES",
         "nextSiteName":"KALIDERES",
         "note":"",
         "receiver":"Penerima",
         "driverName":"Astuti",
         "driverPhone":"",
         "presenter":"TRUE",
         "agentName":"",
         "presentername":""
      }
   ]
}

Failed

{
     "error_id":"404",
     "error_message":"Invalid AWB number"
}

 

There are several error message responses from Track API

No

Error Code

Reason

Description

1

404

Invalid AWB number

The AWB number is invalid or the track status has expired

2

404

Authorization failed

The API credential is incorrect

 

TARIFF CHECKING

This API can be used to check shipping rates from origin city to destination district.

API Details

Request Method : POST
Header : application/x-www-form-urlencoded
URL : {can be seen on dashboard after login}
Body : x-www-form-urlencoded

 

Parameter

Type

Null

(Y/N)

Description

data

String

N

Request data

sign

String

N

Signature on data + key (Encryption)

 

data

Parameter

Type

Null

(Y/N)

Description

weight

double

N

Weight of the package

sendSiteCode

String

N

Origin Code-City e.g. 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

N

Destination Code- District e.g. 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

N

{can be seen on dashboard after login}

productType

String

N

Filled with "EZ"

 

How To Do Signature

Signature can be generated by concatenating data_param and key, then do MD5 and base64 sequentially. Below is the example for the PHP

$signature   = base64_encode(md5(($data_param).$key));

 

Request Example

Request from Postman

 

Request for PHP

$key = '......';
$data = array
(
                'weight'=>"1"
                ,'sendSiteCode'=>'JAKARTA'
                ,'destAreaCode'=>'KALIDERES'
                ,'cusName'=>'........'
                ,'productType'=>'EZ'
);
$jason=json_encode($data);
$mmm = base64_encode(md5($jason.$key));

$data1 = array
(
                 'data'=>$jason
                ,'sign'=>$mmm
);

 

Response

Response Parameters

Parameter

Type

Description

is_success

String

Flag whether the request to API is success

message

String

The message description

content

String

The services array is in String

-          name

String

J&T Service Name

-          cost

String

Shipment cost

 

Response Examples

Success

{
   "is_success":"true",
   "message":"",
   "content":"[{\"name\":\"EZ\",\"cost\":\"9000\"}]"
}

Failed

{
   "is_success":"false",
   "message":"invalid Authorization"
}

 

There are several error message responses from Track API

No

Reason

Description

1

fail

The API credential is incorrect or invalid request data

2

invalid Authorization

The API credential is incorrect


API Cancel Order

This API can be used to cancel Order that has not been processed by J&T.

API Details

Request Method : POST
Header : application/x-www-form-urlencoded
URL : {can be seen on dashboard after login}
Body : x-www-form-urlencoded

 

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

 

for example data_param => {"detail":[{……}]}

data_sign

String

N

Signature on data_param + key (Encryption)

 

data_param

Parameter

Type

Null

(Y/N)

Description

username

String

N

{can be seen on dashboard after login}

api_key

String

N

{can be seen on dashboard after login}

orderid

String (20)

N

Ecommerce/onlineshop order ID

remark

String (30)

N

 Cancellation remark

 

How To Do Signature

Signature can be generated by concatenating data_param and key, then do MD5 and base64 sequentially. Below is the example for the PHP

$signature   = base64_encode(md5(($data_param).$key));

 

Request Example

Request from Postman

 

Request for PHP

$key = << Please call us >>
$data = array
(
                'username'=>'....'
                ,'api_key'=>'......'
                ,'orderid'=>'ORDERID-12345678'
                ,'remark'=>'Canceled by E-Commerce'
);
$data_param    = json_encode(array('detail'=>array($data)));
$data_sign     = base64_encode(md5(($data_param).$key));

 

Response

Response Parameters

Parameter

Type

Description

success

String

Flag whether the request to API is success

desc

String

The message description

detail

object

 

-          orderid

String

Ecommerce/onlineshop order ID

-          status

String

Flag whether the Cancellation is success

-          reason

String

Reason for the failed cancellation

 

Response examples

Success

{
   "success":true,
   "desc":"Request berhasil",
   "detail":[
      {
         "orderid":"ORDERID-12345678",
         "status":"Sukses",
         "reason":""
      }
   ]
}

Failed

{
   "success":true,
   "desc":"Request berhasil",
   "detail":[
      {
         "orderid":"ASD-123463",
         "status":"Error",
         "reason":"Tidak dapat dibatalkan,Status pesanan adalah:CANCEL_ORDER"
      }
   ]
}

 

There are several error message responses from Order API

No

Reason

Description

1

Username atau Api Key salah

The API credential is incorrect

2

Kesalahan signature

The Signature is incorrect

3

Tidak dapat dibatalkan,Status pesanan adalah:GOT

The order has been processed by J&T

4

Order berikut bukan dalam username yang sama

The order is belongs to other partner

5

Tidak dapat dibatalkan,Status pesanan adalah:CANCEL_ORDER

The order has been cancelled

6

Parameter orderid tidak boleh kosong

The orderid parameter can’t be empty

7

Kesalahan pada parameter

The body parameter data is invalid or the data_param is not in detail object