Jumppoint International Open API Spec

# Jumppoint International Open API Spec # Overview All API endpoints listed in this documentation are relative to Production: https://open-api.intl.jumppoint.io/ Sandbox: https://staging.open-api.intl.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. To obatin the API Access Token, use the following API. POST /login #### Body Parameters | Field | Type | Required | Description | | -------- | ------ | -------- | ----------------------- | | username | String | Yes | API user login name | | password | String | Yes | API user login password | Request a new OAuth Bearer Access Token, please ensure the following flow is implemented on your end: 1. Generate new access token. 2. Store the access token and expiration info in storage 3. Attach the access token with every API request in the HTTP request 4. Acquire a new access token after the token expired. ##### Sample Request: ```json= { "username": "string", "password": "string" } ``` #### Success response: | Field | Type | Description | | ----------- | ------- | ----------------------------------------------------------------------------------------------- | | accessToken | String | OAuth Bearer access token to be included in the Authorization HTTP header for all API requests. | | expiresIn | Integer | The number of seconds at which the access token will expire. | ##### Sample Response: ```json= { "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9", "expiresIn": 86400 } ``` ##### Error response: ```json= { "status": false, "message": "Incorrect login email or password. Please try again." } ``` # Create Booking POST /booking ##### Request Parameters | Name | Type | Required | Description | Example | | -------------------- | ------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | | referenceNo | string | Yes | Your own customsize reference number of the booking | Ref12345 | | webhookURL | string | No | A custom webhook url instead of the default merchant webhook url | https://www.webhookurl/trigger-webhook/00001 | | transportMode | string | Yes | What kind of transpotation to use in this shipment Valid transpotation are: Air Sea Land | Air | | pickUp | boolean | Yes | True = need Pickup service False = no need Pickup service | TRUE | | pickUpBagNo | string | No | The bag/groupping number of the bag. Optional. | N34512 | | pickUpDate | string | Required if pickUp is True | Pickup date in ISO 8601 format, required only when pickup is true MUST either be a current date or a future date within 2 weeks. (Sunday and Public Holidays are not available) | 2023-03-30 | | pickUpSlot | string | Required if pickUp is True | Preferred timeslot on pickup date, required only when pickup is true Valid time slots are: AM PM | AM | | sender | object | Yes | Origin and sender information | [See below](#Sender) | | iossNo | string | Required if receiver in European Countries | IOSS number applied for VAT registration in EU Member States. it must input in pair with iossCountry \*If you do not have IOSS number, please contact us for the register service | IM345654345876 | | iossCountry | string | Required if receiver in European Countries | Country of the IOSS number, must input in pair with iossNo | Germany | | receiver | object | Yes | Destination and receiver information | [See below](#Receiver) | | packageValue | number | Yes | Declared value of the package, must input in pair with packageValueCurrency | 200 | | packageValueCurrency | string | Yes | Currency of the declared value is in, in ISO 4217 format. Must input in pair with packageValue MUST match the currecy of destination countryCode | USD | | paymentMethod | string | Yes | Valid payment method are: COD : Cash on Delivery PP : Prepaid | COD | | codValue | number | Required if paymentMethod is COD | Cash on delivery value, required only when payment method is "COD". Precision up to 2 d.p. Must input in pair with codValueCurrency | 300 | | codValueCurrency | string | Required if paymentMethod is COD | Currency of the cash on delivery value is in, in ISO 4217 format. Required only when payment method is "COD". Must input in pair with codValue | THB | | package | object | Yes | Package information | [See below](#Package) | | shipmentTerm | string | Required if destination country is China | Represents "international commercial terms" (Incoterms). Availd terms are: DDP DDU EXW FOB CIF CPT | DDU | | productType | string | Yes | Package contains sensitvie products e.g. battery or not Valid type are: General Sensitive | General | | packageAmount | string | No | Number of Product within the package. Must be integer. | 2 | | cargoValue | number | No | The total sales amount of all products under the same package (total value). Precision up to 2 d.p. | | | freightShippingFee | number | No | Shipping fee charged by the platform. Precision up to 2 d.p. | | | insuranceValue | number | No | Insurance value of the packages. Precision up to 2 d.p. Must input together with insuranceCurrency & insuranceType | | | insuranceCurrency | string | No | Currency of the insurance value is in, in ISO 4217 format. Precision up to 2 d.p. Must input together with insuranceValue & insuranceType. | | | insuranceType | string | No | Type of insurance. Must input together with insuranceValue & insuranceCurrency | | | products | array | Yes | Item details for custom clearance process | [See below](#Products) | ##### Sender | Name | Type | Required | Description | Example | | ----------- | ------ | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | name | string | Yes | Name of sender | Sandy Lee | | company | string | Yes | Company of sender | DFE Logistic Limited | | address | string | Yes | Address of sender - Please be as detail as possible | 18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong | | district | string | No | District of the sender location | Kowloon City | | city | string | No | City of the sender address is located at Validation: city has to be in corresponding province and country Please refer to the city-states-country mapping in: [https://dr5hn.github.io/countries-states-cities-database/ ](https://dr5hn.github.io/countries-states-cities-database/)(if there is no City in the province, please leave the field empty) | Kowloon City | | province | string | Yes | Province of the sender address is located at Validation: province has to be in corresponding country Please refer to the city-states-country mapping in: [https://dr5hn.github.io/countries-states-cities-database/](https://dr5hn.github.io/countries-states-cities-database/) | Kowloon City | | countryCode | string | Yes | Country of the sender address is located at, in ISO-2 format Validation: exact match with one of the country code in below database Please refer to the city-states-country mapping in: [https://dr5hn.github.io/countries-states-cities-database/](https://dr5hn.github.io/countries-states-cities-database/) | HK | | postcode | string | Yes | Postal code of the sender address is located at | 00000 | | phone | string | Yes | Phone number of sender Please provide the sender calling code & phone no. (must match origin phone no. format as follows: +852-37069876) | +852-64352654 | | email | string | No | Email of sender | 123@jumppoint.io | | taxNo | string | No | Tax number of sender, must input in pair with taxNoType | X02068045 | | taxNoType | string | Required if taxNo has input | Type of tax number of sender, must input in pair with taxNo Vaild taxNo type are: Social Security Number (SSN) Tax Identification Number (TIN) VAT Number ID Number LVG Number | Social Security Number (SSN) | | idNo | string | No | Identity number of sender, must input in pair with idNoType | X02068045 | | idNoType | string | Required if idNo has input | Type of identity number of sender, must input in pair with idNo Valid idNo type are: Tax card Driver ID Passport CP passport | Passport | ##### Receiver | Name | Type | Required | Description | Example | | ----------- | ------ | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | name | string | Yes | Name of receiver | Sandy Lee | | company | string | Yes | Company of receiver | DFE Logistic Limited | | address | string | Yes | Address of receiver - Please be as detail as possible | 18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong | | district | string | No | District of the receiver location | Kowloon City | | city | string | No | City of the receiver address is located at Validation: city has to be in corresponding province and country Please refer to the city-states-country mapping in: [https://dr5hn.github.io/countries-states-cities-database/ ](https://dr5hn.github.io/countries-states-cities-database/)(if there is no City in the province, please leave the field empty) | Kowloon City | | province | string | Yes | Province of the receiver address is located at Validation: province has to be in corresponding country Please refer to the city-states-country mapping in: [https://dr5hn.github.io/countries-states-cities-database/](https://dr5hn.github.io/countries-states-cities-database/) | Kowloon City | | countryCode | string | Yes | Country of the receiver address is located at, in ISO-2 format Validation: exact match with one of the country code in below database Please refer to the city-states-country mapping in: [https://dr5hn.github.io/countries-states-cities-database/](https://dr5hn.github.io/countries-states-cities-database/) | HK | | postcode | string | Yes | Postal code of the receiver address is located at | 00000 | | phone | string | Yes | Phone number of receiver Please provide the receiver calling code & phone no. (must match origin phone no. format as follows: +852-37069876) | +852-64352654 | | email | string | No | Email of receiver | 123@jumppoint.io | | taxNo | string | No | Tax number of receiver, must input in pair with taxNoType | X02068045 | | taxNoType | string | Required if taxNo has input | Type of tax number of receiver, must input in pair with taxNo Vaild taxNo type are: Social Security Number (SSN) Tax Identification Number (TIN) VAT Number ID Number | Social Security Number (SSN) | | idNo | string | No | Identity number of receiver, must input in pair with idNoType | X02068045 | | idNoType | string | Required if idNo has input | Type of identity number of receiver, must input in pair with idNo Valid idNo type are: Tax card Driver ID Passport CP passport | Passport | ##### Package | Name | Type | Required | Description | Example | | ------------ | ------ | -------- | ---------------------------------------------------------- | ------- | | height | number | No | Height of the package in cm. Must be integer. | 30 | | length | number | No | length of the package in cm. Must be integer. | 20 | | width | number | No | Width of the package in cm. Must be integer. | 20 | | volumeWeight | number | No | Volume weight of the package in kg. Precision up to 3 d.p. | 18.56 | | grossWeight | number | Yes | Gross weigth of the package in kg. Precision up to 3 d.p. | 20.78 | ##### Products | Name | Type | Required | Description | Example | | ------------- | ------ | -------- | ------------------------------------------------------------ | -------------------------------------------------- | | descriptionEn | string | Yes | Description of product in English. | Trasformer - Toys | | descriptionOr | string | Yes | Description of product in origin language. | Trasformer - Toys | | descriptionDe | string | No | Description of product in destination language. | Trasformer - Toys | | category | string | No | Category of the product | Toy | | unitPrice | number | Yes | Unit price of product. Precision up to 2 d.p. | 40 | | priceCurrency | string | Yes | Currency of the unit price is in, in ISO 4217 format. | GBP | | quantity | number | Yes | numberNumber of this product. Must be integer. | 20 | | sku | string | No | SKU of the product | ABCC12323 | | ean | string | No | EAN of the product |5123918749122 | hsCode | string | No | HS code of product | H5234 | | brand | string | No | Brand of product | ABC | | saleUrl | string | No | Sale platform Url | [https://www.google.com/](https://www.google.com/) | | batteryType | string | No | Type of batteries contain in the product | PI968 - lithium metal batteries | | batteryAmount | number | No | Number of batteries contain in the product. Must be integer. | 4 | ##### Example Request Body ```json= { "referenceNo": "REF00001008", "webhookURL": "https://www.webhookurl/trigger-webhook/00001", "transportMode": "Air", "pickUp": true, "pickUpBagNo": "BAG12345", "pickUpDate": "2023-04-14", "pickUpSlot": "PM", "sender": { "name": "Tommy Lee", "company": "Jumppoint Logistic Limited", "address": "香港葵涌大連排道金星工業大廈地下", "district": "葵涌", "city": "Kwai Tsing", "province": "Kwai Tsing", "countryCode": "HK", "postcode": "00000", "phone": "+852-55677865", "email": "tommylee@jumppoint.io", "taxNo": "GGWP3452", "taxNoType": "Social Security Number (SSN)", "idNo": "DDWP33441", "idNoType": "Passport" }, "receiver": { "name": "Jerry Lee", "company": "Aiginter Technologies Limited", "address": "322/16 Biz Galleria, Nuanchan, Bueng Kum, Bangkok, Thailand", "district": "Bueng Kum", "city": "Bangkok", "province": "Bangkok", "countryCode": "TH", "postcode": "10230", "phone": "+66-892405092", "email": "jerrylee@jumppoint.io", "taxNo": "GGWP46677", "taxNoType": "Social Security Number (SSN)", "idNo": "DDWP7734432", "idNoType": "Passport" }, "packageValue": 2557, "packageValueCurrency": "THB", "paymentMethod": "COD", "codValue": 25, "codValueCurrency": "THB", "package": { "height": 23, "lenght": 15, "width": 14, "volumeWeight": 22, "grossWeight": 25.2 }, "shipmentTerm": "DDP", "productType": "General", "packageAmount": 1, "cargoValue": 1, "products": [ { "descriptionEn": "T-Shirt", "descriptionOr": "strinT-Shirtg", "descriptionDe": "เสื้อแจ็กเกต", "unitPrice": 254, "priceCurrency": "THB", "quantity": 20, "hsCode": "Hr53", "brand": "Lego", "saleUrl": "http://www.google.com", "batteryType": "PI966 - Lithium ion batteries packed with equipment", "batteryAmount": 1 } ] } ``` ##### Example Response ###### Sucessfully Created (Status Code: 200) ```json= { "status": true, "data": {} } ``` ##### Example Error Messages ###### Duplicated Reference No (Status Code: 400) ```json= { "status": false, "message": "Errors: referenceNo: Reference No is already taken" } ``` ###### Incorrect Currency (Status Code: 400) ```json= { "status": false, "message": "Errors: packageValueCurrency: Declared Value Currency needs to match with destination currency" } ``` # Get Shipments Info GET /shipments?orderNo={orderNo} or GET /shipments?ref={refNo} ##### Request Parameters | Name | Type | Description | Example | | ------- | ------ | ----------------------------------------------------- | -------------- | | orderNo | string | Order Number of the shipment you wish to retrieve | JPTH1931219700 | | ref | string | Reference Number of the shipment you wish to retrieve | Return123123 | ##### Response Parameters | Name | Type | Description | Example | | ------------------ | --------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | | referenceNo | string | Merchant's reference number of the shipment record | Ref12345 | | orderNo | string | Order number of the shipment record | JPUS6759785254 |returnServiceDropOffCode | string | Drop off code for return service | 1451231231 | shipmentLabel | string | The url linked to the shipment label file | [https://jumppoint-international/label](https://jumppoint-international/label) | | status | string | Current status of the shipment | Order Created | | flagged | boolean | True if flagged by admin | TRUE | | origin | object | Origin information of the shipment | [See below](#origin) | | destination | object | Destination information of the shipment | [See below](#destination) | | createdAt | string | The datetime of the shipement record in ISO 8601 format | 2023-03-28T08:50:28.889Z | | pickUpDate | string | The pick-up date in ISO 8601 format | 2023-03-30T00:00:00.000Z | | deliveryDate | string | The delivery date in ISO 8601 format | 2023-04-11T00:00:00.000Z | | transportationMode | string | What kind of transpotation to use in this shipment | Air | | statusLogs | array | Trackings of shipment sorted by time descendingly | [See below](#statusLogs) | | products | array | Information of each product in the package | [See below](#products) | | productDetails | object | Dimensions of each product in the package | [See below](#productDetails) | ##### origin | Name | Type | Description | Example | | ---------------- | ------ | ------------------------------------------------------------ | ---------------------------------------------------------- | | origin | string | The address of the shipment sender | 18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong | | sender | string | The name of the shipment sender | Kelly Chan | | senderCountryIso | string | The country code of the shipment sender in ISO 3166-1 format | HK | ##### destination | Name | Type | Description | Example | | ------------------ | ------ | -------------------------------------------------------------- | --------------------------------------------- | | destination | string | The address of the shipment receiver | Apollo Beach Boulevard, Apollo Beach, FL, USA | | receiver | string | The name of the shipment receiver | Jerry Lee | | receiverCountryIso | string | The country code of the shipment receiver in ISO 3166-1 format | US | ##### statusLogs | Name | Type | Description | Example | | ----------- | ------ | --------------------------------------------------------------------------- | ------------------------ | | id | string | ID of status | 6422aa542807185d8c53015d | | name | string | Name of status | Order Created | | triggeredAt | string | The datetime of when the shipment update to this status in ISO 8601 format. | 2023-03-28T08:50:28.926Z | ##### products | Name | Type | Description | Example | | ------------- | ------ | ---------------------------------------------- | -------------------------------- | | descEn | string | Product Description in English | Trasformer - Toys | | descOL | string | Product Description in Origin Language | Trasformer - Toys | | descDest | string | Product Description in Destination Language | Trasformer - Toys | | qty | string | Quantity of this product | 7 | | batteryType | string | Type of battery contained in this product | PI965 - Lithium ion Batteries123 | | batteryAmount | string | Number of of battery contained in this product | 18 | | price | string | Selling price of this product | 99 | | currency | string | Currency of the selling price is in | USD | ##### productDetails | Name | Type | Description | Example | | -------------------- | ------ | --------------------------------------- | ------- | | productType | string | Type of product | General | | customerGrossWeight | string | Gross weight (kg) declared by customer | 80 | | customerVolumeWeight | string | Volume weight (kg) declared by customer | 50 | | chargeableWeight | string | Weight (kg) subjected to charge | 80 | | actualGrossWeight | string | Gross weight (kg) in actual | null | | actualVolumeWeight | string | Volume weight (kg) in actual | null | ##### Full shipment status | Status | Description | | ----------------------------------- | ----------- | | Order Created | 訂單創建成功 | | Order Confirmed | 訂單確認 | | Successful Pickup | 成功收件 | | Arrival at Origin Warehouse | 到達倉庫 | | Successful Export Customs Clearance | 出口清關成功 | | Departure from Origin Airport | 離開起運地機場 | | Departure from Origin Hub | 離開起運地 | | Arrival at Destination Airport | 到達目的地機場 | | Arrival at Destination Hub | 到達目的地 | | Successful Import Customs Clearance | 入口清關成功 | | Pickup by Last Mile Delivery | 派送團隊已收件 | | Arrival at Last Mile Sorting Hub | 到達分揀倉庫 | | Out For Last Mile Delivery | 外出派送 | | First Unsuccessful Delivery | 首次外出派送失敗 | | Second Unsuccessful Delivery | 再次外出派送失敗 | | Unsuccessful Delivery | 派送失敗 | | Rejected | 拒收 | | Successful Delivery | 已交付 | | Return Order Created | 返貨訂單創建成功 | | Successful Return | 退貨成功 | | Exception | 派送異常 | ##### Sample Response: ```json= { "status": true, "data": { "referenceNo": "VM0003", "orderNo": "JPUS6759785254", "shipmentLabel": "https://jumppoint-international-public-resource-dev.s3.ap-northeast-1.amazonaws.com/AMZOHK0001/shipmentLabels/shipment-labels-JPUS6759785254.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARLW6QBGRMSD3AKFH%2F20230412%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20230412T080535Z&X-Amz-Expires=60&X-Amz-Signature=9bd406c139a1cc15d86a36ee119a7698c2d8bf569115bf2d3dee6c7e397ce602&X-Amz-SignedHeaders=host", "status": "Order Created", "flagged": true, "origin": { "origin": "18F, Gemstar Tower, 23 Man Lok Street, Hung Hom, Hong Kong", "sender": "Kelly Chan", "senderCountry": "HK" }, "destination": { "destination": "Apollo Beach Boulevard, Apollo Beach, FL, USA", "receiver": "Jerry Lee", "receiverCountry": "US" }, "createdAt": "2023-03-28T08:50:28.889Z", "pickUpDate": "2023-03-28T00:00:00.000Z", "deliveryDate": null, "transportationMode": "Air", "statusLogs": [ { "id": "6422aa542807185d8c53015d", "name": "Order Created", "triggeredAt": "2023-03-28T08:50:28.926Z" } ], "products": [ { "descEn": "descriptionEn", "descOL": "descriptionOr", "descDest": "descriptionDe", "qty": "7", "batteryType": "PI965 - Lithium ion Batteries123", "batteryAmount": "18", "price": "99", "currency": "USD" } ], "productDetails": { "productType": "General", "customerGrossWeight": "80", "customerVolumeWeight": "50", "chargeableWeight": "80", "actualGrossWeight": null, "actualVolumeWeight": null } } } ``` ##### Example Error Messages ###### Invalid trackingNumber (Status Code: 400) ```json= { "status": false, "message": "Shipment Order not found" } ``` # Batch Shipment Order Query POST /shipments/batch ##### Request parameter | Name | Type | Required | Description | Example | | ---- | ---- | -------- | ----------- | --- | | orderNos | string | Yes |Order Numbers of the shipments you wish to retrieve | JPTH1931219700 | ##### Sample request ```json= { "orderNos":["JPTH7894446466","JPTH1868202815"] } ``` ##### Sample response ```json= { "status": true, "data": [ { "referenceNo": "REFF201326156", "orderNo": "JPTH7894446466", "status": "Exception", "origin": { "origin": "18F, Gemstar Tower, 23 Man Lok Street, Hung Hom", "sender": "Sandy Lee", "senderCountry": "HK" }, "destination": { "destination": "38836 Biz Galleria, Nuanchan, Bueng Kum", "receiver": "Tommy Chan", "receiverCountry": "TH" }, "createdAt": "2023-03-27T11:16:40.334Z", "pickUpDate": "2023-03-30T00:00:00.000Z", "deliveryDate": null, "transportationMode": "Air", "products": [ { "descEn": "Trasformer - Toys", "descOL": "Trasformer - Toys", "descDest": "ของเล่น", "qty": "30", "batteryType": "PI968 - lithium metal batteries", "batteryAmount": "4", "price": "40", "currency": "HKD" } ], "productDetails": { "productType": "Sensitive", "customerGrossWeight": "20", "customerVolumeWeight": null, "chargeableWeight": null, "actualGrossWeight": null, "actualVolumeWeight": null } }, { "referenceNo": "REFF201326157", "orderNo": "JPTH1868202815", "status": "Successful Pickup", "origin": { "origin": "18F, Gemstar Tower, 23 Man Lok Street, Hung Hom", "sender": "Sandy Lee", "senderCountry": "HK" }, "destination": { "destination": "38836 Biz Galleria, Nuanchan, Bueng Kum", "receiver": "Tommy Chan", "receiverCountry": "TH" }, "createdAt": "2023-03-27T11:26:51.652Z", "pickUpDate": null, "deliveryDate": null, "transportationMode": "Air", "products": [ { "descEn": "Trasformer - Toys", "descOL": "Trasformer - Toys", "descDest": "ของเล่น", "qty": "30", "batteryType": "PI968 - lithium metal batteries", "batteryAmount": "4", "price": "40", "currency": "HKD" } ], "productDetails": { "productType": "Sensitive", "customerGrossWeight": "20", "customerVolumeWeight": null, "chargeableWeight": null, "actualGrossWeight": null, "actualVolumeWeight": null } } ] } ``` # Batch Shipment Latest Status Query POST /shipments/batch/status-logs/latest ##### Request parameter | Name | Type | Required | Description | Example | | ---- | ---- | -------- | ----------- | --- | | orderNos | string | Yes |Order Numbers of the shipments you wish to retrieve | JPTH1931219700 | ##### Sample request ```json= { "orderNos":["JPTH7894446466","JPTH1868202815"] } ``` ##### Sample response ```json= { "status": true, "data": [ { "orderNo": "JPTH7894446466", "status": "Exception", "triggeredAt": "Exception" }, { "orderNo": "JPTH1868202815", "status": "Successful Pickup", "triggeredAt": "Successful Pickup" } ] } ``` # Batch Shipment Status Log Query POST /shipments/batch/status-logs ##### Request parameter | Name | Type | Required | Description | Example | | ---- | ---- | -------- | ----------- | --- | | orderNos | string | Yes |Order Numbers of the shipments you wish to retrieve | JPTH1931219700 | ##### Sample request ```json= { "orderNos":["JPTH7894446466","JPTH1868202815"] } ``` ##### Sample response ```json= { "status": true, "data": [ { "orderNo": "JPTH7894446466", "status": "Exception", "triggeredAt": "2023-12-22T08:32:47.000Z", "statusLogs": [ { "status": "Exception", "triggeredAt": "2023-12-22T08:32:47.000Z" }, { "status": "Order Created", "triggeredAt": "2023-12-01T11:18:26.000Z" }, { "status": "Successful Origin Outbound", "triggeredAt": "2023-03-28T23:02:00.000Z" }, { "status": "Order Confirmed", "triggeredAt": "2023-03-28T08:36:00.000Z" }, { "status": "Order Confirmed", "triggeredAt": "2023-03-28T07:36:00.000Z" }, { "status": "Order Confirmed", "triggeredAt": "2023-03-27T11:16:52.000Z" }, { "status": "Order Created", "triggeredAt": "2023-03-27T04:16:40.351Z" }, { "status": "Order Created", "triggeredAt": "2023-03-27T03:16:40.351Z" } ] }, { "orderNo": "JPTH1868202815", "status": "Successful Pickup", "triggeredAt": "2023-03-30T21:30:00.000Z", "statusLogs": [ { "status": "Successful Pickup", "triggeredAt": "2023-03-30T21:30:00.000Z" }, { "status": "Order Confirmed", "triggeredAt": "2023-03-27T11:27:00.000Z" }, { "status": "Order Created", "triggeredAt": "2023-03-27T03:26:51.668Z" } ] } ] } ``` # Get Shipment Label GET /shipments/shipment-label?orderNo={orderNo} ##### Request Payload | Name | Type | Required | Description | Example | | -------------- | ------ | -------- | ---------------------------------------------------- | -------------- | | orderNo | string | Required | Order Number of the shipment you wish to retrieve | JPTH1931219700 | ##### Sample Response ```json= { "status": true, "data": { "url": "https://jumppoint-international-public-resource-dev.s3.ap-northeast-1.amazonaws.com/AMZOHK0001/shipmentLabels/shipment-labels-JPHK3466419727.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIARLW6QBGRMSD3AKFH%2F20230328%2Fap-northeast-1%2Fs3%2Faws4_request&X-Amz-Date=20230328T091830Z&X-Amz-Expires=60&X-Amz-Signature=877632dde4f67f6a80d92d53af7b11fcdaa31a68d062c607a3901dde362297f1&X-Amz-SignedHeaders=host" } } ``` ##### Example Error Messages ###### Invalid trackingNumber (Status Code: 400) ```json= { "status": false, "message": "Shipment Order not found" } ``` # Webhooks You may register a webhook to receive order status updates from Jumppoint. ## Register and manage your webhook ### Create a webhook POST /webhooks Please save the `secret` value as it'll only appear once. ##### Request Parameters | Name | Type | Required | Description | Example | | -------------- | ------ | -------- | ---------------------------------------------------- | -------------- | | url | string | Required | The API endpoint which you intend to receive the webhook | https://example.com/webhook-receiver | ##### Sample Response ```json= { "status": true, "data": { "id": "643ee08ec3cb926799da73f4", "url": "https://example.com/webhook-receiver", "secret": "98a120ec04cb5410b2e9314e0fa0538e8f90", "createdAt": "2023-04-18T18:25:18.130Z" } } ``` ##### Example Error Messages ###### Invalid url (Status Code: 400) ```json= { "status": false, "message": "Errors: url: Invalid input: must start with \"https://\"" } ``` ### List all webhooks GET /webhooks ### Get a webhook by ID GET /webhooks/{id} ### Update a webhook by ID PUT /webhooks/{id} The new URL will take effect immediately. ##### Request Parameters | Name | Type | Required | Description | Example | | -------------- | ------ | -------- | ---------------------------------------------------- | -------------- | | url | string | Required | The API endpoint to replace with | https://example.com/new-webhook-receiver | ##### Example Error Messages ###### Invalid url (Status Code: 400) ```json= { "status": false, "message": "Errors: url: Invalid input: must start with \"https://\"" } ``` ### Delete a webhook by ID DELETE /webhooks/{id} The deletion will take effect immediately. ## Handle webhook requests You'll need to have a RESTful web server to recieve webhook requests. The endpoint URL receiving the webhook must use the POST method. ### Security Jumppoint sends all webhook requests with the `X-Jumppoint-Signature` header. Its value is calculated by the HMAC of the raw body using the SHA-256 hash function and the secret shared to you on creation of the webhook record. To validate the request is actually sent from Jumppoint, calculate the HMAC and compare the value with the signature. ##### Example code ```js const sig = req.get('X-Jumppoint-Signature'); const hmac = crypto.createHmac('sha256', '98a120ec04cb5410b2e9314e0fa0538e8f90'); // the secret hmac.update(JSON.stringify(req.body)); const digest = hmac.digest('hex'); if (sig === digest) { res.send("success"); } ``` Learn more about [HMAC signature verification](https://hookdeck.com/webhooks/guides/how-to-implement-sha256-webhook-signature-verification#using-hmac-signature-verification-to-authenticate-and-validate-webhooks ) ### Request Payload ##### JSON attributes | Name | Type | Required | Description | Example | | -------------- | ------ | -------- | ---------------------------------------------------- | -------------- | | customerOrderId | string | Required | ID of customer order | 646e3914954fba48a681676e | | customerOrderNo | string | Required | Order No of customer order | JPUS6759785254 | | status | string | Required | [Shipment Status](#Full-shipment-status) | Order Created | | triggeredAt | string | Required | The datetime of when the shipment update to this status in ISO 8601 format. | 2023-05-25T00:20:03.820Z | ##### Sample Request body: ```json= { "customerOrderId": "646e3914954fba48a681676e", "customerOrderNo": "JPUS6759785254", "status": "Order Created", "triggeredAt": "2023-05-25T00:20:03.820Z" } ``` ### Response Please return a HTTP 200 response at your receiver. Jumppoint will consider the webhook request is successful upon receiving a HTTP 200 response. Otherwise, it'll retry sending the request again some more times some times later.

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.