Jumppoint Open API v3 Documentation

--- title: 'Jumppoint Open API v3 Documentation' tags: open-api --- Jumppoint Open API v3 Documentation === # Table of Contents [TOC] --- # 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 * We use Bearer Authentication to authenticate requests. You will need to include `Authorization: Bearer <API Access Token>` in the header for all requests. * Before you get started, you will need to get your API Access Tokens from our Business Development Team for our Production and Sandbox environments. * Your token should not be publicly accessible. * ## Error Message ```json= { "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 ```json= { "statusCode": 429, "message": "ThrottlerException: Too Many Requests" } ``` # API ## Changelogs * Support creation of freight and cold chain shipments * Remove bulk import shipment endpoint * Refactor shipment data structure and fetching endpoints ## Shipment ### `POST /v3/shipment` :::info To create a Shipment (with a list of items) ::: #### Resource URL * Sandbox: `POST https://staging.open-api.jumppoint.io/v3/shipment` * Production: `POST https://open-api.jumppoint.io/v3/shipment` #### Resource Information | Request Content-Type | Response formats | Requires authentication | | -------- | -------- | -------- | | `application/json` | `application/json; charset=utf-8` | Yes | #### Body Parameters | Name | Type | Required | Description | Example | | -------- | -------- | -------- | -------- | -------- | | externalOrderNumber | string | No | Order number for your own reference | A00001 | | shipmentCategory | string | Yes | Specify the type of your shipment See [below](#shipment-category-v3) | `parcel` / `freight` | | origin | object | Yes | Sender information | Parcel to-door: See [below](#origin-parcel-todoor-POSTv3) Parcel drop-off: See [below](#origin-parcel-dropoff-POSTv3) Freight: See [below](#origin-freight-POSTv3) | | destination | object | Yes | Receipient information | Parcel to-door: See [below](#destination-parcel-todoor-POSTv3) Parcel drop-off: See [below](#destination-parcel-store-POSTv3) Freight: See [below](#destination-freight-POSTv3) | | items | array | Yes | Parcel details | See [below](#item-POSTv3) | | pickUpDate | string | Yes | Hong Kong Time Format: YYYY-MM-DD; Must be after today, excluding Sunday and public holidays | "2021-12-31" | | pickUpTimeslot | string | Yes | Hong Kong Time Format: HH:mm-HH:mm; | "10\:30-13\:00" or null for not designated See [below](#pick-up-timeslots) | | deliveryDate | string | No | Hong Kong Time Format: YYYY-MM-DD; Must be after pickUpDate, excluding Sunday and public holidays | "2021-12-31" | | deliveryTimeslot | string | No | Hong Kong Time Format: HH:mm-HH:mm; | "15\:00-18\:00" or null for not designated See [below](#delivery-timeslots) | | paymentMethod | string | Yes | See [below](#payment-method) | "PAID_BY_RECEIVER" | | cod | decimal(8,2) | Required if paymentMethod is 'PAID_BY_MERCHANT_COD' or 'CASH_ON_DELIVERY' | Amount you wish to receive from receiptient excluding the shipment fee | 200 | | notes | string | No | Special note to be marked on the shipment Maximum: 250 characters | Fragile - handle with care | | webhookUrl | string | No | See [*Webhook*](#Webhook); Maximum: 250 characters | 'https://c977-61-244-155-9.ngrok.io/webhook/jumppoint' | | webhookUrl | string | No | See [*Webhook*](#Webhook); Maximum: 250 characters | 'https://c977-61-244-155-9.ngrok.io/webhook/jumppoint' | ##### origin-parcel-todoor-POSTv3 | 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' | ##### origin-parcel-dropoff-POSTv3 | Name | Type | Required | Description | Example | | -------- | -------- | -------- | -------- | -------- | | contactName | string | Yes | Maximum: 30 characters | 'Peter Chan' | | contactPhone | string | Yes | 8 digits | '98745632' | | store | string | Yes | Get from [`GET /pick-up-store/list?isDropOff=1`](#GET-v3pick-up-storelist) | 'HKPANY' ##### origin-freight-POSTv3 | 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' | | freightType | string | Yes | See [below](#freight-type) | 'b2b' | | addressType | string | Yes | b2b options: See [below](#address-type-b2b) shuttling options: See [below](#address-type-shuttling) | 'airport' ##### destination-parcel-todoor-POSTv3 | 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 | Yes | Maximum: 250 characters | '新蒲崗大有街31號善美工業大廈' | floor | string | Yes | Maximum: 10 characters | '10' | | room | string | Yes | Maximum: 10 characters | '01' | ##### destination-parcel-store-POSTv3 | Name | Type | Required | Description | Example | | -------- | -------- | -------- | -------- | -------- | | contactName | string | Yes | Maximum: 30 characters | 'Peter Chan' | | contactPhone | string | Yes | 8 digits | '98745632' | | store | string | Yes | Get from [`GET /pick-up-store/list`](#GET-v3pick-up-storelist) | 'OK123' ##### destination-freight-POSTv3 | 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' | | freightType | string | Yes | See [below](#freight-type) | 'b2b' | | addressType | string | Yes | b2b options: See [below](#address-type-b2b) shuttling options: See [below](#address-type-shuttling) | 'airport' ##### item-POSTv3 | Name | Type | Required | Description | Example | | -------- | -------- | -------- | -------- | -------- | | externalOrderNumber | string | No | Maximum: 50 characters | '000235462' | | dimension | string | Yes | See [below](#item-dimension) | 'D01' | | actualWeight | number | Required for standard parcel delivery (i.e. no delivery date specified) in kg; | DECIMAL(8,2) | 2.15 | weight | string | Required for any other types of delivery | See [below](#item-weight) | 'W01' | | temperature | string | Required | See [below](#item-temperature) | 'T01' | | category | string | Required if no `categoryOther` provided | For parcel standard delivery: See [below](#item-category-parcel-standard) For other types of delivery: See [below](#item-category-non-parcel-standard) | 'C203' | | categoryOther | string | Required if no `category` provided | Maximum: 10 characters | 'Toys' | | notes | string | No | Maximum: 250 characters | "call customer 30 mins before delivery" | ##### pick-up-timeslots ###### Parcel pick-up timeslots | Value | Temperature | | -------- | -------- | | null | Room-temperature | | null | Cold-chain | ###### Freight pick-up timeslots | Value | Temperature | | -------- | -------- | | null | Room-temperature | | null | Cold-chain | ##### delivery-timeslots ###### Parcel delivery timeslots | Value | Temperature | | -------- | -------- | | null | Room-temperature | | 11:00-16:00 | Cold-chain Express only | | 16:00-20:00 | Cold-chain Express only | | null | Cold-chain | ###### Freight delivery timeslots | Value | Temperature | | -------- | -------- | | null | Room-temperature | | 11:00-16:00 | Cold-chain Express only | | 16:00-20:00 | Cold-chain Express only | | null | Cold-chain | #### Example Request Body ###### Self-pickup parcel (please via [GET /v3/pick-up-store/list](#Pick-Up-Stores) to check the "store" code of the available pickup stores ) ```json= { "externalOrderNumber": "dummySE", "shipmentCategory": "parcel", "origin":{ "contactName": "Kelvin Sender", "contactPhone": "99999999", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "destination":{ "contactName": "tester", "contactPhone": "99999999", "store": "SE0000" }, "items":[ { "externalOrderNumber": "dummySE01", "dimension":"D01", "actualWeight": 2, "temperature": "T01", "categoryOther": "Something", "notes": "testing" } ], "pickUpDate": "2025-10-16", "paymentMethod": "PAID_BY_MERCHANT", "notes":"testing" } ``` ###### Non-temperature control standard parcel ```json= { "externalOrderNumber": "non-temp-standard-parcel-1", "shipmentCategory": "parcel", "origin":{ "contactName": "Kelvin Sender", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "destination":{ "contactName": "Kelvin Receiver", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "items":[ { "externalOrderNumber": "item-001", "dimension":"D01", "actualWeight": 2, "temperature": "T01", "categoryOther": "Something", "notes": "nice one" }, { "externalOrderNumber": "item-002", "dimension":"D01", "actualWeight": 2, "temperature": "T01", "categoryOther": "Something", "notes": "nice one2" } ], "pickUpDate": "2024-12-14", // "pickUpTimeslot": "", // "deliveryDate": "", // "DeliveryTimeslot": "", "paymentMethod": "PAID_BY_MERCHANT", "notes":"hello testing standard" // "webhookUrl":"" } ``` ###### Non-temperature control express parcel ```json= { "externalOrderNumber": "non-temp-express-parcel-1", "shipmentCategory": "parcel", "origin":{ "contactName": "Kelvin Sender", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "destination":{ "contactName": "Kelvin Receiver", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "items":[ { "externalOrderNumber": "express-item-001", "dimension":"D01", "actualWeight": 2, "temperature": "T01", "categoryOther": "Something", "notes": "nice one" }, { "externalOrderNumber": "express-item-002", "dimension":"D01", "actualWeight": 2, "temperature": "T01", "categoryOther": "Something", "notes": "nice one2" } ], "pickUpDate": "2024-12-16", // "pickUpTimeslot": "", "deliveryDate": "2024-12-16", // "DeliveryTimeslot": "", "paymentMethod": "PAID_BY_MERCHANT", "notes":"hello testing standard" // "webhookUrl":"" } ``` ###### Temperature control express parcel ```json= { "externalOrderNumber": "temp-express-parcel-1", "shipmentCategory": "parcel", "origin":{ "contactName": "Kelvin Sender", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "destination":{ "contactName": "Kelvin Receiver", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "items":[ { "externalOrderNumber": "temp-express-item-001", "dimension":"D01", "actualWeight": 2, "temperature": "T02", "categoryOther": "Something", "notes": "nice one" }, { "externalOrderNumber": "temp-express-item-002", "dimension":"D01", "actualWeight": 2, "temperature": "T02", "categoryOther": "Something", "notes": "nice one2" } ], "pickUpDate": "2024-12-14", // "pickUpTimeslot": "", "deliveryDate": "2024-12-16", // "DeliveryTimeslot": "", "paymentMethod": "PAID_BY_MERCHANT", "notes":"hello testing express" // "webhookUrl":"" } ``` ###### Temperature control same-day parcel ```json= { "externalOrderNumber": "temp-sameday-parcel-1", "shipmentCategory": "parcel", "origin":{ "contactName": "Kelvin Sender", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "destination":{ "contactName": "Kelvin Receiver", "contactPhone": "67891234", "address":"新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "items":[ { "externalOrderNumber": "temp-express-item-001", "dimension":"D01", "actualWeight": 2, "temperature": "T02", "categoryOther": "Something", "notes": "nice one" }, { "externalOrderNumber": "temp-express-item-002", "dimension":"D01", "actualWeight": 2, "temperature": "T02", "categoryOther": "Something", "notes": "nice one2" } ], "pickUpDate": "2024-12-16", // "pickUpTimeslot": "", "deliveryDate": "2024-12-16", // "DeliveryTimeslot": "", "paymentMethod": "PAID_BY_MERCHANT", "notes":"hello testing same-day" // "webhookUrl":"" } ``` #### Example Response ```json= { "status": "Success", "data": { "shipment": { "refNo": "AIGNITER_EO_011244", "trackingNumber": "JP319037246154", "origin": { "contactName": "Kelvin Sender", "contactPhone": "67891234", "address": "新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "destination": { "contactName": "Kelvin Receiver", "contactPhone": "67891234", "address": "新蒲崗大有街31號善美工業大廈", "floor": "10", "room": "A" }, "shipmentCategory": "parcel", "temperature": "non", "speed": "standard", "state": "created", "createdAt": "2024-12-16 15:52", "pickUpDate": "2024-12-17", "pickUpTimeslot": "10:30-13:30", "deliveryDate": "Invalid date", "deliveryTimeslot": "15:00-18:00", "paymentMethod": "PAID_BY_MERCHANT", "shipmentFee": 27, "additionalWeightFee": 0, "totalFee": 27, "totalCharge": 27, "items": [ { "trackingNumber": "JP319037246154", "externalOrderNumber": "item-001", "waybillTrackingNumber": "JP319037246154", "state": "created", "statusLogs": [ { "time": "2024-12-16 15:52", "status": "Created" } ], "dimension": "D01", "temperature": "T01", "categoryOther": "Something", "actualWeight": 2, "cargoValue": null, "notes": "nice one" }, { "trackingNumber": "JP319037246173", "externalOrderNumber": "item-002", "waybillTrackingNumber": "JP319037246173", "state": "created", "statusLogs": [ { "time": "2024-12-16 15:52", "status": "Created" } ], "dimension": "D01", "temperature": "T01", "categoryOther": "Something", "actualWeight": 2, "cargoValue": null, "notes": "nice one2" } ] }, "amountDeducted": true, "accountBalance": 99779064.99 } } ``` --- ### `GET /v3/shipment/{trackingNumber}` :::info To retrieve the details of a specific shipment ::: #### Resource URL * Sandbox: `GET https://staging.open-api.jumppoint.io/v3/shipment/{trackingNumber}` * Production: `GET https://open-api.jumppoint.io/v3/shipment/{trackingNumber}` #### Resource Information | Response formats | Requires authentication | | -------- | -------- | | `application/json; charset=utf-8`| Yes | #### Request Parameters | Name | Type | Required | Description | Example | | -------- | -------- | -------- | -------- | -------- | | trackingNumber | string | Yes | Tracking Number of the shipment / any items belonging to the shipment you wish to retrieve | JP319037069928 | #### Response Parameters | Parameter | Type | Description | Example | | -------- | -------- | -------- | -------- | | trackingNumber | string | Tracking Number of the parent shipment | 'JP319037069928' | | refNo | string | Tracking Number of the parent shipment | 'AIGNITER_EO_002934' | | externalOrderNumber | string | External Order Number (if any) | "0951358" | | orderDate | string | Creation Time of the shipment; at Hong Kong Time; | "2021-06-25 16:57" | | state | string | Current status of the shipment; See [shipmentState](#shipmentState-v3) | 'On the way to customer' | | temperature | string | `non`/`single`/`multi` | 'non' | speed | string | `same-day`/`express`/`standard` | 'express' | | pickUpDate | string | Pick Up Date of the shipment | '2021-06-26' | | deliveryDate | string | Delivery Date of the shipment| '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](#payment-method) | 'PAID_BY_MERCHANT' | | cod | decimal(8,2) | Cash On Delivery Amount | 100 | | notes | string | Order Notes (if any) | "call customer before delivery" | | origin | object | [Sender Address Details](#origin) | *[see below]* | | destination | object | [Receiptient Address Details](#destination) | *[see below]* | | items | Array | [Item Details](#item-v3) | *[see below]* | | statusLogs | array | [Trackings of shipment sorted by time descendingly](#statusLogs) | *[see below for objects in the array]* | #### origin-v3 | Parameter | Type | Description | Example | | -------- | -------- | -------- | -------- | | contactName | string | Name of sender | 'Peter Chan' | | contactPhone | string | Phone number of sender | '98745632' | | address | string | Sender Address; Only applicable when shipment is not drop-off at Pick Up Stores; | '新蒲崗大有街31號善美工業大廈' | store | string | Drop-off store; Only applicable when shipment is drop-off at Pick Up Stores; | Get from [`GET /pick-up-store/list?isDropOff=1`](#GET-v3pick-up-storelist) | 'HKPANY' | floor | string | Floor number of sender address (if any); Only applicable when shipment is not delivering to Pick Up Stores; | '10' | | room | string | Floor number of sender address (if any); Only applicable when shipment is not delivering to Pick Up Stores; | '01' | | freightType | string | Only with freight shipment | 'b2b' | | addressType | string | Only available with freight shipment | 'hotel_receiving_department' #### destination-v3 | 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' | | freightType | string | Only applicable with freight shipment | 'b2b' | | addressType | string | Only applicable with freight shipment | 'hotel_receiving_department' ##### item-v3 | Parameter | Type | Description | Example | | -------- | -------- | -------- | -------- | | trackingNumber | string | Tracking Number of the child item | "JP658854693314"| | state | string | Current status of the item; See [itemState](#itemState-v3) | 'On the way to customer' | | externalOrderNumber | string | External Order Number (if any) | "0951358" | | dimension | string | [Dimension Details](#item-dimension) | *[see below]* | | actualWeight | number | Actual Weight of parcel (in kg); Only applicable for standard parcel delivery; | 2 | | weight | string | [Weight Details](#item-weight); Applicable for any other types of deliveries | *[see below]* | | adjustedWeight | number | Adjusted Weight of parcel (in kg) (if any) | 2.3 | | adjustedLength | number | Adjusted Length of parcel (in cm) (if any) | 10.2 | | adjustedWidth | number | Adjusted Width of parcel (in cm) (if any) | 10.2 | | adjustedHeight | number | Adjusted Height of parcel (in cm) (if any) | 5.5 | | temperature | string | [Temperature Details](#item-temparature); | *[see below]* | | category | string | [Category Details](#item-category); Only applicable if no `'category'` inputted | *[see below]* | | statusLogs | array | [Trackings of item sorted by time descendingly](#statusLogs-v3) | *[see below for objects in the array]* | | notes | string | Order Notes (if any) | "call customer before delivery" | #### statusLogs-v3 | Parameter | Type | Description | Example | | -------- | -------- | -------- | -------- | | time | string | format: 'YYYY-MM-DD HH:mm' | '2021-09-27 10:34' | | status | string | [Shipment/Item State](#shipmentState-v3) | 'Created' | | remarks | string | (if any) | 'Nobody answered the door 無人應門' | #### Example Response ```json= { "shipment": { "refNo": "AIGNITER_EO_006810", "trackingNumber": "JP319037093644", "origin": { "contactName": "123", "contactPhone": "12341234", "address": "12312312313213", "freightType": "b2b", "addressType": "airport" }, "destination": { "contactName": "123", "contactPhone": "12341234", "address": "123123", "freightType": "b2b", "addressType": "airport" }, "shipmentCategory": "freight", "temperature": "non", "speed": "standard", "state": "cancelled", "createdAt": "2024-09-24 18:42", "pickUpDate": "2024-09-26", "pickUpTimeslot": "10:30-13:30", "deliveryDate": "2024-09-27", "deliveryTimeslot": "15:00-18:00", "paymentMethod": "PAID_BY_MERCHANT", "shipmentFee": 340, "additionalWeightFee": 0, "totalFee": 340, "totalCharge": 340, "items": [ { "trackingNumber": "JP319037093644", "externalOrderNumber": "123", "waybillTrackingNumber": "JP319037093644", "state": "created", "statusLogs": [ { "time": "2024-09-24 18:42", "status": "Created" } ], "dimension": "D02", "temperature": "T01", "categoryOther": "car parts", "cargoValue": 4400, "unit": "pallet", "quantity": 1, "notes": "Sensitive to moisture" }, { "trackingNumber": "JP319037093649", "externalOrderNumber": "1232", "waybillTrackingNumber": "JP319037093649", "state": "created", "statusLogs": [ { "time": "2024-09-24 18:42", "status": "Created" } ], "dimension": "D02", "temperature": "T01", "categoryOther": "motor", "cargoValue": 4400, "unit": "pallet", "quantity": 1, "notes": "Right-side up" } ] } } ``` #### Example Error Messages ##### Invalid `trackingNumber` (Status Code: 404) ```json= { "message": "Shipment cannot be found" } ``` --- --- ## Item --- ### `GET /v3/item/options` :::info To retrieve lists of valid item options ::: #### Resource URL * Sandbox: `GET https://staging.open-api.jumppoint.io/v3/item/options` * Production: `GET https://open-api.jumppoint.io/v3/item/options` #### Resource Information | Response formats | Requires authentication | | --------------------------------- | ----------------------- | | `application/json; charset=utf-8` | Yes | #### Request Parameters | Name | Type | Required | Description | Example | | -------- | -------- | -------- | -------- | -------- | | isTemperature | boolean | Required | TODO | true | | isStandard | boolean | Required | TODO | true | | itemTypeId | string | Required | TODO | TODO 'e6ce5827-3209-44f5-a989-0aa9efba8bfc' | #### Example Response ```json= { "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`; | --- ## Label ### `GET /v3/label/shipment/{trackingNumber}` :::info To retrieve list of labels for all items by PARENT shipment tracking number ::: #### Resource URL * Sandbox: `GET https://staging.open-api.jumppoint.io/v3/label/shipment/{trackingNumber}` * Production: `GET https://open-api.jumppoint.io/v3/label/shipment/{trackingNumber}` #### 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 :::warning * The download link will be expired in 10 minutes. * You should save the PDF file to your device on getting the link. * You will need to recall the API to get a new link after 10 minutes. ::: ```json= { "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**) ```json= { "message": "Shipment cannot be found" } ``` ### `GET /v3/label/item/{trackingNumber}` :::info To retrieve label for specific item by corresponding item tracking number ::: #### Resource URL * Sandbox: `GET https://staging.open-api.jumppoint.io/v3/label/item/{trackingNumber}` * Production: `GET https://open-api.jumppoint.io/v3/label/item/{trackingNumber}` #### 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 :::warning * The download link will be expired in 10 minutes. * You should save the PDF file to your device on getting the link. * You will need to recall the API to get a new link after 10 minutes. ::: ```json= { "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**) ```json= { "message": "Shipment cannot be found" } ``` --- ## Pick Up Stores ### `GET /v3/pick-up-store/list` :::info To retrieve lists of Pick Up Stores for pick-up or drop-off ::: #### Resource URL * Sandbox: `GET https://staging.open-api.jumppoint.io/v3/pick-up-store/list` * Production: `GET https://open-api.jumppoint.io/v3/pick-up-store/list` #### Resource Information | Response formats | Requires authentication | | --------------------------------- | ----------------------- | | `application/json; charset=utf-8` | Yes | #### Request Parameters | Parameter | Type | Description | Example | | -------- | -------- | -------- | -------- | | isDropOff | boolean | If true,return Pick Up Stores available for drop off | See [pickUpStore](#pickUpStore) | | isPickUp | boolean | If true,return Pick Up Stores available for pick up | See [pickUpStore](#pickUpStore) | #### Response Parameters | Parameter | Type | Description | Example | | -------- | -------- | -------- | -------- | | pickUpStores | obeject[] | Returned Pick Up Stores | See [below](#pickUpStore) | #### 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](#[pickUpStoreCompany])]* | operationTime | object | Operation Time of Pick Up Store | *[see [operationTime](#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 | |isCashReceipt | boolean |Cash Receipt service availability at pick up store | true | |isDropOff | boolean | Drop Off service availability at pick up store | false | |isPickUp | boolean | Pick Up service availability at pick up store | false | #### 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' | #### Notes :::warning * `code` used as `pickUpStoreCode` in [`POST /v3/shipment`](#Create-a-Shipment-POST-v3shipment) * `operationTime` are in local Hong Kong Time ::: #### Example Response ```json= { "pickUpStores": [ { "id": "21fb72a1-b59b-433c-9045-c4321d02d3b2", "code": "HKI10", "alias": "樹熊屋自取站", "contactPhone": "90827761", "externalRouteCode": null, "phoneAreaCode": "852", "area": { "en": "", "zh": "", "sc": "", "full": "" }, "district": { "en": "", "zh": "", "sc": "", "full": "" }, "region": { "en": "", "zh": "", "sc": "", "full": "" }, "address": "西環德輔道西343號均益2期地下10號舖（近商場干諾道西出入口）", "pickUpStoreCompany": null, "operationTime": { "monday": { "from": "13:00", "to": "19:00", "isClosed": false }, "tuesday": { "from": "13:00", "to": "19:00", "isClosed": false }, "wednesday": { "from": "13:00", "to": "19:00", "isClosed": false }, "thursday": { "from": "13:00", "to": "19:00", "isClosed": false }, "friday": { "from": "13:00", "to": "19:00", "isClosed": false }, "saturday": { "from": "13:00", "to": "19:00", "isClosed": false }, "sunday": { "from": null, "to": null, "isClosed": true }, "publicHoliday": { "from": null, "to": null, "isClosed": true } }, "freeStorage": 2, "isDropOff": false, "isReturnDropOff": false, "isPickUp": true, "isCashReceipt": true } ] } ``` --- # Tables ## Common Constants ##### shipmentState-v3 | 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 | 到達自提點 | --- #### itemState-v3 | 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 | 到達自提點 | --- #### shipment-category | Value | Description | | -------- | -------- | | parcel | Parcel | | freight | Freight | --- #### freight-type | Value | Description | | -------- | -------- | | b2b | B2B | | shuttling | Shuttling | --- #### address-type ##### address-type-b2b | Value | Description | | -------- | -------- | | hotel_receiving_department | Hotel receiving department | | supermarket_receiving_department | Supermarket receiving department | | centralised_warehouse | Centralised warehouse | | store | Store | | public_warehouse | Public warehouse | | private_warehouse | Private warehouse | | airport | Airport | | pier | Pier | | others | Other | ##### address-type-shuttling | Value | Description | | -------- | -------- | | hk | Hong Kong Island | | kl | Kowloon | | nt | New Territories | --- #### item-dimension | Value | Description | | -------- | -------- | | D01 | Big: >60cm | | D02 | Medium: 31-60cm | | D03 | Small: <30cm | | D04 | Circle K: LWH < 90cm, Weight < 5kg | --- #### item-weight | Value | Description | | -------- | -------- | | W01 | Heavy: >10kg | | W02 | Medium: 5-10kg | | W03 | Light: <5kg | --- #### item-temperature | Value | Description | | -------- | -------- | | T01 | Room Temperature| | T02 | 0-4°C | | T03 | -18°C | | T04 | 17-20°C | --- #### item-cateogry ##### item-cateogry-parcel-standard | Value | Description | | -------- | -------- | | C101 | Documents | | C102 | Electronic Products | | C103 | Daily Necessities | | C104 | Clothes | | C105 | Food | | C106 | Alcohol | ##### item-cateogry-non-parcel-standard | Value | Description | | -------- | -------- | | C201 | Wine | | C202 | Food | | C203 | Electronic Products | | C204 | Daily Necessities | --- #### payment-method | 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 | --- # 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 /v3/shipment`](#POST-v3shipment) requests. :::warning 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: ```json= { "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](#shipmentState-v3) | ### Item's tracking status changed When your item's tracking status changed, you'll get the event payload as below: ```json= { "time": "2021-09-27 10:34", "shipmentTrackingNumber": "JP319037069928", "itemTrackingNumber": "JP319037069931", "itemState": "On the way to customer" } ``` Another Example: ```json= { "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](#itemState-v3) | | remarks | string | (if any) | 'Nobody answered the door 無人應門' |