Jumppoint Open API v1 Documentation

Table of Contents

Overview

All API endpoints listed in this documentation are relative to

  1. Production: https://open-api.jumppoint.io/
  2. Sandbox: https://staging.open-api.jumppoint.io/

Authentication

Error Message





{
  "statusCode": 401,
  "message": "Unauthorized"
}

Rate Limit

Rate limiting is applied. All endpoints have a limit of 10 requests per second.
You will be blocked once you make the maximum amount of requests.

Error Message





{
  "statusCode": 429,
  "message": "ThrottlerException: Too Many Requests"
}

Tables

Common Constants

paymentMethod

Value Description Shipment Fee Cash on Delivery
PAID_BY_MERCHANT 寄件人支付運費 Deducted from your account balance -
PAID_BY_MERCHANT_COD 寄件人付運費，貨款到付 Deducted from your account balance Received on delivery
PAID_BY_RECEIVER 收件人到付運費 Received on delivery -
CASH_ON_DELIVERY 貨物及運費到付 Received on delivery Received on delivery

Common Objects

origin

Parameter Type Description Example
contactName string Name of receiptient 'Peter Chan'
contactPhone string Phone number of receiptient '98745632'
address string Receiptient Address;
Only applicable when shipment is not delivering to Pick Up Stores;		 '新蒲崗大有街31號善美工業大廈'
floor string Floor number of receiptient address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '10'
room string Floor number of receiptient address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '01'

destination

Parameter Type Description Example
contactName string Name of receiptient 'Peter Chan'
contactPhone string Phone number of receiptient '98745632'
address string Receiptient Address;
Only applicable when shipment is not delivering to Pick Up Stores;		 '新蒲崗大有街31號善美工業大廈'
floor string Floor number of receiptient address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '10'
room string Floor number of receiptient address (if any);
Only applicable when shipment is not delivering to Pick Up Stores;		 '01'

pickUpStore

Parameter Type Description Example
code string Unique code of Pick Up Store 'KLE48'
alias string Alias of Pick Up Store '新蒲崗自提點'
districtEn string District of Pick Up Store in English 'Wong Tai Sin'
districtChi string District of Pick Up Store in Chinese '黃大仙'
address string Address of Pick Up Store '新蒲崗大有街31號善美工業大廈'
pickUpStoreCompany object information of Pick Up Store Company(if it belongs to any) [see pickUpStoreCompany]
operationTime object Operation Time of Pick Up Store [see operationTime]
freeStorage number Free period after the shipments arriving at the pick up store (in days)
(Storage fee will be charged after this period of time)		 3
providingServices object Service Options for Pick Up Stores [see providingServices]

pickUpStoreCompany

Parameter Type Description Example
nameChi string Chinese Name of the company 'OK便利店'
nameEn string English Name of the company 'Circle K'
Alias string Alias of the company 'OK'

operationTime

Parameter Type Description Example
mondayFrom string Opening time on Monday in 'HH:mm' (if any) '09:00'
mondayTo string Closing time on Monday in 'HH:mm' (if any) '18:00'
tuesdayFrom string Opening time on Tuesday in 'HH:mm' (if any) '09:00'
tuesdayTo string Closing time on Tuesday in 'HH:mm' (if any) '18:00'
wednesdayFrom string Opening time on Wednesday in 'HH:mm' (if any) '09:00'
wednesdayTo string Closing time on Wednesday in 'HH:mm' (if any) '09:00'
thursdayFrom string Opening time on Thursday in 'HH:mm' (if any) '18:00'
thursdayTo string Closing time on Thursday in 'HH:mm' (if any) '09:00'
fridayFrom string Opening time on Friday in 'HH:mm' (if any) '18:00'
fridayTo string Closing time on Friday in 'HH:mm' (if any) '09:00'
saturdayFrom string Opening time on Saturday in 'HH:mm' (if any) '18:00'
saturdayTo string Closing time on Saturday in 'HH:mm' (if any) '09:00'
sundayFrom string Opening time on Sunday in 'HH:mm' (if any) '18:00'
sundayTo string Closing time on Sunday in 'HH:mm' (if any) '09:00'
publicHolidayFrom string Opening time on Public Holidays in 'HH:mm' (if any) '18:00'
publicHolidayTo string Closing time of Public Holidays in 'HH:mm' (if any) '18:00'

