Application Programming Interface (API) at Speedpost System for System Integration with e-commerce Systems The Government of the Hong Kong Special Administrative Region The contents of this document remain the property of and may not be reproduced in whole or in part without the expressed permission of the Government of HKSAR
Table of Contents 1. Speedpost Web Services URL... 3 2. Speedpost Web Services Overview... 4 3. Web Services Authentication... 4 4. Speedpost Posting API... 5 5. Speedpost Posting API Create Shipping Record... 5 5.1 Request Details... 5 5.2 Response Details... 9 6. Speedpost Posting API Download Shipping Label... 10 6.1 Request Details... 10 6.2 Response Details... 10 7. API Call Limit... 10 API Daily Call Limit... 10 8. Appendix... 11 Appendix A Sender Address... 11 Appendix B1 Country Code (Speedpost Standard/ MultiPack/ Freight)... 11 Appendix B2 Country Code (Next Flight Out)... 19 Appendix B4 Country Code (Economy Express/ EC Post)... 19 Appendix C Insurance Service Code... 19 Appendix D Item Type Code... 19 Appendix E Currency... 20 Appendix F CN23 Item Type Code... 20 Appendix G Posting Services... 20 Appendix H1 Addressee City ( For EC Post/ Economy Express Only)... 21 Page 2 of 21
1. Speedpost Web Services URL Testing Site URL: https://service.hongkongpost.hk/api-trial/services Production Site URL: https://api.hongkongpost.hk/api/services *Only authorized IP addresses are allowed to access this URL Page 3 of 21
2. Speedpost Web Services Overview Web Services Operations Usage createsoazorder Create shipping record SoazPosting getsoazaddresspack Download Shipping Label 3. Web Services Authentication Authentication key is required to call Speedpost API. The credential is provided registered API users. Credential must be included in your request SOAP message as specified in API. Without this information, your API request will be rejected. Parameter Data Type Length Not Null? Remark Constraint USERNAME TEXT 20 Yes API Username PASSWORD TEXT 20 Yes Credentials for reject unauthorized party to use the API. These credentials must be included in your code as specified in the Web Services technical documentation. Transactions without proper credentials will be rejected. Page 4 of 21
4. Speedpost Posting API Location (Testing Site) https://service.hongkongpost.hk/api-trial /services/soazposting?wsdl (Production Site) https://api.hongkongpost.hk/api /services/soazposting?wsdl Target Namespace http://webservice.integrator.hkpost.com Protocol Default style SOAP Document Transport protocol SOAP over HTTPS Operations 1. createsoazorder 2. getsoazaddresspack 5. Speedpost Posting API Create Shipping Record 5.1 Request Details Please read the following data description (* Mandatory fields) Parameter Data Type Length Constra int Mandatory Remark (byte) soazusername TEXT 20 * Soaz (My Speedpost) username integratorusername TEXT 20 * API username Sender Information service TEXT 10 * Posting Service Option Appendix G sendaddrtypecode TEXT 1 * Sender s Address Type Option: Appendix A Page 5 of 21
sendaddress1 TEXT 35 # Address of Sender Line1 Mandatory and valid if sendaddrtypecode = I sendaddress2 TEXT 35 Address of Sender Line2 Optional for sendaddrtypecode = I sendaddress3 TEXT 35 Address of Sender Line3 Optional for sendaddrtypecode = I sendaddress4 TEXT 35 Address of Sender Line4 Optional for sendaddrtypecode = I sendcontactname TEXT 50 * Sender s Contant Name sendemail TEXT 60 Sender s Email sendfaxno TEXT 25 Sender s Fax Number sendtelno TEXT 25 * Sender s Telephone Number Delivery Address Informtaion addresseename TEXT 35 * Name of Addressee addresseecompanyna TEXT 70 Company Name me addresseeaddr1 TEXT 35 * Address of Addressee Line1 addresseeaddr2 TEXT 35 Address of Addressee Line2 addresseeaddr3 TEXT 35 Address of Addressee Line3 addresseeaddr4 TEXT 35 Address of Addressee Line4 addresseecity TEXT 35 * City For EC Post/ Economy Express Appendix H1 Others Free Text addresseepostalcode TEXT 9 # Postal Code Mandatory for EC Post/ Economy Express addresseecountry TEXT 3 * Country Code Option: For Speedpost Standard/ Multipack/ Freight Appendix B1 For Next Flight Out Appendix B2 For EC Post/ Economy Express Appendix B4 Page 6 of 21
addresseeemail TEXT 60 Email of Addressee addresseefaxno TEXT 25 Fax Number of Addressee addresseetelno TEXT 25 Telephone Number of Addressee Insurance insurflag TEXT 1 * Insurance Option: Y- Yes N- No insurrplanname TEXT 1 Insurance Type Option: Appendix C insuramt NUMBER 7 Insurance Amount Product Information itemtypecode TEXT 1 * Item Category Option Appendix D itemdesc1 TEXT 60 1 st Product Content Details itemqty1 NUMBER 5 1 st Product Quantity itemwgt1 NUMBER 6 1 st Product Weight itemctycode1 TEXT 2 1 st Product City Code Option Appendix B itemvalue1 NUMBER 7 1 st Product Value itemhscode1 NUMBER 7 1 st Product HKHS Code itemcurrcode1 TEXT 3 Product Currency ( Applied for all product) Option Appendix E itemdesc2 TEXT 60 2 nd Product Content Details itemqty2 NUMBER 5 2 nd Product Quantity itemwgt2 NUMBER 6 2 nd Product Weight itemctycode2 TEXT 2 2 nd Product City Code Option Appendix B itemvalue2 NUMBER 7 2 nd Product Value itemhscode2 NUMBER 7 2 nd Product HKHS Code itemdesc3 TEXT 60 3 rd Product Content Details itemqty3 NUMBER 5 3 rd Product Quantity itemwgt3 NUMBER 6 3 rd Product Weight itemctycode3 TEXT 2 3 rd Product City Code Option Appendix B itemvalue3 NUMBER 7 3 rd Product Value Page 7 of 21
itemhscode3 NUMBER 7 3 rd Product HKHS Code itemdesc4 TEXT 60 4 th Product Content Details itemqty4 NUMBER 5 4 th Product Quantity itemwgt4 NUMBER 6 4 th Product Weight itemctycode4 TEXT 2 4 th Product City Code Option Appendix B itemvalue4 NUMBER 7 4 th Product Value itemhscode4 NUMBER 7 4 th Product HKHS Code nocertinv NUMBER 3 Number of Certificate and Invoice CN23 Form cn23flag TEXT 1 * Need to complete CN23 Form Option Y- Yes N- No cn23itemtypecode TEXT 1 # Category of Item Option Appendix F Mandatory if cn23flag is Y cn23itemtypedesc TEXT 30 Item Description ( for category is other) sendcustref TEXT 20 Sender s Customs Reference impref TEXT 60 Importers Reference imptelno TEXT 25 Importer s Telephone Number impfaxno TEXT 25 Importer s Fax Number impemail TEXT 60 Importer s Email Address postalchrg NUMBER 6 Postage Charge (HKD) otherfee NUMBER 6 Other fees comment TEXT 60 Comments (e.g.: goods subject to quarantine, sanitary / phytosanitary inspection or other restrictions) nolicence TEXT 20 Licence Number nocert TEXT 20 Certificate Number noinv TEXT 20 Invoice Number Customer Order Reference (EC Post/ Economy Express Only) custordref TEXT 20 Customer Order Reference Reference Online store website (EC Post Only) requrl TEXT 256 # Online Store Website Mandatory for EC Post Page 8 of 21
itemno 5.2 Response Details Parameter Data Type Remark TEXT status NUMBER 200 : success 9998 : invalid input 9999: general exception errmessage TEXT Error Message Page 9 of 21
6. Speedpost Posting API Download Shipping Label 6.1 Request Details Parameter Data Type Length Mandatory Remark Constraint soazusername TEXT 20 * Soaz (My Speedpost) username integratorusername TEXT 20 * API username itemno TEXT 13 * Item No printmode TEXT 1 A: A4 size address pack cn23noofcopy NUMBER 1 No. of Copy, default is 0, max 9 cn22noofcopy NUMBER 1 No. of Copy, default is 0, max 9 signature TEXT 30 Signature of the sender createdate Creation date TEXT 10 Format: dd-mm-yyyy 6.2 Response Details Parameter Data Type Remark status NUMBER 0: Success -1: Failed 9998 : invalid input 9999: general exception errmessage TEXT Error Messages ap base64binary PDF file as byte format 7. API Call Limit To maintain a high level of availability and provide superior quality of service, Limitation the API call usage for API user as follows. The limits on the total calls are subjected to change, depends on actual usage of API user. API Daily Call Limit Posting API - 10,000 Page 10 of 21
8. Appendix Appendix A Sender Address Code English Name Chinese Name P Pick-up Address 收件地址 B Billing Address 帳單地址 I Input Address 自定義地址 Appendix B1 Country Code (Speedpost Standard/ MultiPack/ Freight) Code English Name Chinese Name AF AFGHANISTAN 阿富汗 AL ALBANIA 阿爾巴尼亞 DZ ALGERIA 阿爾及利亞 AD ANDORRA 安道爾 AO ANGOLA 安哥拉 AI ANGUILLA 安圭拉島 AG ANTIGUA 安提瓜 AR ARGENTINA 阿根廷 AM ARMENIA 亞美利亞 AW ARUBA 阿魯巴 AU AUSTRALIA 澳大利亞 ( 澳洲 ) AT AUSTRIA 奧地利 AZ AZERBAIJAN 亞塞拜疆 BS BAHAMAS 巴哈馬 BH BAHRAIN 巴林 BD BANGLADESH 孟加拉 BB BARBADOS 巴巴多斯 Page 11 of 21
BY BELARUS 白俄羅斯 BE BELGIUM 比利時 BZ BELIZE 伯利茲 BJ BENIN 貝寧 BM BERMUDA 百慕達 BT BHUTAN 不丹 BO BOLIVIA 玻利維亞 BA BOSNIA AND HERZEGOVINA 波斯尼亞 - 黑塞哥維那 BW BOTSWANA 博茨瓦納 BR BRAZIL 巴西 BN BRUNEI DARUSSALAM 文萊 BG BULGARIA 保加利亞 BF BURKINA FASO 布基納法索 BI BURUNDI 布隆迪 KH CAMBODIA 柬埔寨 CM CAMEROON 喀麥隆 CA CANADA 加拿大 CV CAPE VERDE 佛得角 FM CAROLINE ISLANDS (MICRONESIA) 加羅林群島 ( 密克羅尼西亞 ) PW CAROLINE ISLANDS(PALAU) 加羅林群島 ( 帕勞 ) KY CAYMAN ISLANDS 開曼群島 CF CENTRAL AFRICA REPUBLIC 中非共和國 TD CHAD 乍得 CL CHILE 智利 CN CHINA 中國內地 CO COLOMBIA 哥倫比亞 CG CONGO (REPUBLIC OF) 剛果 CD CONGO(DEM. REP. OF THE) 剛果 ( 民主共和國 ) CR COSTA RICA 哥斯達黎加 Page 12 of 21
CI COTE D'IVOIRE(IVORY COAST) 科特迪瓦 ( 象牙海岸 ) HR CROATIA 克羅地亞 CU CUBA 古巴 CY CYPRUS 塞浦路斯 CZ CZECH REPUBLIC 捷克 DK DENMARK 丹麥 DJ DJIBOUTI 吉布提 DM DOMINICA 多明尼加 DO DOMINICAN REPUBLIC 多米尼加共和國 TP EAST TIMOR 東帝汶 EC ECUADOR 厄瓜多爾 EG EGYPT 埃及 SV EL SALVADOR 薩爾瓦多 GQ EQUATORIAL GUINEA(REPUBLIC OF) 赤道幾內亞 ER ERITREA 厄立特里亞 EE ESTONIA(REPUBLIC OF) 愛沙尼亞 ET ETHIOPIA 埃塞俄比亞 FO FAROE ISLANDS 法羅群島 FJ FIJI 斐濟 FI FINLAND 芬蘭 FR FRANCE 法國 GF FRENCH GUIANA 法屬圭亞那 PF FRENCH POLYNESIA 法屬波利尼西亞 GA GABON 加蓬 GM GAMBIA 岡比亞 XE GAZA AND KHAN YUNIS 加沙及汗尤尼斯 GE GEORGIA (REPUBLIC OF) 格魯吉亞 DE GERMANY 德國 GH GHANA 加納 Page 13 of 21
GI GIBRALTAR 直布羅陀 GB GREAT BRITAIN 英國 GR GREECE 希臘 GL GREENLAND 格陵蘭 GD GRENADA 格林納達 GP GUADELOUPE 瓜德羅普島 GU GUAM 關島 GT GUATEMALA 危地馬拉 GN GUINEA (REPUBLIC OF) 幾內亞 GW GUINEA BISSAU (REPUBLIC OF) 幾內亞比紹 GY GUYANA 圭亞那 HT HAITI 海地 HN HONDURAS (REPUBLIC OF) 洪都拉斯 HU HUNGARY 匈牙利 IS ICELAND 冰島 IN INDIA 印度 ID INDONESIA 印度尼西亞 IR IRAN 伊朗 IQ IRAQ 伊拉克 IE IRELAND 愛爾蘭 IL ISRAEL 以色列 IT ITALY 意大利 JM JAMAICA 牙買加 JP JAPAN 日本 JO JORDAN 約旦 KZ KAZAKHSTAN 哈薩克 KE KENYA 肯尼亞 KI KIRIBATI 基里巴斯 KP KOREA,NORTH 北韓 Page 14 of 21
KR KOREA,SOUTH 南韓 KW KUWAIT 科威特 KG KYRGYZSTAN 吉爾吉斯 LA LAO PDR 老撾 LV LATVIA 拉脫維亞 LB LEBANON 黎巴嫩 LS LESOTHO 萊索托 LR LIBERIA 利比里亞 LY LIBYA 利比亞 LI LIECHTENSTEIN 列支敦士登 LT LITHUANIA (REPUBLIC OF) 立陶宛 LU LUXEMBOURG 盧森堡 MO MACAU 澳門 MK MACEDONIA 馬其頓 MG MADAGASCAR (DEM. REP. OF) 馬達加斯加 MW MALAWI 馬拉維 MY MALAYSIA 馬來西亞 MV MALDIVES (REPUBLIC OF) 馬爾代夫 ML MALI 馬里 MT MALTA 馬爾他 MP MARIANA ISLANDS (NORTHERN) 馬里亞納群島 ( 北 ) MH MARSHALL ISLANDS 馬紹爾群島 MQ MARTINIQUE 馬提尼克島 MR MAURITANIA 毛里塔尼亞 MU MAURITIUS 毛里求斯 MX MEXICO 墨西哥 MD MOLDOVA (REPUBLIC OF) 摩爾多瓦 MC MONACO 摩納哥 MN MONGOLIA 蒙古 Page 15 of 21
ME MONTENEGRO (REP. OF) 黑山共和國 MS MONTSERRAT 蒙特塞拉特 MA MOROCCO 摩洛哥 MZ MOZAMBIQUE 莫桑比克 MM MYANMAR (UNION OF) 緬甸 NA NAMIBIA 納米比亞 NR NAURU ISLANDS 瑙魯群島 NP NEPAL 尼泊爾 NL NETHERLANDS 荷蘭 AN NETHERLANDS ANTILLES 荷屬安的列斯 NC NEW CALEDONIA 新喀里多尼亞 NZ NEW ZEALAND 新西蘭 XL NEW ZEALAND ISLANDS TERRITORIES(COOK ISL 新西蘭屬土島嶼 ( 庫克群島 ) NI NICARAGUA 尼加拉瓜 NE NIGER REPUBLIC 尼日爾 NG NIGERIA 尼日利亞 NF NORFOLK ISLANDS 諾福克島 NO NORWAY 挪威 OM OMAN,SULTANATE OF 阿曼 PK PAKISTAN 巴基斯坦 PA PANAMA (REPUBLIC OF) 巴拿馬 PG PAPUA NEW GUINEA 巴布亞新畿內亞 PY PARAGUAY 巴拉圭 PE PERU 秘魯 PH PHILIPPINES 菲律賓 PL POLAND 波蘭 PT PORTUGAL 葡萄牙 PR PUERTO RICO 波多黎各 Page 16 of 21
QA QATAR (STATE OF) 卡塔爾 RE REUNION 留尼汪島 RO ROMANIA 羅馬尼亞 RU RUSSIA (RUSSIAN FEDERATION) 俄羅斯 ( 俄羅斯聯邦 ) RW RWANDA 盧旺達 AS SAMOA (USA TERRITORY) 薩摩亞 ( 美國屬土 ) SM SAN MARINO 聖馬力諾 ST 聖多美及普林西比 SAO TOME AND PRINCIPE (REPUBLIC OF) SA SAUDI ARABIA 沙地阿拉伯 SN SENEGAL 塞內加爾 RS SERBIA (REP. OF) 塞爾維亞共和國 SC SEYCHELLES 塞舌爾 SL SIERRA LEONE 塞拉利昂 SG SINGAPORE 新加坡 SK SLOVAK REPUBLIC (SLOVAKIA) 斯洛伐克 ( 共和國 ) SI SLOVENIA (REPUBLIC OF) 斯洛文尼亞 SB SOLOMON ISLANDS 所羅門群島 ZA SOUTH AFRICA (REPUBLIC OF) 南非 ES SPAIN 西班牙 LK SRI LANKA (REPUBLIC OF) 斯里蘭卡 KN ST.CHRISTOPHER(ST.KITTS) AND NEVIS 聖克里斯托佛島及尼維斯島 LC ST.LUCIA 聖盧西亞 VC ST.VINCENT 聖文森特 SD SUDAN 蘇丹 SR SURINAME (REPUBLIC OF) 蘇里南 SZ SWAZILAND 斯威士蘭 SE SWEDEN 瑞典 CH SWITZERLAND 瑞士 Page 17 of 21
SY SYRIAN ARAB REPUBLIC (SYRIA) 阿拉伯敘利亞共和國 ( 敘利亞 ) TW TAIWAN 台灣 TJ TAJIKISTAN (REPUBLIC OF) 塔吉克 TZ TANZANIA 坦桑尼亞 TH THAILAND 泰國 TG TOGO 多哥 TO TONGA 湯加 VG TORTOLA (BRITISH VIRGIN ISLANDS) 托爾托拉島 ( 英屬處女島 ) TT TRINIDAD AND TOBAGO (REPUBLIC OF) 千里達和多巴哥 TN TUNISIA 突尼斯 TR TURKEY 土耳其 TM TURKMENISTAN 土庫曼 TC TURKS AND CAICOS ISLANDS 特克斯和凱科斯群島 TV TUVALU 圖瓦盧 UG UGANDA 烏干達 UA UKRAINE 烏克蘭 AE UNITED ARAB EMIRATES 阿拉伯聯合酋長國 US UNITED STATES OF AMERICA 美國 UY URUGUAY 烏拉圭 UZ UZBEKISTAN (REPUBLIC OF) 烏茲別克 VU VANUATU (THE REPUBLIC OF) 瓦努阿圖 VE VENEZUELA 委內瑞拉 VN VIETNAM 越南 VI VIRGIN ISLANDS OF THE USA 美屬處女群島 WS WESTERN SAMOA 西薩摩亞 YE YEMEN(REPUBLIC OF) 也門 ZM ZAMBIA 贊比亞 ZW ZIMBABWE 津巴布韋 Page 18 of 21
Appendix B2 Country Code (Next Flight Out) Code English Name Chinese Name FR France 法國 GB Great Britain 英國 MY Malaysia 馬來西亞 NL Netherlands 荷蘭 PH Philippines 菲律賓 SG Singapore 新加坡 TW Taiwan 台灣 Appendix B4 Country Code (Economy Express/ EC Post) Code English Name Chinese Name CN China 中國內地 Appendix C Insurance Service Code Code English Name Chinese Name 0 General Items 一般物品 1 Watches, mobile phones, cameras and accessories 手錶 手提電話 相機及配件 Appendix D Item Type Code Code English Name Chinese Name D Document 文件 Page 19 of 21
M Merchandise 商品 S Sample 樣本 G Gift 禮物 Appendix E Currency Code English Name Chinese Name EUR EURO 歐羅 HKD HK Dollar 港幣 YEN YEN 日圓 MOP MACAU PATACA 澳門圓 RMB RMB 人民幣 GBP Pound 英鎊 USD US Dollar 美元 Appendix F CN23 Item Type Code Code English Name Chinese Name G Gift 禮物 D Documents 文件 S Commercial Sample 商業樣本 R Returned Goods 退回貨品 O Other 其它 Appendix G Posting Services Code English Name Chinese Name SPT_STD Speedpost Standard 標準服務 SPT_MPB Speedpost MultiPack 萬用箱服務 SPT_FRE Speedpost Freight 貨運服務 SPT_NFO Speedpost Next Flight Out 瞬時達服務 Page 20 of 21
SPT_ECON Speedpost Economy Express 經濟快遞服務 SPT_ECPOST Speedpost EC Post E 郵寶服務 Appendix H1 Addressee City ( For EC Post/ Economy Express Only) Code English Name Chinese Name BEIJING BEIJING 北京 CHONGQING CHONGQING 重慶 FUJIAN FUJIAN 福建 GUANGDONG GUANGDONG 廣東 SHANDONG SHANDONG 山東 SHANGHAI SHANGHAI 上海 SICHUAN SICHUAN 四川 TIANJIN TIANJIN 天津 ZHEJIANG ZHEJIANG 浙江 Page 21 of 21