taiwan-logistics-skill 1.2.2 → 1.2.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/taiwan-logistics/data/field-mappings.csv +23 -27
- package/assets/taiwan-logistics/data/status-codes.csv +54 -0
- package/assets/taiwan-logistics/examples/hct-logistics-example.py +288 -288
- package/assets/taiwan-logistics/examples/paynow-logistics-cvs-example.py +263 -263
- package/assets/taiwan-logistics/examples/pchomepay-logistics-cvs-example.py +255 -255
- package/assets/taiwan-logistics/examples/smilepay-logistics-cvs-example.py +298 -298
- package/package.json +1 -1
|
@@ -1,288 +1,288 @@
|
|
|
1
|
-
#!/usr/bin/env python3
|
|
2
|
-
"""
|
|
3
|
-
新竹物流 (HCT) 直連 carrier API Python 範例
|
|
4
|
-
|
|
5
|
-
依 taiwan-logistics-skill 規範撰寫。
|
|
6
|
-
|
|
7
|
-
⚠️ 重要區分:
|
|
8
|
-
- 本範例描述「直連 HCT 自家 API」(申請後使用)
|
|
9
|
-
- 如僅需透過 ECPay/PayNow/SmilePay 等 aggregator 走 HCT 配送
|
|
10
|
-
(LogisticsType=HCT),請參考各 aggregator 的物流文件,無需自行串接 HCT API
|
|
11
|
-
|
|
12
|
-
⚠️ 加密:
|
|
13
|
-
HCT 採自訂加解密;演算法、金鑰、IV、padding **皆於申請後由 HCT 提供 C# Sample Code**。
|
|
14
|
-
本範例的 _encrypt() 為 placeholder,實際串接時須以 HCT 提供之演算法替換。
|
|
15
|
-
|
|
16
|
-
支援:
|
|
17
|
-
- 查貨服務(網頁串接 + XML 批次查詢)
|
|
18
|
-
- 出貨服務(傳入託運資料 / 修改重量 / 列印總表 / 查詢貨號 / 逆物流)
|
|
19
|
-
|
|
20
|
-
API 文件: 參見 references/hct-logistics-api.md
|
|
21
|
-
|
|
22
|
-
依賴:
|
|
23
|
-
pip install requests
|
|
24
|
-
"""
|
|
25
|
-
|
|
26
|
-
import time
|
|
27
|
-
import xml.etree.ElementTree as ET
|
|
28
|
-
from dataclasses import dataclass, field
|
|
29
|
-
from typing import Dict, List, Literal, Optional
|
|
30
|
-
|
|
31
|
-
import requests
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
@dataclass
|
|
35
|
-
class TransData:
|
|
36
|
-
"""傳入託運資料 (TransData)"""
|
|
37
|
-
esdate: str # 出貨日期 YYYY/MM/DD
|
|
38
|
-
epino: str # 訂單編號 (該日期內唯一)
|
|
39
|
-
epdcl1: str # 收件人姓名
|
|
40
|
-
epdcl2: str # 收件人電話
|
|
41
|
-
eaddr1: str # 收件人地址
|
|
42
|
-
epname: str # 寄件人姓名
|
|
43
|
-
eptel: str # 寄件人電話
|
|
44
|
-
eaddr2: str # 寄件人地址
|
|
45
|
-
eqmny: int # 件數
|
|
46
|
-
eweight: int = 0 # 重量(kg, 整數)
|
|
47
|
-
epod: Literal['1', '2'] = '1' # 1=託運單 2=面交收據
|
|
48
|
-
eshipment: str = '' # 出貨溫層/種類
|
|
49
|
-
eprdcl1: str = '' # 商品名稱
|
|
50
|
-
epaytype: Literal['0', '1', '2'] = '0' # 0=月結 1=現付 2=代收貨款
|
|
51
|
-
eamtcod: int = 0 # 代收貨款金額(epaytype=2 時)
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
@dataclass
|
|
55
|
-
class HCTResponse:
|
|
56
|
-
success: bool
|
|
57
|
-
decrypted_xml: str = ''
|
|
58
|
-
error_message: str = ''
|
|
59
|
-
raw_text: str = ''
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
class HCTDirectLogisticService:
|
|
63
|
-
"""
|
|
64
|
-
HCT 新竹物流直連 API 服務.
|
|
65
|
-
|
|
66
|
-
端點:
|
|
67
|
-
- 網頁查貨: /phone/searchGoods_Main.aspx?no=加密字串&v=xx
|
|
68
|
-
- XML 批次查貨: /phone/searchGoods_Main_Xml.ashx (POST)
|
|
69
|
-
- 傳入託運資料: TransData (DataSet/JSON/XML 變體)
|
|
70
|
-
- 修改重量: UpdData
|
|
71
|
-
- 列印總表: TransReport (18:00 前 must call)
|
|
72
|
-
- 查詢貨號: QueryEDELNO
|
|
73
|
-
- 逆物流: R_TransData (JSON only)
|
|
74
|
-
|
|
75
|
-
加密金鑰: 申請後由 HCT 提供; 維護於後台「站所電腦負責人」流程。
|
|
76
|
-
"""
|
|
77
|
-
|
|
78
|
-
BASE_URL = 'https://hctapiweb.hct.com.tw'
|
|
79
|
-
SEARCH_BASE = 'https://hctapiweb.hct.com.tw/phone'
|
|
80
|
-
|
|
81
|
-
def __init__(self, customer_no: str, encrypt_version: str, encryption_key: str = ''):
|
|
82
|
-
"""
|
|
83
|
-
Args:
|
|
84
|
-
customer_no: HCT 配發的客戶編號(站所提供)
|
|
85
|
-
encrypt_version: URL `v=` 參數值(站所提供, e.g. 'V001')
|
|
86
|
-
encryption_key: HCT 加密金鑰(申請後提供)
|
|
87
|
-
"""
|
|
88
|
-
self.customer_no = customer_no
|
|
89
|
-
self.encrypt_version = encrypt_version
|
|
90
|
-
self.encryption_key = encryption_key
|
|
91
|
-
|
|
92
|
-
# -- 加密 / 解密(申請後依 HCT 提供之 C# Sample 替換) ----------------------
|
|
93
|
-
|
|
94
|
-
def _encrypt(self, plaintext: str) -> str:
|
|
95
|
-
"""
|
|
96
|
-
HCT 自訂加密.
|
|
97
|
-
|
|
98
|
-
⚠️ Placeholder: 申請後請依 HCT 提供之 C# Sample Code 替換。
|
|
99
|
-
通常為 DES/3DES + 自訂 padding + Hex 編碼。
|
|
100
|
-
"""
|
|
101
|
-
if not self.encryption_key:
|
|
102
|
-
raise NotImplementedError(
|
|
103
|
-
'請先取得 HCT 提供之加密 sample code 並替換 _encrypt() 實作'
|
|
104
|
-
)
|
|
105
|
-
# 真正實作會像:
|
|
106
|
-
# cipher = DES.new(self.encryption_key, DES.MODE_ECB)
|
|
107
|
-
# padded = pad(plaintext.encode(), 8)
|
|
108
|
-
# return cipher.encrypt(padded).hex().upper()
|
|
109
|
-
raise NotImplementedError('Placeholder; replace with HCT-provided algorithm')
|
|
110
|
-
|
|
111
|
-
def _decrypt(self, ciphertext: str) -> str:
|
|
112
|
-
"""HCT 自訂解密(同上, placeholder)"""
|
|
113
|
-
if not self.encryption_key:
|
|
114
|
-
raise NotImplementedError('請先取得 HCT 提供之解密實作')
|
|
115
|
-
raise NotImplementedError('Placeholder; replace with HCT-provided algorithm')
|
|
116
|
-
|
|
117
|
-
# -- 查貨服務 -------------------------------------------------------------
|
|
118
|
-
|
|
119
|
-
def get_search_goods_url(self, order_id: str) -> str:
|
|
120
|
-
"""
|
|
121
|
-
產生網頁查貨 URL(單筆).
|
|
122
|
-
|
|
123
|
-
客戶可點此 URL 直接看到 HCT 系統內的貨況頁面。
|
|
124
|
-
"""
|
|
125
|
-
encrypted = self._encrypt(order_id)
|
|
126
|
-
return f'{self.SEARCH_BASE}/searchGoods_Main.aspx?no={encrypted}&v={self.encrypt_version}'
|
|
127
|
-
|
|
128
|
-
def search_goods_batch(self, order_ids: List[str]) -> HCTResponse:
|
|
129
|
-
"""
|
|
130
|
-
XML 批次查貨.
|
|
131
|
-
|
|
132
|
-
請求 XML:
|
|
133
|
-
<qrylist>
|
|
134
|
-
<order orderid="1234567890"/>
|
|
135
|
-
<order orderid="1234567891"/>
|
|
136
|
-
</qrylist>
|
|
137
|
-
"""
|
|
138
|
-
# 組 XML
|
|
139
|
-
root = ET.Element('qrylist')
|
|
140
|
-
for oid in order_ids:
|
|
141
|
-
ET.SubElement(root, 'order', {'orderid': oid})
|
|
142
|
-
xml_str = ET.tostring(root, encoding='unicode')
|
|
143
|
-
|
|
144
|
-
# 加密
|
|
145
|
-
encrypted = self._encrypt(xml_str)
|
|
146
|
-
url = f'{self.SEARCH_BASE}/searchGoods_Main_Xml.ashx?no={encrypted}&v={self.encrypt_version}'
|
|
147
|
-
|
|
148
|
-
try:
|
|
149
|
-
r = requests.post(url, timeout=30)
|
|
150
|
-
r.raise_for_status()
|
|
151
|
-
except requests.exceptions.RequestException as e:
|
|
152
|
-
raise ConnectionError(f'HCT 查貨 API 連線失敗: {e}')
|
|
153
|
-
|
|
154
|
-
# 解密回應
|
|
155
|
-
try:
|
|
156
|
-
decrypted = self._decrypt(r.text)
|
|
157
|
-
return HCTResponse(
|
|
158
|
-
success=True,
|
|
159
|
-
decrypted_xml=decrypted,
|
|
160
|
-
raw_text=r.text,
|
|
161
|
-
)
|
|
162
|
-
except Exception as e:
|
|
163
|
-
return HCTResponse(success=False, error_message=str(e), raw_text=r.text)
|
|
164
|
-
|
|
165
|
-
# -- 出貨服務 -------------------------------------------------------------
|
|
166
|
-
|
|
167
|
-
def trans_data(self, orders: List[TransData]) -> HCTResponse:
|
|
168
|
-
"""
|
|
169
|
-
TransData: 傳入託運資料.
|
|
170
|
-
|
|
171
|
-
每次最多 30 筆(含圖片時 5 筆)。
|
|
172
|
-
建立後須於當日 18:00 前呼叫 TransReport 否則無法列印託運單。
|
|
173
|
-
"""
|
|
174
|
-
# 組成 XML 或 JSON(HCT 支援 DataSet/XML/JSON 三種變體)
|
|
175
|
-
# 以 JSON 變體為例:
|
|
176
|
-
body = {
|
|
177
|
-
'CustomerNo': self.customer_no,
|
|
178
|
-
'TransData': [
|
|
179
|
-
{
|
|
180
|
-
'esdate': o.esdate,
|
|
181
|
-
'epino': o.epino,
|
|
182
|
-
'epdcl1': o.epdcl1,
|
|
183
|
-
'epdcl2': o.epdcl2,
|
|
184
|
-
'eaddr1': o.eaddr1,
|
|
185
|
-
'epname': o.epname,
|
|
186
|
-
'eptel': o.eptel,
|
|
187
|
-
'eaddr2': o.eaddr2,
|
|
188
|
-
'eqmny': o.eqmny,
|
|
189
|
-
'eweight': o.eweight,
|
|
190
|
-
'epod': o.epod,
|
|
191
|
-
'eshipment': o.eshipment,
|
|
192
|
-
'eprdcl1': o.eprdcl1,
|
|
193
|
-
'epaytype': o.epaytype,
|
|
194
|
-
'eamtcod': o.eamtcod,
|
|
195
|
-
} for o in orders
|
|
196
|
-
],
|
|
197
|
-
}
|
|
198
|
-
# 加密 + POST(端點/路徑申請後由 HCT 提供)
|
|
199
|
-
# url = self.BASE_URL + '/api/TransData'
|
|
200
|
-
# encrypted = self._encrypt(json.dumps(body))
|
|
201
|
-
# r = requests.post(url, data={'data': encrypted, 'v': self.encrypt_version})
|
|
202
|
-
# 此處僅展示架構,實際端點/欄位以 HCT 文件為準
|
|
203
|
-
return HCTResponse(success=False, error_message='HCT TransData endpoint 申請後提供')
|
|
204
|
-
|
|
205
|
-
def trans_report(self, esdate: str, epinos: List[str]) -> HCTResponse:
|
|
206
|
-
"""
|
|
207
|
-
TransReport: 列印託運單總表.
|
|
208
|
-
|
|
209
|
-
⚠️ 必須於出貨日當日 18:00 前呼叫,否則包裹無法配送。
|
|
210
|
-
"""
|
|
211
|
-
return HCTResponse(success=False, error_message='HCT TransReport endpoint 申請後提供')
|
|
212
|
-
|
|
213
|
-
def upd_data(self, esdate: str, epino: str, new_weight: int) -> HCTResponse:
|
|
214
|
-
"""UpdData: 修改重量"""
|
|
215
|
-
return HCTResponse(success=False, error_message='HCT UpdData endpoint 申請後提供')
|
|
216
|
-
|
|
217
|
-
def query_edelno(self, esdate: str, epino: str) -> HCTResponse:
|
|
218
|
-
"""QueryEDELNO: 查詢貨號"""
|
|
219
|
-
return HCTResponse(success=False, error_message='HCT QueryEDELNO endpoint 申請後提供')
|
|
220
|
-
|
|
221
|
-
def r_trans_data(self, orders: List[TransData]) -> HCTResponse:
|
|
222
|
-
"""
|
|
223
|
-
R_TransData: 逆物流託運(JSON only, 沒有 XML/DataSet 變體).
|
|
224
|
-
"""
|
|
225
|
-
return HCTResponse(success=False, error_message='HCT R_TransData endpoint 申請後提供')
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
# ============================================================================
|
|
229
|
-
# Examples
|
|
230
|
-
# ============================================================================
|
|
231
|
-
|
|
232
|
-
def example_search_url():
|
|
233
|
-
print('=== HCT 網頁查貨 URL ===\n')
|
|
234
|
-
print('注意: 此範例需要 HCT 提供加密 sample code 才能跑。\n')
|
|
235
|
-
svc = HCTDirectLogisticService(
|
|
236
|
-
customer_no='YOUR_CUSTOMER_NO',
|
|
237
|
-
encrypt_version='V001',
|
|
238
|
-
encryption_key='YOUR_HCT_KEY', # 申請後取得
|
|
239
|
-
)
|
|
240
|
-
try:
|
|
241
|
-
url = svc.get_search_goods_url(order_id='1234567890')
|
|
242
|
-
print(f'查貨 URL: {url}')
|
|
243
|
-
except NotImplementedError as e:
|
|
244
|
-
print(f'[expected] {e}')
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
def example_batch_search():
|
|
248
|
-
print('\n=== HCT XML 批次查貨 ===\n')
|
|
249
|
-
svc = HCTDirectLogisticService('YOUR_CUSTOMER_NO', 'V001', 'YOUR_HCT_KEY')
|
|
250
|
-
try:
|
|
251
|
-
resp = svc.search_goods_batch(['1234567890', '1234567891'])
|
|
252
|
-
if resp.success:
|
|
253
|
-
print(f'解密 XML:\n{resp.decrypted_xml[:500]}')
|
|
254
|
-
else:
|
|
255
|
-
print(f'[FAIL] {resp.error_message}')
|
|
256
|
-
except NotImplementedError as e:
|
|
257
|
-
print(f'[expected] {e}')
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
def example_trans_data():
|
|
261
|
-
print('\n=== HCT TransData 傳入託運資料 ===\n')
|
|
262
|
-
svc = HCTDirectLogisticService('YOUR_CUSTOMER_NO', 'V001', 'YOUR_HCT_KEY')
|
|
263
|
-
orders = [
|
|
264
|
-
TransData(
|
|
265
|
-
esdate='2026/05/07',
|
|
266
|
-
epino=f'ORD{int(time.time())}',
|
|
267
|
-
epdcl1='王小明',
|
|
268
|
-
epdcl2='0912345678',
|
|
269
|
-
eaddr1='台北市信義區信義路五段7號',
|
|
270
|
-
epname='店家',
|
|
271
|
-
eptel='02-27000000',
|
|
272
|
-
eaddr2='台北市大安區忠孝東路四段1號',
|
|
273
|
-
eqmny=1,
|
|
274
|
-
eweight=2,
|
|
275
|
-
eshipment='常溫',
|
|
276
|
-
eprdcl1='測試商品',
|
|
277
|
-
epaytype='2', # 代收貨款
|
|
278
|
-
eamtcod=1500,
|
|
279
|
-
)
|
|
280
|
-
]
|
|
281
|
-
resp = svc.trans_data(orders)
|
|
282
|
-
print(f'結果: success={resp.success} message={resp.error_message}')
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
if __name__ == '__main__':
|
|
286
|
-
example_search_url()
|
|
287
|
-
example_batch_search()
|
|
288
|
-
example_trans_data()
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
新竹物流 (HCT) 直連 carrier API Python 範例
|
|
4
|
+
|
|
5
|
+
依 taiwan-logistics-skill 規範撰寫。
|
|
6
|
+
|
|
7
|
+
⚠️ 重要區分:
|
|
8
|
+
- 本範例描述「直連 HCT 自家 API」(申請後使用)
|
|
9
|
+
- 如僅需透過 ECPay/PayNow/SmilePay 等 aggregator 走 HCT 配送
|
|
10
|
+
(LogisticsType=HCT),請參考各 aggregator 的物流文件,無需自行串接 HCT API
|
|
11
|
+
|
|
12
|
+
⚠️ 加密:
|
|
13
|
+
HCT 採自訂加解密;演算法、金鑰、IV、padding **皆於申請後由 HCT 提供 C# Sample Code**。
|
|
14
|
+
本範例的 _encrypt() 為 placeholder,實際串接時須以 HCT 提供之演算法替換。
|
|
15
|
+
|
|
16
|
+
支援:
|
|
17
|
+
- 查貨服務(網頁串接 + XML 批次查詢)
|
|
18
|
+
- 出貨服務(傳入託運資料 / 修改重量 / 列印總表 / 查詢貨號 / 逆物流)
|
|
19
|
+
|
|
20
|
+
API 文件: 參見 references/hct-logistics-api.md
|
|
21
|
+
|
|
22
|
+
依賴:
|
|
23
|
+
pip install requests
|
|
24
|
+
"""
|
|
25
|
+
|
|
26
|
+
import time
|
|
27
|
+
import xml.etree.ElementTree as ET
|
|
28
|
+
from dataclasses import dataclass, field
|
|
29
|
+
from typing import Dict, List, Literal, Optional
|
|
30
|
+
|
|
31
|
+
import requests
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
@dataclass
|
|
35
|
+
class TransData:
|
|
36
|
+
"""傳入託運資料 (TransData)"""
|
|
37
|
+
esdate: str # 出貨日期 YYYY/MM/DD
|
|
38
|
+
epino: str # 訂單編號 (該日期內唯一)
|
|
39
|
+
epdcl1: str # 收件人姓名
|
|
40
|
+
epdcl2: str # 收件人電話
|
|
41
|
+
eaddr1: str # 收件人地址
|
|
42
|
+
epname: str # 寄件人姓名
|
|
43
|
+
eptel: str # 寄件人電話
|
|
44
|
+
eaddr2: str # 寄件人地址
|
|
45
|
+
eqmny: int # 件數
|
|
46
|
+
eweight: int = 0 # 重量(kg, 整數)
|
|
47
|
+
epod: Literal['1', '2'] = '1' # 1=託運單 2=面交收據
|
|
48
|
+
eshipment: str = '' # 出貨溫層/種類
|
|
49
|
+
eprdcl1: str = '' # 商品名稱
|
|
50
|
+
epaytype: Literal['0', '1', '2'] = '0' # 0=月結 1=現付 2=代收貨款
|
|
51
|
+
eamtcod: int = 0 # 代收貨款金額(epaytype=2 時)
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
@dataclass
|
|
55
|
+
class HCTResponse:
|
|
56
|
+
success: bool
|
|
57
|
+
decrypted_xml: str = ''
|
|
58
|
+
error_message: str = ''
|
|
59
|
+
raw_text: str = ''
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
class HCTDirectLogisticService:
|
|
63
|
+
"""
|
|
64
|
+
HCT 新竹物流直連 API 服務.
|
|
65
|
+
|
|
66
|
+
端點:
|
|
67
|
+
- 網頁查貨: /phone/searchGoods_Main.aspx?no=加密字串&v=xx
|
|
68
|
+
- XML 批次查貨: /phone/searchGoods_Main_Xml.ashx (POST)
|
|
69
|
+
- 傳入託運資料: TransData (DataSet/JSON/XML 變體)
|
|
70
|
+
- 修改重量: UpdData
|
|
71
|
+
- 列印總表: TransReport (18:00 前 must call)
|
|
72
|
+
- 查詢貨號: QueryEDELNO
|
|
73
|
+
- 逆物流: R_TransData (JSON only)
|
|
74
|
+
|
|
75
|
+
加密金鑰: 申請後由 HCT 提供; 維護於後台「站所電腦負責人」流程。
|
|
76
|
+
"""
|
|
77
|
+
|
|
78
|
+
BASE_URL = 'https://hctapiweb.hct.com.tw'
|
|
79
|
+
SEARCH_BASE = 'https://hctapiweb.hct.com.tw/phone'
|
|
80
|
+
|
|
81
|
+
def __init__(self, customer_no: str, encrypt_version: str, encryption_key: str = ''):
|
|
82
|
+
"""
|
|
83
|
+
Args:
|
|
84
|
+
customer_no: HCT 配發的客戶編號(站所提供)
|
|
85
|
+
encrypt_version: URL `v=` 參數值(站所提供, e.g. 'V001')
|
|
86
|
+
encryption_key: HCT 加密金鑰(申請後提供)
|
|
87
|
+
"""
|
|
88
|
+
self.customer_no = customer_no
|
|
89
|
+
self.encrypt_version = encrypt_version
|
|
90
|
+
self.encryption_key = encryption_key
|
|
91
|
+
|
|
92
|
+
# -- 加密 / 解密(申請後依 HCT 提供之 C# Sample 替換) ----------------------
|
|
93
|
+
|
|
94
|
+
def _encrypt(self, plaintext: str) -> str:
|
|
95
|
+
"""
|
|
96
|
+
HCT 自訂加密.
|
|
97
|
+
|
|
98
|
+
⚠️ Placeholder: 申請後請依 HCT 提供之 C# Sample Code 替換。
|
|
99
|
+
通常為 DES/3DES + 自訂 padding + Hex 編碼。
|
|
100
|
+
"""
|
|
101
|
+
if not self.encryption_key:
|
|
102
|
+
raise NotImplementedError(
|
|
103
|
+
'請先取得 HCT 提供之加密 sample code 並替換 _encrypt() 實作'
|
|
104
|
+
)
|
|
105
|
+
# 真正實作會像:
|
|
106
|
+
# cipher = DES.new(self.encryption_key, DES.MODE_ECB)
|
|
107
|
+
# padded = pad(plaintext.encode(), 8)
|
|
108
|
+
# return cipher.encrypt(padded).hex().upper()
|
|
109
|
+
raise NotImplementedError('Placeholder; replace with HCT-provided algorithm')
|
|
110
|
+
|
|
111
|
+
def _decrypt(self, ciphertext: str) -> str:
|
|
112
|
+
"""HCT 自訂解密(同上, placeholder)"""
|
|
113
|
+
if not self.encryption_key:
|
|
114
|
+
raise NotImplementedError('請先取得 HCT 提供之解密實作')
|
|
115
|
+
raise NotImplementedError('Placeholder; replace with HCT-provided algorithm')
|
|
116
|
+
|
|
117
|
+
# -- 查貨服務 -------------------------------------------------------------
|
|
118
|
+
|
|
119
|
+
def get_search_goods_url(self, order_id: str) -> str:
|
|
120
|
+
"""
|
|
121
|
+
產生網頁查貨 URL(單筆).
|
|
122
|
+
|
|
123
|
+
客戶可點此 URL 直接看到 HCT 系統內的貨況頁面。
|
|
124
|
+
"""
|
|
125
|
+
encrypted = self._encrypt(order_id)
|
|
126
|
+
return f'{self.SEARCH_BASE}/searchGoods_Main.aspx?no={encrypted}&v={self.encrypt_version}'
|
|
127
|
+
|
|
128
|
+
def search_goods_batch(self, order_ids: List[str]) -> HCTResponse:
|
|
129
|
+
"""
|
|
130
|
+
XML 批次查貨.
|
|
131
|
+
|
|
132
|
+
請求 XML:
|
|
133
|
+
<qrylist>
|
|
134
|
+
<order orderid="1234567890"/>
|
|
135
|
+
<order orderid="1234567891"/>
|
|
136
|
+
</qrylist>
|
|
137
|
+
"""
|
|
138
|
+
# 組 XML
|
|
139
|
+
root = ET.Element('qrylist')
|
|
140
|
+
for oid in order_ids:
|
|
141
|
+
ET.SubElement(root, 'order', {'orderid': oid})
|
|
142
|
+
xml_str = ET.tostring(root, encoding='unicode')
|
|
143
|
+
|
|
144
|
+
# 加密
|
|
145
|
+
encrypted = self._encrypt(xml_str)
|
|
146
|
+
url = f'{self.SEARCH_BASE}/searchGoods_Main_Xml.ashx?no={encrypted}&v={self.encrypt_version}'
|
|
147
|
+
|
|
148
|
+
try:
|
|
149
|
+
r = requests.post(url, timeout=30)
|
|
150
|
+
r.raise_for_status()
|
|
151
|
+
except requests.exceptions.RequestException as e:
|
|
152
|
+
raise ConnectionError(f'HCT 查貨 API 連線失敗: {e}')
|
|
153
|
+
|
|
154
|
+
# 解密回應
|
|
155
|
+
try:
|
|
156
|
+
decrypted = self._decrypt(r.text)
|
|
157
|
+
return HCTResponse(
|
|
158
|
+
success=True,
|
|
159
|
+
decrypted_xml=decrypted,
|
|
160
|
+
raw_text=r.text,
|
|
161
|
+
)
|
|
162
|
+
except Exception as e:
|
|
163
|
+
return HCTResponse(success=False, error_message=str(e), raw_text=r.text)
|
|
164
|
+
|
|
165
|
+
# -- 出貨服務 -------------------------------------------------------------
|
|
166
|
+
|
|
167
|
+
def trans_data(self, orders: List[TransData]) -> HCTResponse:
|
|
168
|
+
"""
|
|
169
|
+
TransData: 傳入託運資料.
|
|
170
|
+
|
|
171
|
+
每次最多 30 筆(含圖片時 5 筆)。
|
|
172
|
+
建立後須於當日 18:00 前呼叫 TransReport 否則無法列印託運單。
|
|
173
|
+
"""
|
|
174
|
+
# 組成 XML 或 JSON(HCT 支援 DataSet/XML/JSON 三種變體)
|
|
175
|
+
# 以 JSON 變體為例:
|
|
176
|
+
body = {
|
|
177
|
+
'CustomerNo': self.customer_no,
|
|
178
|
+
'TransData': [
|
|
179
|
+
{
|
|
180
|
+
'esdate': o.esdate,
|
|
181
|
+
'epino': o.epino,
|
|
182
|
+
'epdcl1': o.epdcl1,
|
|
183
|
+
'epdcl2': o.epdcl2,
|
|
184
|
+
'eaddr1': o.eaddr1,
|
|
185
|
+
'epname': o.epname,
|
|
186
|
+
'eptel': o.eptel,
|
|
187
|
+
'eaddr2': o.eaddr2,
|
|
188
|
+
'eqmny': o.eqmny,
|
|
189
|
+
'eweight': o.eweight,
|
|
190
|
+
'epod': o.epod,
|
|
191
|
+
'eshipment': o.eshipment,
|
|
192
|
+
'eprdcl1': o.eprdcl1,
|
|
193
|
+
'epaytype': o.epaytype,
|
|
194
|
+
'eamtcod': o.eamtcod,
|
|
195
|
+
} for o in orders
|
|
196
|
+
],
|
|
197
|
+
}
|
|
198
|
+
# 加密 + POST(端點/路徑申請後由 HCT 提供)
|
|
199
|
+
# url = self.BASE_URL + '/api/TransData'
|
|
200
|
+
# encrypted = self._encrypt(json.dumps(body))
|
|
201
|
+
# r = requests.post(url, data={'data': encrypted, 'v': self.encrypt_version})
|
|
202
|
+
# 此處僅展示架構,實際端點/欄位以 HCT 文件為準
|
|
203
|
+
return HCTResponse(success=False, error_message='HCT TransData endpoint 申請後提供')
|
|
204
|
+
|
|
205
|
+
def trans_report(self, esdate: str, epinos: List[str]) -> HCTResponse:
|
|
206
|
+
"""
|
|
207
|
+
TransReport: 列印託運單總表.
|
|
208
|
+
|
|
209
|
+
⚠️ 必須於出貨日當日 18:00 前呼叫,否則包裹無法配送。
|
|
210
|
+
"""
|
|
211
|
+
return HCTResponse(success=False, error_message='HCT TransReport endpoint 申請後提供')
|
|
212
|
+
|
|
213
|
+
def upd_data(self, esdate: str, epino: str, new_weight: int) -> HCTResponse:
|
|
214
|
+
"""UpdData: 修改重量"""
|
|
215
|
+
return HCTResponse(success=False, error_message='HCT UpdData endpoint 申請後提供')
|
|
216
|
+
|
|
217
|
+
def query_edelno(self, esdate: str, epino: str) -> HCTResponse:
|
|
218
|
+
"""QueryEDELNO: 查詢貨號"""
|
|
219
|
+
return HCTResponse(success=False, error_message='HCT QueryEDELNO endpoint 申請後提供')
|
|
220
|
+
|
|
221
|
+
def r_trans_data(self, orders: List[TransData]) -> HCTResponse:
|
|
222
|
+
"""
|
|
223
|
+
R_TransData: 逆物流託運(JSON only, 沒有 XML/DataSet 變體).
|
|
224
|
+
"""
|
|
225
|
+
return HCTResponse(success=False, error_message='HCT R_TransData endpoint 申請後提供')
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
# ============================================================================
|
|
229
|
+
# Examples
|
|
230
|
+
# ============================================================================
|
|
231
|
+
|
|
232
|
+
def example_search_url():
|
|
233
|
+
print('=== HCT 網頁查貨 URL ===\n')
|
|
234
|
+
print('注意: 此範例需要 HCT 提供加密 sample code 才能跑。\n')
|
|
235
|
+
svc = HCTDirectLogisticService(
|
|
236
|
+
customer_no='YOUR_CUSTOMER_NO',
|
|
237
|
+
encrypt_version='V001',
|
|
238
|
+
encryption_key='YOUR_HCT_KEY', # 申請後取得
|
|
239
|
+
)
|
|
240
|
+
try:
|
|
241
|
+
url = svc.get_search_goods_url(order_id='1234567890')
|
|
242
|
+
print(f'查貨 URL: {url}')
|
|
243
|
+
except NotImplementedError as e:
|
|
244
|
+
print(f'[expected] {e}')
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def example_batch_search():
|
|
248
|
+
print('\n=== HCT XML 批次查貨 ===\n')
|
|
249
|
+
svc = HCTDirectLogisticService('YOUR_CUSTOMER_NO', 'V001', 'YOUR_HCT_KEY')
|
|
250
|
+
try:
|
|
251
|
+
resp = svc.search_goods_batch(['1234567890', '1234567891'])
|
|
252
|
+
if resp.success:
|
|
253
|
+
print(f'解密 XML:\n{resp.decrypted_xml[:500]}')
|
|
254
|
+
else:
|
|
255
|
+
print(f'[FAIL] {resp.error_message}')
|
|
256
|
+
except NotImplementedError as e:
|
|
257
|
+
print(f'[expected] {e}')
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
def example_trans_data():
|
|
261
|
+
print('\n=== HCT TransData 傳入託運資料 ===\n')
|
|
262
|
+
svc = HCTDirectLogisticService('YOUR_CUSTOMER_NO', 'V001', 'YOUR_HCT_KEY')
|
|
263
|
+
orders = [
|
|
264
|
+
TransData(
|
|
265
|
+
esdate='2026/05/07',
|
|
266
|
+
epino=f'ORD{int(time.time())}',
|
|
267
|
+
epdcl1='王小明',
|
|
268
|
+
epdcl2='0912345678',
|
|
269
|
+
eaddr1='台北市信義區信義路五段7號',
|
|
270
|
+
epname='店家',
|
|
271
|
+
eptel='02-27000000',
|
|
272
|
+
eaddr2='台北市大安區忠孝東路四段1號',
|
|
273
|
+
eqmny=1,
|
|
274
|
+
eweight=2,
|
|
275
|
+
eshipment='常溫',
|
|
276
|
+
eprdcl1='測試商品',
|
|
277
|
+
epaytype='2', # 代收貨款
|
|
278
|
+
eamtcod=1500,
|
|
279
|
+
)
|
|
280
|
+
]
|
|
281
|
+
resp = svc.trans_data(orders)
|
|
282
|
+
print(f'結果: success={resp.success} message={resp.error_message}')
|
|
283
|
+
|
|
284
|
+
|
|
285
|
+
if __name__ == '__main__':
|
|
286
|
+
example_search_url()
|
|
287
|
+
example_batch_search()
|
|
288
|
+
example_trans_data()
|