providingServices

Parameter Type Description Example
cashReceipt boolean Cash Receipt service availability at pick up store true
dropOff boolean Drop Off service availability at pick up store false

item options

Parameter Type Description Example
id string ID used in POST /shipment 'D01'
descriptionChi string Option Description in Chinese 'Wine'
descriptionEn string Option Description in English '酒'

API

Shipment

POST /v1/shipment

To create a Shipment

Resource URL

Resource Information

Request Content-Type Response formats Requires authentication
application/json application/json; charset=utf-8 Yes

Body Parameters

Name Type Required Description Example
sameDayDelivery boolean Yes true for "Same-Day Delivery Service";
false for "Standard Delivery Service"		 true
origin object Yes Sender information See below
destination object Yes Receipient information See below
pickUpStoreCode String Required if this shipment is delivering to our pick up store
(Delivery to pick up stores only applicable to "Standard Delivery Service")		 Get from GET /pick-up-store/list "KLE47"
item object Yes Parcel details See below
pickUpOnHold boolean Only applicable to "Standard Delivery"; Shipment will be on hold.
No pick up date will be assigned and will not being pick up by courier until being notified by calling POST /shipment/pick-up-on-hold-release		 true
pickUpDate string Required for "Same-Day Delivery Service";
Optional for "Standard Delivery;
Not applicable when pickUpOnHold is set to true"
Hong Kong Time;		 Format: YYYY-MM-DD;
Get from GET /date/valid		 "2021-12-31"
deliveryDate string Required for "Same-Day Delivery Service";
Hong Kong Time;		 Format: YYYY-MM-DD;
Get from GET /date/valid		 "2021-12-31"
cod integer Required if paymentMethod is 'PAID_BY_MERCHANT_COD' or 'CASH_ON_DELIVERY' Amount you wish to receive from receiptient excluding the shipment fee 200
orderNotes string No Maximum: 250 characters "call customer 30 mins before delivery"
externalOrderNumber string No Maximum: 50 characters '000235462'
webhookUrl string No See Webhook;
Maximum: 250 characters		 'https://c977-61-244-155-9.ngrok.io/webhook/jumppoint'
paymentMethod string Yes See above "PAID_BY_RECEIVER"
origin-POSTv1
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits '98745632'
address string Yes Maximum: 250 characters '新蒲崗大有街31號善美工業大廈'
floor string No Maximum: 10 characters '10'
room string No Maximum: 10 characters '01'
destination-POSTv1
Name Type Required Description Example
contactName string Yes Maximum: 30 characters 'Peter Chan'
contactPhone string Yes 8 digits;
Mobile numbers should be used in order to receive SMS		 '98745632'
address string Required if no pickUpStoreCode provided Maximum: 250 characters '新蒲崗大有街31號善美工業大廈'
floor string No; Applicable only if no pickUpStoreCode provided; Maximum: 10 characters '10'
room string No; Applicable only if no pickUpStoreCode provided; Maximum: 10 characters '01'
item-POSTv1
Name Type Required Description Example
dimensionOptionId string Yes Get from GET /item/options 'D01'
weightOptionId string Required for "Same-Day Delivery Service" Get from GET /item/options 'W01'
actualWeight number Required for "Standard Delivery Service";
in kg;		 DECIMAL(8,2) 2.1
temperatureOptionId string Required for "Same-Day Delivery Service" Get from GET /item/options 'T01'
categoryOptionId string Required if no category provided Get from GET /item/options 'C203'
category string Required if no categoryOptionId provided Maximum: 10 characters 'Toys'

Example Request Body (Same-Day Delivery Service)






























