taiwan-logistics-skill 1.2.0 → 1.2.2
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/README.md +83 -141
- package/assets/taiwan-logistics/CLAUDE.md +137 -137
- package/assets/taiwan-logistics/EXAMPLES.md +75 -0
- package/assets/taiwan-logistics/README.md +68 -342
- package/assets/taiwan-logistics/examples/hct-logistics-example.py +288 -0
- package/assets/taiwan-logistics/examples/paynow-logistics-cvs-example.py +263 -0
- package/assets/taiwan-logistics/examples/pchomepay-logistics-cvs-example.py +255 -0
- package/assets/taiwan-logistics/examples/smilepay-logistics-cvs-example.py +298 -0
- package/assets/taiwan-logistics/references/hct-logistics-api.md +1102 -1102
- package/assets/taiwan-logistics/references/paynow-logistics-api.md +1670 -1670
- package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1154 -1154
- package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1332 -1332
- package/package.json +2 -2
|
@@ -0,0 +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()
|
|
@@ -0,0 +1,263 @@
|
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
PayNow 立吉富物流 Python 範例
|
|
4
|
+
|
|
5
|
+
依 taiwan-logistics-skill 規範撰寫。
|
|
6
|
+
|
|
7
|
+
⚠️ 加密: PayNow 物流使用 3DES (TripleDES) / ECB / Zero-Padding
|
|
8
|
+
24-byte Key + 8-byte IV,**不同於金流端的動態 AES-256 (GP/GK)**
|
|
9
|
+
|
|
10
|
+
支援 11 條產品線:
|
|
11
|
+
- 7-11 大宗 (B2C) / 冷凍大宗 (B2C) / 冷凍 C2C / 海外配送
|
|
12
|
+
- 全家 大宗 (B2C) / 冷凍大宗 (B2C) / 冷凍 C2C
|
|
13
|
+
- 4 大超商常溫 C2C (7-11/全家/萊爾富/OK)
|
|
14
|
+
- 黑貓宅配 / 黑貓店到店
|
|
15
|
+
|
|
16
|
+
API 文件: 參見 references/paynow-logistics-api.md
|
|
17
|
+
|
|
18
|
+
依賴:
|
|
19
|
+
pip install pycryptodome requests
|
|
20
|
+
"""
|
|
21
|
+
|
|
22
|
+
import json
|
|
23
|
+
import time
|
|
24
|
+
from dataclasses import dataclass, field
|
|
25
|
+
from typing import Dict, Literal, Optional
|
|
26
|
+
|
|
27
|
+
import requests
|
|
28
|
+
from Crypto.Cipher import DES3
|
|
29
|
+
from Crypto.Util.Padding import pad
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass
|
|
33
|
+
class LogisticOrder:
|
|
34
|
+
"""PayNow 物流訂單"""
|
|
35
|
+
service_id: str # 物流商品線 ID(依產品線不同, 見下方常數)
|
|
36
|
+
goods_name: str
|
|
37
|
+
amount: int # COD 金額
|
|
38
|
+
sender_name: str
|
|
39
|
+
sender_phone: str
|
|
40
|
+
sender_address: str = ''
|
|
41
|
+
receiver_name: str = ''
|
|
42
|
+
receiver_phone: str = ''
|
|
43
|
+
receiver_address: str = ''
|
|
44
|
+
receiver_store_id: str = '' # 取貨門市(CVS)
|
|
45
|
+
return_url: str = '' # 通知 URL
|
|
46
|
+
is_cod: bool = True
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
@dataclass
|
|
50
|
+
class PayNowLogisticResponse:
|
|
51
|
+
success: bool
|
|
52
|
+
status: str = ''
|
|
53
|
+
message: str = ''
|
|
54
|
+
logistic_trade_no: str = ''
|
|
55
|
+
raw: Dict[str, any] = field(default_factory=dict)
|
|
56
|
+
|
|
57
|
+
|
|
58
|
+
class PayNowLogisticService:
|
|
59
|
+
"""
|
|
60
|
+
PayNow 物流服務.
|
|
61
|
+
|
|
62
|
+
認證:
|
|
63
|
+
- 商家代號 (merID) + 賣場交易密碼 (apicode)
|
|
64
|
+
- 加密: 3DES / ECB / Zero-Padding
|
|
65
|
+
- 24-byte Key + 8-byte IV (示範值, 真實值需向 PayNow 申請)
|
|
66
|
+
|
|
67
|
+
11 條產品線 ServiceID(部分代碼):
|
|
68
|
+
20 = 7-11 大宗 B2C 常溫
|
|
69
|
+
21 = 7-11 大宗 B2C 冷凍
|
|
70
|
+
22 = 7-11 冷凍 C2C
|
|
71
|
+
23 = 7-11 海外配送
|
|
72
|
+
30 = 全家 大宗 B2C
|
|
73
|
+
31 = 全家 冷凍大宗
|
|
74
|
+
32 = 全家 冷凍 C2C
|
|
75
|
+
40 = 4 大超商常溫 C2C (7-11/全家/萊爾富/OK)
|
|
76
|
+
50 = 黑貓宅配
|
|
77
|
+
51 = 黑貓店到店
|
|
78
|
+
...
|
|
79
|
+
"""
|
|
80
|
+
|
|
81
|
+
TEST_BASE = 'https://test.paynow.com.tw'
|
|
82
|
+
PROD_BASE = 'https://www.paynow.com.tw'
|
|
83
|
+
|
|
84
|
+
# 官方範例金鑰(僅供加密邏輯測試使用)
|
|
85
|
+
SAMPLE_KEY = '123456789070828783123456' # 24 bytes
|
|
86
|
+
SAMPLE_IV = '12345678' # 8 bytes
|
|
87
|
+
|
|
88
|
+
def __init__(self, mer_id: str, apicode: str, key_3des: str, iv_3des: str, is_test: bool = True):
|
|
89
|
+
if len(key_3des) != 24:
|
|
90
|
+
raise ValueError(f'PayNow 物流 3DES Key 必須 24 bytes (收到 {len(key_3des)})')
|
|
91
|
+
if len(iv_3des) != 8:
|
|
92
|
+
raise ValueError(f'PayNow 物流 3DES IV 必須 8 bytes (收到 {len(iv_3des)})')
|
|
93
|
+
|
|
94
|
+
self.mer_id = mer_id
|
|
95
|
+
self.apicode = apicode
|
|
96
|
+
self.key = key_3des.encode('utf-8')
|
|
97
|
+
self.iv = iv_3des.encode('utf-8')
|
|
98
|
+
self.base_url = self.TEST_BASE if is_test else self.PROD_BASE
|
|
99
|
+
|
|
100
|
+
# -- 3DES 加密 ------------------------------------------------------------
|
|
101
|
+
|
|
102
|
+
def _encrypt_3des(self, plaintext: str) -> str:
|
|
103
|
+
"""
|
|
104
|
+
3DES / ECB / Zero-Padding 加密.
|
|
105
|
+
|
|
106
|
+
⚠️ ECB 模式不使用 IV; PayNow 文件雖列 IV 但實際邏輯為 ECB。
|
|
107
|
+
若實際串接時用 CBC, 則替換 mode=DES3.MODE_CBC 並附 IV。
|
|
108
|
+
"""
|
|
109
|
+
# Zero-padding (補 \x00 至 8 byte 倍數)
|
|
110
|
+
block_size = 8
|
|
111
|
+
pad_len = block_size - (len(plaintext.encode('utf-8')) % block_size)
|
|
112
|
+
if pad_len == block_size:
|
|
113
|
+
pad_len = 0
|
|
114
|
+
padded = plaintext.encode('utf-8') + b'\x00' * pad_len
|
|
115
|
+
|
|
116
|
+
cipher = DES3.new(self.key, DES3.MODE_ECB)
|
|
117
|
+
encrypted = cipher.encrypt(padded)
|
|
118
|
+
return encrypted.hex().upper()
|
|
119
|
+
|
|
120
|
+
# -- Operations -----------------------------------------------------------
|
|
121
|
+
|
|
122
|
+
def create_logistic(self, order: LogisticOrder) -> PayNowLogisticResponse:
|
|
123
|
+
"""建立物流訂單"""
|
|
124
|
+
# 組成欲加密的 query string
|
|
125
|
+
body_dict = {
|
|
126
|
+
'merID': self.mer_id,
|
|
127
|
+
'LogisticServiceID': order.service_id,
|
|
128
|
+
'GoodsName': order.goods_name,
|
|
129
|
+
'Amount': str(order.amount) if order.is_cod else '0',
|
|
130
|
+
'SenderName': order.sender_name,
|
|
131
|
+
'SenderPhone': order.sender_phone,
|
|
132
|
+
'SenderAddress': order.sender_address,
|
|
133
|
+
'ReceiverName': order.receiver_name,
|
|
134
|
+
'ReceiverPhone': order.receiver_phone,
|
|
135
|
+
'ReceiverAddress': order.receiver_address,
|
|
136
|
+
'ReceiverStoreID': order.receiver_store_id,
|
|
137
|
+
'ReturnURL': order.return_url,
|
|
138
|
+
'IsCOD': 'Y' if order.is_cod else 'N',
|
|
139
|
+
'TimeStr': str(int(time.time())),
|
|
140
|
+
}
|
|
141
|
+
query = '&'.join(f'{k}={v}' for k, v in body_dict.items())
|
|
142
|
+
encrypted = self._encrypt_3des(query)
|
|
143
|
+
|
|
144
|
+
# POST 至 PayNow
|
|
145
|
+
url = self.base_url + '/service/sevp_logistic.aspx'
|
|
146
|
+
try:
|
|
147
|
+
r = requests.post(
|
|
148
|
+
url,
|
|
149
|
+
data={
|
|
150
|
+
'merID': self.mer_id,
|
|
151
|
+
'EncStr': encrypted,
|
|
152
|
+
'apicode': self.apicode,
|
|
153
|
+
},
|
|
154
|
+
timeout=30,
|
|
155
|
+
)
|
|
156
|
+
r.raise_for_status()
|
|
157
|
+
except requests.exceptions.RequestException as e:
|
|
158
|
+
raise ConnectionError(f'PayNow API 連線失敗: {e}')
|
|
159
|
+
|
|
160
|
+
# PayNow 物流回應通常為 form-data string 或簡易 JSON
|
|
161
|
+
try:
|
|
162
|
+
resp = r.json() if 'application/json' in r.headers.get('Content-Type', '') else self._parse_form(r.text)
|
|
163
|
+
except (ValueError, AttributeError):
|
|
164
|
+
return PayNowLogisticResponse(success=False, message=r.text[:200])
|
|
165
|
+
|
|
166
|
+
status = str(resp.get('status', resp.get('Status', '')))
|
|
167
|
+
return PayNowLogisticResponse(
|
|
168
|
+
success=(status in ('1', 'SUCCESS', '0')),
|
|
169
|
+
status=status,
|
|
170
|
+
message=resp.get('message', resp.get('Message', '')),
|
|
171
|
+
logistic_trade_no=resp.get('LogisticTradeNo', resp.get('logistic_trade_no', '')),
|
|
172
|
+
raw=resp,
|
|
173
|
+
)
|
|
174
|
+
|
|
175
|
+
@staticmethod
|
|
176
|
+
def _parse_form(text: str) -> Dict[str, any]:
|
|
177
|
+
"""簡易 form-data parser"""
|
|
178
|
+
return {k: v for k, v in (kv.split('=', 1) for kv in text.split('&') if '=' in kv)}
|
|
179
|
+
|
|
180
|
+
# -- Emap 選店 URL --------------------------------------------------------
|
|
181
|
+
|
|
182
|
+
def get_emap_url(self, service_id: str, return_url: str) -> str:
|
|
183
|
+
"""取得電子地圖選店頁 URL"""
|
|
184
|
+
return f'{self.base_url}/service/sevp_estore.aspx?merID={self.mer_id}&LogisticServiceID={service_id}&ReturnURL={return_url}'
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
# ============================================================================
|
|
188
|
+
# Examples
|
|
189
|
+
# ============================================================================
|
|
190
|
+
|
|
191
|
+
def example_711_b2c():
|
|
192
|
+
print('=== PayNow 7-11 大宗 B2C 取貨付款 ===\n')
|
|
193
|
+
svc = PayNowLogisticService(
|
|
194
|
+
mer_id='YOUR_MER_ID',
|
|
195
|
+
apicode='YOUR_APICODE',
|
|
196
|
+
key_3des=PayNowLogisticService.SAMPLE_KEY,
|
|
197
|
+
iv_3des=PayNowLogisticService.SAMPLE_IV,
|
|
198
|
+
is_test=True,
|
|
199
|
+
)
|
|
200
|
+
order = LogisticOrder(
|
|
201
|
+
service_id='20', # 7-11 大宗 B2C 常溫
|
|
202
|
+
goods_name='測試商品',
|
|
203
|
+
amount=1500,
|
|
204
|
+
sender_name='店家',
|
|
205
|
+
sender_phone='0227000000',
|
|
206
|
+
sender_address='台北市信義區信義路五段7號',
|
|
207
|
+
receiver_name='王小明',
|
|
208
|
+
receiver_phone='0912345678',
|
|
209
|
+
receiver_store_id='123456',
|
|
210
|
+
return_url='https://your-shop.com/api/paynow/notify',
|
|
211
|
+
is_cod=True,
|
|
212
|
+
)
|
|
213
|
+
try:
|
|
214
|
+
resp = svc.create_logistic(order)
|
|
215
|
+
if resp.success:
|
|
216
|
+
print(f'[OK] LogisticTradeNo={resp.logistic_trade_no}')
|
|
217
|
+
else:
|
|
218
|
+
print(f'[FAIL] {resp.status}: {resp.message}')
|
|
219
|
+
except Exception as e:
|
|
220
|
+
print(f'[ERROR] {e}')
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
def example_tcat_home():
|
|
224
|
+
print('\n=== PayNow 黑貓宅配 ===\n')
|
|
225
|
+
svc = PayNowLogisticService('YOUR_MER_ID', 'YOUR_APICODE',
|
|
226
|
+
PayNowLogisticService.SAMPLE_KEY,
|
|
227
|
+
PayNowLogisticService.SAMPLE_IV, is_test=True)
|
|
228
|
+
order = LogisticOrder(
|
|
229
|
+
service_id='50', # 黑貓宅配
|
|
230
|
+
goods_name='生鮮食品',
|
|
231
|
+
amount=2000,
|
|
232
|
+
sender_name='店家',
|
|
233
|
+
sender_phone='0227000000',
|
|
234
|
+
sender_address='台北市信義區',
|
|
235
|
+
receiver_name='王小明',
|
|
236
|
+
receiver_phone='0912345678',
|
|
237
|
+
receiver_address='台北市大安區忠孝東路四段1號',
|
|
238
|
+
return_url='https://your-shop.com/api/paynow/notify',
|
|
239
|
+
is_cod=True,
|
|
240
|
+
)
|
|
241
|
+
try:
|
|
242
|
+
resp = svc.create_logistic(order)
|
|
243
|
+
if resp.success:
|
|
244
|
+
print(f'[OK] LogisticTradeNo={resp.logistic_trade_no}')
|
|
245
|
+
else:
|
|
246
|
+
print(f'[FAIL] {resp.message}')
|
|
247
|
+
except Exception as e:
|
|
248
|
+
print(f'[ERROR] {e}')
|
|
249
|
+
|
|
250
|
+
|
|
251
|
+
def example_emap():
|
|
252
|
+
print('\n=== PayNow 電子地圖選店 ===\n')
|
|
253
|
+
svc = PayNowLogisticService('YOUR_MER_ID', 'YOUR_APICODE',
|
|
254
|
+
PayNowLogisticService.SAMPLE_KEY,
|
|
255
|
+
PayNowLogisticService.SAMPLE_IV, is_test=True)
|
|
256
|
+
url = svc.get_emap_url(service_id='40', return_url='https://your-shop.com/checkout/store-selected')
|
|
257
|
+
print(f'導轉至: {url}')
|
|
258
|
+
|
|
259
|
+
|
|
260
|
+
if __name__ == '__main__':
|
|
261
|
+
example_711_b2c()
|
|
262
|
+
example_tcat_home()
|
|
263
|
+
example_emap()
|