{
  "sameDayDelivery": true,
  "origin": {
    "contactName": "Peter Chan",
    "contactPhone": "98745632",
    "address": "新蒲崗大有街31號善美工業大廈",
    "floor": "10",
    "room": "01"
  },
  "destination": {
    "contactName": "Peter Chan",
    "contactPhone": "98745632",
    "address": "新蒲崗大有街31號善美工業大廈",
    "floor": "10",
    "room": "01"
  },
  "item": {
    "dimensionOptionId": "D01",
    "weightOptionId": "W01",
    "temperatureOptionId": "T01",
    "categoryOptionId": "C201"
  },
  "paymentMethod": "PAID_BY_MERCHANT",
  "pickUpDate": "2021-10-05",
  "deliveryDate": "2021-10-05",
  "orderNotes": "call customer 30 mins before delivery",
  "externalOrderNumber": "000235462",
  "webhookUrl": "https://c977-61-244-155-9.ngrok.io/webhook/jumppoint"
}

Example Request Body (Standard Delivery Service + Deliver to Pick Up Store)























{
  "sameDayDelivery": false,
  "origin": {
    "contactName": "Peter Chan",
    "contactPhone": "98745632",
    "address": "新蒲崗大有街31號善美工業大廈",
    "floor": "10",
    "room": "01"
  },
  "destination": {
    "contactName": "Peter Chan",
    "contactPhone": "98745632"
  },
  "pickUpStoreCode": "KLE48",
  "item": {
    "dimensionOptionId": "D01",
    "actualWeight": 1.3,
    "categoryOptionId": "C101"
  },
  "paymentMethod": "PAID_BY_MERCHANT",
  "orderNotes": "fragile"
}

Example Response

Status Code: 201 Created




































{
  "shipment": {
    "trackingNumber": "JP319037069931",
    "sameDayDelivery": true,
    "origin": {
      "contactName": "Peter Chan",
      "contactPhone": "98745632",
      "address": "新蒲崗大有街31號善美工業大廈",
      "floor": "10",
      "room": "01"
    },
    "destination": {
      "contactName": "Peter Chan",
      "contactPhone": "98745632"
    },
    "pickUpStore": {
      "code": "KLE48",
      "alias": "新蒲崗自提點",
      "address": "大有街31號 善美工業大廈10樓1001室"
    },
    "item": {
      "dimension": "Big: >60cm 大: >60cm",
      "temperature": "Room Temperature 室溫",
      "weight": "Medium: 5-10kg 中: 5-10kg",
      "category": "Wine 酒"
    },
    "paymentMethod": "PAID_BY_MERCHANT",
    "pickUpDate": "2021-10-15",
    "deliveryDate": "2021-10-15",
    "orderNotes": "call customer 30 mins before delivery",
    "externalOrderNumber": "000235462",
    "totalCharge": 68
  },
  "accountBalance": 4249
}

Example Error Messages

Invalid Form Input








{
  "statusCode": 400,
  "message": [
    "item.categoryOptionId should not be empty",
    "item.category should not be empty"
  ],
  "error": "Bad Request"
}
Invalid pickUpStoreCode (Status Code: 404)



{
  "message": "Pick Up Store cannot be found"
}

GET /v1/shipment/{trackingNumber}

To retrieve the details of a specific shipment

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Name Type Required Description Example
trackingNumber string Required Tracking Number of the shipment you wish to retrieve JP319037069928

Response Parameters

Parameter Type Description Example
trackingNumber string Tracking Number of the shipment 'JP319037069928'
refNo string Tracking Number of the shipment 'AIGNITER_EO_002934'
externalOrderNumber string ExteTracking Number of the shipment '000234'
orderNotes string remarks of the shipment 'Remarks…'
orderDate string Creation Time of the shipment; at Hong Kong Time; "2021-06-25 16:57"
shipmentState string Current status of the shipment; See shipmentState 'On the way to customer'
sameDayDelivery boolean true for “Same-Day Delivery Service”;
false for “Standard Delivery Service”;		 true
pickUpDate string Pick Up Date of the shipment;
only for “Same-Day Delivery Service”;		 '2021-06-26'
deliveryDate string Delivery Date of the shipment;
only for “Same-Day Delivery Service”;		 '2021-06-27'
shipmentFee number Shipment Fee 68
additionalWeightFee number Additional Weight Fee - a surcharge for exceeding certain weight; 2
totalFee number Shipment Fee + Additional Weight Fee 70
totalCharge number Total Charge 70
paymentMethod string Payment Method 'PAID_BY_MERCHANT'
cod number Cash On Delivery Amount 100
origin object Sender Address Details [see above]
externalOrderNumber destination object Receiptient Address Details
pickUpStore object Pick Up Store Details [see above]
item object Parcels Details [see below]
statusLogs array Trackings of shipment sorted by time descendingly [see below for objects in the array]
shipmentState-GETv1
Status Description
Created 已建立
Confirmed 已確認
Passed to courier 速遞員已拎件
Not able to receive products 無法拎件
On the way to warehouse 前往貨倉中
Arrived at warehouse 到達貨倉
Sending to another warehouse 轉貨倉
On the way to customer 送貨中
Undelivered 無法送達
Completed 完成 - 已送達
Rejected 拒絕訂單
Scheduled for redeliver 將再次派送
Problem shipment 出現問題
On the way to pick up store 前往自提點中
Arrived at pick up store 到達自提點
item
Parameter Type Description Example
dimensionOption object Dimension Details [see above]
weightOption object Weight Details;
Only applicable for 'Same-Day Delivery Service';		 [see above]
actualWeight number Actual Weight of parcel (in kg);
Only applicable for 'Standard Delivery Service';		 2
adjustedWeight number Adjusted Weight of parcel (in kg) (if any) 2.3
temperatureOption object Temperature Details;
Only applicable for 'Same-Day Delivery Service'		 [see above]
categoryOption object Category Details;
Only applicable if no 'category' inputted		 [see above]
category number Category inputted;
Only applicable if no 'categoryOption' provided		 'Toys'
statusLogs
Parameter Type Description Example
time string format: 'YYYY-MM-DD HH:mm' '2021-09-27 10:34'
status string Shipment State 'Created'
remarks string (if any) 'Nobody answered the door 無人應門'

Example Response















































































{
  "shipment": {
    "trackingNumber": "JP319037070058",
    "refNo": "JUMPPOINT_EO_003012",
    "orderDate": "2021-09-07 18:42",
    "shipmentState": "On the way to customer",
    "sameDayDelivery": false,
    "shipmentFee": 28,
    "additionalWeightFee": 0,
    "totalFee": 28,
    "totalCharge": 28,
    "paymentMethod": "PAID_BY_MERCHANT",
    "cod": 0,
    "orderNotes": "fragile",
    "origin": {
      "contactName": "Peter Chan",
      "contactPhone": "98745632",
      "address": "新蒲崗大有街31號善美工業大廈"
    },
    "destination": {
      "contactName": "Peter Chan",
      "contactPhone": "98745632"
    },
    "pickUpStore": {
      "code": "KLE48",
      "alias": "新蒲崗自提點",
      "districtEn": "Wong Tai Sin",
      "districtChi": "黃大仙",
      "address": "大有街31號 善美工業大廈10樓1001室",
      "operationTime": {
        "mondayFrom": "09:00",
        "mondayTo": "18:00",
        "tuesdayFrom": "09:00",
        "tuesdayTo": "18:00",
        "wednesdayFrom": "09:00",
        "wednesdayTo": "18:00",
        "thursdayFrom": "09:00",
        "thursdayTo": "18:00",
        "fridayFrom": "09:00",
        "fridayTo": "18:00",
        "saturdayFrom": "09:00",
        "saturdayTo": "18:00",
        "sundayFrom": "09:00",
        "sundayTo": "18:00",
        "publicHolidayFrom": "09:00",
        "publicHolidayTo": "18:00"
      },
      "freeStorage": 2
    },
    "item": {
      "dimensionOption": {
        "id": "D01",
        "descriptionChi": "大: >60cm",
        "descriptionEn": "Big: >60cm"
      },
      "actualWeight": 1.3,
      "categoryOption": {
        "id": "C101",
        "descriptionChi": "文件",
        "descriptionEn": "Documents"
      }
    },
    "statusLogs": [
      {
        "time": "2021-09-08 18:39",
        "status": "On the way to customer"
      },
      {
        "time": "2021-09-08 18:39",
        "status": "Passed to courier"
      },
      {
        "time": "2021-09-08 18:39",
        "status": "Arrived at warehouse"
      }
    ]
  }
}

Example Error Messages

Invalid trackingNumber (Status Code: 404)



{
  "message": "Shipment cannot be found"
}

Dates

GET /v1/date/valid

To retrieve lists of valid Pick-Up and Delivery Dates

Notes

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Example Response

























{
  "pickUpDates": [
    "2021-09-28",
    "2021-09-29",
    "2021-09-30",
    "2021-10-04",
    "2021-10-05",
    "2021-10-06",
    "2021-10-07"
  ],
  "deliveryDates": [
    "2021-09-28",
    "2021-09-29",
    "2021-09-30",
    "2021-10-02",
    "2021-10-04",
    "2021-10-05",
    "2021-10-06",
    "2021-10-07",
    "2021-10-08",
    "2021-10-09",
    "2021-10-11",
  ]
}

Item

GET /v1/item/options

To retrieve lists of valid item options

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Example Response

















































































































{
    "options": {
        "categoryStandard": [
            {
                "id": "C101",
                "descriptionEn": "Documents",
                "descriptionChi": "文件"
            },
            {
                "id": "C102",
                "descriptionEn": "Electronic Products",
                "descriptionChi": "電子產品"
            },
            {
                "id": "C103",
                "descriptionEn": "Daily Necessities",
                "descriptionChi": "日用品"
            },
            {
                "id": "C104",
                "descriptionEn": "Clothes",
                "descriptionChi": "服飾"
            },
            {
                "id": "C105",
                "descriptionEn": "Food",
                "descriptionChi": "食品"
            }
        ],
        "categorySameDay": [
            {
                "id": "C201",
                "descriptionEn": "Wine",
                "descriptionChi": "酒"
            },
            {
                "id": "C202",
                "descriptionEn": "Food",
                "descriptionChi": "食品"
            },
            {
                "id": "C203",
                "descriptionEn": "Electronic Products",
                "descriptionChi": "電子產品"
            },
            {
                "id": "C204",
                "descriptionEn": "Daily Necessities",
                "descriptionChi": "日用品"
            }
        ],
        "dimension": [
            {
                "id": "D01",
                "descriptionEn": "Big: >60cm",
                "descriptionChi": "大: >60cm"
            },
            {
                "id": "D02",
                "descriptionEn": "Medium: 31-60cm",
                "descriptionChi": "中: 31-60cm"
            },
            {
                "id": "D03",
                "descriptionEn": "Small: <30cm",
                "descriptionChi": "小: <30cm"
            }
        ],
        "temperature": [
            {
                "id": "T01",
                "descriptionEn": "Room Temperature",
                "descriptionChi": "室溫"
            },
            {
                "id": "T02",
                "descriptionEn": "0-4°C",
                "descriptionChi": "0-4度"
            },
            {
                "id": "T03",
                "descriptionEn": "-18°C",
                "descriptionChi": "-18度"
            }
        ],
        "dimensionThirdParty": [
            {
                "id": "D04",
                "descriptionEn": "Circle K: LWH < 90cm, Weight < 5kg",
                "descriptionChi": "Circle K: 長闊高總和<90cm，重<5kg"
            }
        ],
        "weight": [
            {
                "id": "W01",
                "descriptionEn": "Heavy: >10kg",
                "descriptionChi": "重: >10kg"
            },
            {
                "id": "W02",
                "descriptionEn": "Medium: 5-10kg",
                "descriptionChi": "中: 5-10kg"
            },
            {
                "id": "W03",
                "descriptionEn": "Light: <5kg",
                "descriptionChi": "輕: <5kg"
            }
        ]
    }
}

Usage

Option Type Usage
categoryStandard id used in categoryOptionId where sameDayDelivery is false
categorySameDay id used in categoryOptionId where sameDayDelivery is true
dimension id used in dimensionOptionId;
required;
dimensionThirdParty id used in dimensionOptionId;
Only valid option when sameDayDelivery is false and pick up store is from third party(Circle K);
temperature id used in temperatureOptionId;
required when sameDayDelivery is true;
weight id used in weightOptionId;
required when sameDayDelivery is true;

Pick Up Stores

GET /v1/pick-up-store/list

To retrieve lists of Pick Up Stores

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Response Parameters

Parameter Type Description Example
pickUpStores obeject[] Returned Pick Up Stores See pickUpStore

Notes

Example Response































{
  "pickUpStores": [
    {
      "code": "KLE48",
      "alias": "新蒲崗自提點",
      "districtEn": "Wong Tai Sin",
      "districtChi": "黃大仙",
      "address": "大有街31號 善美工業大廈10樓1001室",
      "operationTime": {
        "mondayFrom": "09:00",
        "mondayTo": "18:00",
        "tuesdayFrom": "09:00",
        "tuesdayTo": "18:00",
        "wednesdayFrom": "09:00",
        "wednesdayTo": "18:00",
        "thursdayFrom": "09:00",
        "thursdayTo": "18:00",
        "fridayFrom": "09:00",
        "fridayTo": "18:00",
        "saturdayFrom": "09:00",
        "saturdayTo": "18:00",
        "sundayFrom": "09:00",
        "sundayTo": "18:00",
        "publicHolidayFrom": "09:00",
        "publicHolidayTo": "18:00"
      },
      "freeStorage": 2
    }
  ]
}

Label

GET /v1/label/{trackingNumber}

To retrieve label of specific shipment

Resource URL

Resource Information

Response formats Requires authentication
application/json; charset=utf-8 Yes

Request Parameters

Name Type Required Description Example
trackingNumber string Required Tracking Number of the shipment you wish to retrieve label JP319037069928

Example Response




{
  "labelUrl": "https://jumppoint-development.s3.ap-northeast-1.amazonaws.com/expressOrderLabels/preGenDetailed/JP319037069934.pdf?AWSAccessKeyId=AKIARLW6QBGRI3STRUXC&Expires=1632380064&Signature=hk71K9wFi7UQUPt3AvemsrOWvPM%3D"
}

Example Error Messages

Invalid trackingNumber (Status Code: 404)



{
  "message": "Shipment cannot be found"
}

Webhook

jumppoint can send webhook event to notify your application when there are shipment status updates.

The payload for each webhook event will include information about the related API response. Your provided endpoint should be set up to receive a HTTP POST request, and must always return a 200 HTTP response.

Configuring your Webhooks Settings

You can register your webhook endpoint (URL) by inputting webhookUrl in your POST /v1/shipment requests.

We recommend returning a 200 HTTP response immediately or we will consider the webhook POST action to have failed.

Webhook Events

Shipment's tracking status changed

When your shipment's tracking status changed, you'll get the event payload as below:






{
  "time": "2021-09-27 10:34",
  "trackingNumber": "JP319037069928",
  "status": "Completed"
}
Explanation
Parameter Type Description Example
time string format: 'YYYY-MM-DD HH:mm' '2021-09-27 10:34'
trackingNumber string Tracking Number of the shipment JP319037069928
status string Updated status of the shipment See Shipment State

Item's tracking status changed

When your item's tracking status changed, you'll get the event payload as below:







{
  "time": "2021-09-27 10:34",
  "shipmentTrackingNumber": "JP319037069928",
  "itemTrackingNumber": "JP319037069931",
  "itemState": "On the way to customer"
}

Another Example:








{
  "time": "2021-09-27 10:34",
  "shipmentTrackingNumber": "JP319037069928",
  "itemTrackingNumber": "JP319037069931",
  "itemState": "Undelivered",
  "remarks": "Nobody answered the door 無人應門"
}
Explanation
Parameter Type Description Example
time string format: 'YYYY-MM-DD HH:mm' '2021-09-27 10:34'
shipmentTrackingNumber string Tracking Number of the shipment JP319037069928
itemTrackingNumber string Tracking Number of the item JP319037069931
itemState string Updated status of the shipment See Item State
remarks string (if any) 'Nobody answered the door 無人應門'