taiwan-logistics-skill 1.2.2 → 1.3.0
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 +132 -132
- package/assets/taiwan-logistics/CLAUDE.md +147 -137
- package/assets/taiwan-logistics/EXAMPLES.md +3258 -3258
- package/assets/taiwan-logistics/README.md +132 -132
- package/assets/taiwan-logistics/SKILL.md +845 -845
- package/assets/taiwan-logistics/data/field-mappings.csv +23 -27
- package/assets/taiwan-logistics/data/logistics-types.csv +29 -25
- package/assets/taiwan-logistics/data/operations.csv +32 -32
- package/assets/taiwan-logistics/data/providers.csv +20 -15
- package/assets/taiwan-logistics/data/status-codes.csv +89 -35
- package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +175 -175
- package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +524 -524
- package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +605 -605
- package/assets/taiwan-logistics/examples/store-map-integration-example.html +573 -573
- package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +774 -774
- package/assets/taiwan-logistics/references/carrier-direct-access.md +134 -0
- package/assets/taiwan-logistics/references/ecpay-logistics-api.md +536 -536
- package/assets/taiwan-logistics/references/ezship-logistics-api.md +103 -0
- package/assets/taiwan-logistics/references/hct-logistics-api.md +1102 -1102
- package/assets/taiwan-logistics/references/lalamove-logistics-api.md +138 -0
- package/assets/taiwan-logistics/references/paynow-logistics-api.md +1670 -1670
- package/assets/taiwan-logistics/references/payuni-logistics-api.md +712 -712
- package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1154 -1154
- package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1332 -1332
- package/assets/taiwan-logistics/scripts/core.py +276 -276
- package/assets/taiwan-logistics/scripts/generate-logistics-service.py +1248 -1248
- package/assets/taiwan-logistics/scripts/recommend.py +370 -364
- package/assets/taiwan-logistics/scripts/search.py +127 -127
- package/assets/taiwan-logistics/scripts/test_logistics.py +300 -300
- package/assets/templates/base/quick-reference.md +74 -74
- package/assets/templates/base/skill-content.md +845 -845
- package/assets/templates/platforms/agent.json +26 -26
- package/assets/templates/platforms/claude.json +26 -26
- package/assets/templates/platforms/codebuddy.json +25 -25
- package/assets/templates/platforms/codex.json +26 -26
- package/assets/templates/platforms/continue.json +25 -25
- package/assets/templates/platforms/copilot.json +25 -25
- package/assets/templates/platforms/cursor.json +26 -26
- package/assets/templates/platforms/gemini.json +25 -25
- package/assets/templates/platforms/kiro.json +25 -25
- package/assets/templates/platforms/opencode.json +25 -25
- package/assets/templates/platforms/qoder.json +25 -25
- package/assets/templates/platforms/roocode.json +25 -25
- package/assets/templates/platforms/trae.json +25 -25
- package/assets/templates/platforms/windsurf.json +25 -25
- package/package.json +65 -65
|
@@ -1,524 +1,524 @@
|
|
|
1
|
-
#!/usr/bin/env python3
|
|
2
|
-
"""
|
|
3
|
-
NewebPay 藍新物流 CVS 超商物流 Python 完整範例
|
|
4
|
-
|
|
5
|
-
依照 taiwan-logistics-skill 最高規範撰寫
|
|
6
|
-
支援: C2C 店到店 (7-11, 全家, 萊爾富, OK)、B2C 大宗寄倉
|
|
7
|
-
|
|
8
|
-
API 文件: https://www.newebpay.com
|
|
9
|
-
"""
|
|
10
|
-
|
|
11
|
-
import json
|
|
12
|
-
import hashlib
|
|
13
|
-
import time
|
|
14
|
-
import urllib.parse
|
|
15
|
-
from datetime import datetime
|
|
16
|
-
from typing import Dict, Literal, Optional
|
|
17
|
-
from dataclasses import dataclass, field
|
|
18
|
-
|
|
19
|
-
try:
|
|
20
|
-
from Crypto.Cipher import AES
|
|
21
|
-
from Crypto.Util.Padding import pad, unpad
|
|
22
|
-
import requests
|
|
23
|
-
HAS_DEPENDENCIES = True
|
|
24
|
-
except ImportError:
|
|
25
|
-
HAS_DEPENDENCIES = False
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
@dataclass
|
|
29
|
-
class CVSShipmentData:
|
|
30
|
-
"""CVS 超商物流訂單資料"""
|
|
31
|
-
merchant_order_no: str
|
|
32
|
-
lgs_type: Literal['B2C', 'C2C']
|
|
33
|
-
ship_type: Literal['1', '2', '3', '4'] # 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK
|
|
34
|
-
receiver_store_code: str
|
|
35
|
-
receiver_name: str
|
|
36
|
-
receiver_cell_phone: str
|
|
37
|
-
receiver_tel: Optional[str] = None
|
|
38
|
-
goods_amount: int = 0
|
|
39
|
-
goods_name: str = ''
|
|
40
|
-
sender_name: Optional[str] = None
|
|
41
|
-
sender_cell_phone: Optional[str] = None
|
|
42
|
-
is_collection: Literal['Y', 'N'] = 'N'
|
|
43
|
-
collection_amount: int = 0
|
|
44
|
-
note: Optional[str] = None
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
@dataclass
|
|
48
|
-
class CVSShipmentResponse:
|
|
49
|
-
"""CVS 超商物流訂單回應"""
|
|
50
|
-
success: bool
|
|
51
|
-
status: str
|
|
52
|
-
message: str
|
|
53
|
-
merchant_order_no: str
|
|
54
|
-
logistics_no: Optional[str] = None
|
|
55
|
-
cvs_payment_no: Optional[str] = None
|
|
56
|
-
cvs_validation_no: Optional[str] = None
|
|
57
|
-
booking_note: Optional[str] = None
|
|
58
|
-
raw: Dict = field(default_factory=dict)
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
@dataclass
|
|
62
|
-
class StoreMapData:
|
|
63
|
-
"""電子地圖門市查詢資料"""
|
|
64
|
-
merchant_order_no: str
|
|
65
|
-
lgs_type: Literal['B2C', 'C2C']
|
|
66
|
-
ship_type: Literal['1', '2', '3', '4']
|
|
67
|
-
return_url: str
|
|
68
|
-
extra_data: Optional[str] = None
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
@dataclass
|
|
72
|
-
class StoreMapCallback:
|
|
73
|
-
"""電子地圖門市選擇回傳"""
|
|
74
|
-
lgs_type: str
|
|
75
|
-
ship_type: str
|
|
76
|
-
merchant_order_no: str
|
|
77
|
-
store_id: str
|
|
78
|
-
store_name: str
|
|
79
|
-
store_addr: str
|
|
80
|
-
store_tel: str
|
|
81
|
-
extra_data: str
|
|
82
|
-
raw: Dict = field(default_factory=dict)
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
class NewebPayCVSLogistics:
|
|
86
|
-
"""
|
|
87
|
-
NewebPay 藍新物流 CVS 超商物流服務
|
|
88
|
-
|
|
89
|
-
認證方式: AES-256-CBC + SHA256
|
|
90
|
-
加密方式: JSON + AES-256-CBC 加密 + SHA256 驗證
|
|
91
|
-
|
|
92
|
-
支援超商:
|
|
93
|
-
- 1: 7-ELEVEN 統一超商
|
|
94
|
-
- 2: FamilyMart 全家便利商店
|
|
95
|
-
- 3: Hi-Life 萊爾富便利商店
|
|
96
|
-
- 4: OK Mart OK 便利商店
|
|
97
|
-
|
|
98
|
-
物流類型:
|
|
99
|
-
- C2C: 店到店 (店取、店寄)
|
|
100
|
-
- B2C: 大宗寄倉 (僅 7-11)
|
|
101
|
-
|
|
102
|
-
測試環境:
|
|
103
|
-
- 需至藍新金流申請測試帳號
|
|
104
|
-
- API URL: https://ccore.newebpay.com/API/Logistic
|
|
105
|
-
"""
|
|
106
|
-
|
|
107
|
-
# 測試環境
|
|
108
|
-
TEST_BASE_URL = 'https://ccore.newebpay.com/API/Logistic'
|
|
109
|
-
|
|
110
|
-
# 正式環境
|
|
111
|
-
PROD_BASE_URL = 'https://core.newebpay.com/API/Logistic'
|
|
112
|
-
|
|
113
|
-
def __init__(
|
|
114
|
-
self,
|
|
115
|
-
merchant_id: str,
|
|
116
|
-
hash_key: str,
|
|
117
|
-
hash_iv: str,
|
|
118
|
-
is_production: bool = False
|
|
119
|
-
):
|
|
120
|
-
"""
|
|
121
|
-
初始化 NewebPay CVS 物流服務
|
|
122
|
-
|
|
123
|
-
Args:
|
|
124
|
-
merchant_id: 商店代號
|
|
125
|
-
hash_key: HashKey (32 字元)
|
|
126
|
-
hash_iv: HashIV (16 字元)
|
|
127
|
-
is_production: 是否為正式環境 (預設 False)
|
|
128
|
-
|
|
129
|
-
Raises:
|
|
130
|
-
ImportError: 缺少必要套件
|
|
131
|
-
"""
|
|
132
|
-
if not HAS_DEPENDENCIES:
|
|
133
|
-
raise ImportError(
|
|
134
|
-
'需要安裝必要套件:\n'
|
|
135
|
-
' pip install pycryptodome requests'
|
|
136
|
-
)
|
|
137
|
-
|
|
138
|
-
self.merchant_id = merchant_id
|
|
139
|
-
self.hash_key = hash_key.encode('utf-8')
|
|
140
|
-
self.hash_iv = hash_iv.encode('utf-8')
|
|
141
|
-
self.base_url = self.PROD_BASE_URL if is_production else self.TEST_BASE_URL
|
|
142
|
-
|
|
143
|
-
def aes_encrypt(self, data: str) -> str:
|
|
144
|
-
"""
|
|
145
|
-
AES-256-CBC 加密
|
|
146
|
-
|
|
147
|
-
Args:
|
|
148
|
-
data: 明文字串
|
|
149
|
-
|
|
150
|
-
Returns:
|
|
151
|
-
str: 加密後的 hex 字串
|
|
152
|
-
"""
|
|
153
|
-
cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
|
|
154
|
-
padded_data = pad(data.encode('utf-8'), AES.block_size)
|
|
155
|
-
encrypted = cipher.encrypt(padded_data)
|
|
156
|
-
return encrypted.hex()
|
|
157
|
-
|
|
158
|
-
def aes_decrypt(self, encrypted_data: str) -> str:
|
|
159
|
-
"""
|
|
160
|
-
AES-256-CBC 解密
|
|
161
|
-
|
|
162
|
-
Args:
|
|
163
|
-
encrypted_data: 加密的 hex 字串
|
|
164
|
-
|
|
165
|
-
Returns:
|
|
166
|
-
str: 解密後的明文
|
|
167
|
-
|
|
168
|
-
Raises:
|
|
169
|
-
ValueError: 解密失敗
|
|
170
|
-
"""
|
|
171
|
-
try:
|
|
172
|
-
cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
|
|
173
|
-
decrypted = cipher.decrypt(bytes.fromhex(encrypted_data))
|
|
174
|
-
unpadded = unpad(decrypted, AES.block_size)
|
|
175
|
-
return unpadded.decode('utf-8')
|
|
176
|
-
except Exception as e:
|
|
177
|
-
raise ValueError(f'解密失敗: {str(e)}')
|
|
178
|
-
|
|
179
|
-
def generate_hash_data(self, encrypt_data: str) -> str:
|
|
180
|
-
"""
|
|
181
|
-
產生 HashData (SHA256)
|
|
182
|
-
|
|
183
|
-
Args:
|
|
184
|
-
encrypt_data: 加密後的資料
|
|
185
|
-
|
|
186
|
-
Returns:
|
|
187
|
-
str: SHA256 雜湊值 (大寫)
|
|
188
|
-
"""
|
|
189
|
-
raw = f"{self.hash_key.decode('utf-8')}{encrypt_data}{self.hash_iv.decode('utf-8')}"
|
|
190
|
-
return hashlib.sha256(raw.encode('utf-8')).hexdigest().upper()
|
|
191
|
-
|
|
192
|
-
def verify_hash_data(self, encrypt_data: str, hash_data: str) -> bool:
|
|
193
|
-
"""驗證 HashData"""
|
|
194
|
-
calculated_hash = self.generate_hash_data(encrypt_data)
|
|
195
|
-
return calculated_hash == hash_data.upper()
|
|
196
|
-
|
|
197
|
-
def query_store_map(
|
|
198
|
-
self,
|
|
199
|
-
data: StoreMapData,
|
|
200
|
-
) -> str:
|
|
201
|
-
"""
|
|
202
|
-
查詢電子地圖 (門市選擇)
|
|
203
|
-
|
|
204
|
-
Args:
|
|
205
|
-
data: 門市查詢資料 (StoreMapData)
|
|
206
|
-
|
|
207
|
-
Returns:
|
|
208
|
-
str: 重導向網址 (用戶選擇門市)
|
|
209
|
-
|
|
210
|
-
Example:
|
|
211
|
-
>>> store_data = StoreMapData(
|
|
212
|
-
... merchant_order_no='ORD123',
|
|
213
|
-
... lgs_type='C2C',
|
|
214
|
-
... ship_type='1',
|
|
215
|
-
... return_url='https://your-site.com/callback',
|
|
216
|
-
... )
|
|
217
|
-
>>> redirect_url = service.query_store_map(store_data)
|
|
218
|
-
"""
|
|
219
|
-
# 準備加密資料
|
|
220
|
-
encrypt_data_obj = {
|
|
221
|
-
'MerchantOrderNo': data.merchant_order_no,
|
|
222
|
-
'LgsType': data.lgs_type,
|
|
223
|
-
'ShipType': data.ship_type,
|
|
224
|
-
'ReturnURL': data.return_url,
|
|
225
|
-
'TimeStamp': str(int(time.time())),
|
|
226
|
-
}
|
|
227
|
-
|
|
228
|
-
if data.extra_data:
|
|
229
|
-
encrypt_data_obj['ExtraData'] = data.extra_data
|
|
230
|
-
|
|
231
|
-
# JSON 序列化並加密
|
|
232
|
-
json_str = json.dumps(encrypt_data_obj, ensure_ascii=False)
|
|
233
|
-
encrypt_data = self.aes_encrypt(json_str)
|
|
234
|
-
hash_data = self.generate_hash_data(encrypt_data)
|
|
235
|
-
|
|
236
|
-
# 準備 API 請求
|
|
237
|
-
api_data = {
|
|
238
|
-
'UID_': self.merchant_id,
|
|
239
|
-
'EncryptData_': encrypt_data,
|
|
240
|
-
'HashData_': hash_data,
|
|
241
|
-
'Version_': '1.0',
|
|
242
|
-
'RespondType_': 'JSON',
|
|
243
|
-
}
|
|
244
|
-
|
|
245
|
-
# 發送請求 (NewebPay 會重導向到門市選擇頁面)
|
|
246
|
-
response = requests.post(
|
|
247
|
-
f'{self.base_url}/storeMap',
|
|
248
|
-
data=api_data,
|
|
249
|
-
allow_redirects=False,
|
|
250
|
-
timeout=30,
|
|
251
|
-
)
|
|
252
|
-
|
|
253
|
-
# 回傳重導向網址
|
|
254
|
-
if response.status_code in [301, 302, 303]:
|
|
255
|
-
return response.headers.get('Location', '')
|
|
256
|
-
|
|
257
|
-
return response.url
|
|
258
|
-
|
|
259
|
-
def parse_store_map_callback(
|
|
260
|
-
self,
|
|
261
|
-
encrypt_data: str,
|
|
262
|
-
hash_data: str,
|
|
263
|
-
) -> StoreMapCallback:
|
|
264
|
-
"""
|
|
265
|
-
解析電子地圖回傳資料
|
|
266
|
-
|
|
267
|
-
Args:
|
|
268
|
-
encrypt_data: 加密資料
|
|
269
|
-
hash_data: 雜湊驗證值
|
|
270
|
-
|
|
271
|
-
Returns:
|
|
272
|
-
StoreMapCallback: 門市選擇結果
|
|
273
|
-
|
|
274
|
-
Raises:
|
|
275
|
-
ValueError: 驗證失敗
|
|
276
|
-
|
|
277
|
-
Example:
|
|
278
|
-
>>> callback = service.parse_store_map_callback(
|
|
279
|
-
... request.form['EncryptData_'],
|
|
280
|
-
... request.form['HashData_']
|
|
281
|
-
... )
|
|
282
|
-
>>> print(f"選擇門市: {callback.store_name}")
|
|
283
|
-
"""
|
|
284
|
-
# 驗證 HashData
|
|
285
|
-
if not self.verify_hash_data(encrypt_data, hash_data):
|
|
286
|
-
raise ValueError('HashData 驗證失敗')
|
|
287
|
-
|
|
288
|
-
# 解密資料
|
|
289
|
-
decrypted_json = self.aes_decrypt(encrypt_data)
|
|
290
|
-
decrypted = json.loads(decrypted_json)
|
|
291
|
-
|
|
292
|
-
return StoreMapCallback(
|
|
293
|
-
lgs_type=decrypted.get('LgsType', ''),
|
|
294
|
-
ship_type=decrypted.get('ShipType', ''),
|
|
295
|
-
merchant_order_no=decrypted.get('MerchantOrderNo', ''),
|
|
296
|
-
store_id=decrypted.get('StoreID', ''),
|
|
297
|
-
store_name=decrypted.get('StoreName', ''),
|
|
298
|
-
store_addr=decrypted.get('StoreAddr', ''),
|
|
299
|
-
store_tel=decrypted.get('StoreTel', ''),
|
|
300
|
-
extra_data=decrypted.get('ExtraData', ''),
|
|
301
|
-
raw=decrypted,
|
|
302
|
-
)
|
|
303
|
-
|
|
304
|
-
def create_shipment(
|
|
305
|
-
self,
|
|
306
|
-
data: CVSShipmentData,
|
|
307
|
-
) -> CVSShipmentResponse:
|
|
308
|
-
"""
|
|
309
|
-
建立 CVS 超商物流訂單
|
|
310
|
-
|
|
311
|
-
Args:
|
|
312
|
-
data: CVS 物流訂單資料 (CVSShipmentData)
|
|
313
|
-
|
|
314
|
-
Returns:
|
|
315
|
-
CVSShipmentResponse: 物流訂單回應
|
|
316
|
-
|
|
317
|
-
Raises:
|
|
318
|
-
ValueError: 參數驗證失敗
|
|
319
|
-
Exception: API 請求失敗
|
|
320
|
-
|
|
321
|
-
Example:
|
|
322
|
-
>>> shipment_data = CVSShipmentData(
|
|
323
|
-
... merchant_order_no='SHIP123',
|
|
324
|
-
... lgs_type='C2C',
|
|
325
|
-
... ship_type='1',
|
|
326
|
-
... receiver_store_code='123456',
|
|
327
|
-
... receiver_name='王小明',
|
|
328
|
-
... receiver_cell_phone='0912345678',
|
|
329
|
-
... goods_amount=500,
|
|
330
|
-
... goods_name='測試商品',
|
|
331
|
-
... is_collection='N',
|
|
332
|
-
... )
|
|
333
|
-
>>> result = service.create_shipment(shipment_data)
|
|
334
|
-
>>> print(result.logistics_no)
|
|
335
|
-
"""
|
|
336
|
-
# 參數驗證
|
|
337
|
-
if len(data.merchant_order_no) > 30:
|
|
338
|
-
raise ValueError('訂單編號不可超過 30 字元')
|
|
339
|
-
|
|
340
|
-
# 準備加密資料
|
|
341
|
-
encrypt_data_obj = {
|
|
342
|
-
'MerchantOrderNo': data.merchant_order_no,
|
|
343
|
-
'LgsType': data.lgs_type,
|
|
344
|
-
'ShipType': data.ship_type,
|
|
345
|
-
'ReceiverStoreCode': data.receiver_store_code,
|
|
346
|
-
'ReceiverName': data.receiver_name,
|
|
347
|
-
'ReceiverCellPhone': data.receiver_cell_phone,
|
|
348
|
-
'TimeStamp': str(int(time.time())),
|
|
349
|
-
}
|
|
350
|
-
|
|
351
|
-
# 可選參數
|
|
352
|
-
if data.receiver_tel:
|
|
353
|
-
encrypt_data_obj['ReceiverTel'] = data.receiver_tel
|
|
354
|
-
if data.goods_amount:
|
|
355
|
-
encrypt_data_obj['GoodsAmount'] = data.goods_amount
|
|
356
|
-
if data.goods_name:
|
|
357
|
-
encrypt_data_obj['GoodsName'] = data.goods_name
|
|
358
|
-
if data.sender_name:
|
|
359
|
-
encrypt_data_obj['SenderName'] = data.sender_name
|
|
360
|
-
if data.sender_cell_phone:
|
|
361
|
-
encrypt_data_obj['SenderCellPhone'] = data.sender_cell_phone
|
|
362
|
-
if data.is_collection == 'Y':
|
|
363
|
-
encrypt_data_obj['IsCollection'] = 'Y'
|
|
364
|
-
encrypt_data_obj['CollectionAmount'] = data.collection_amount
|
|
365
|
-
if data.note:
|
|
366
|
-
encrypt_data_obj['Note'] = data.note
|
|
367
|
-
|
|
368
|
-
# JSON 序列化並加密
|
|
369
|
-
json_str = json.dumps(encrypt_data_obj, ensure_ascii=False)
|
|
370
|
-
encrypt_data = self.aes_encrypt(json_str)
|
|
371
|
-
hash_data = self.generate_hash_data(encrypt_data)
|
|
372
|
-
|
|
373
|
-
# 準備 API 請求
|
|
374
|
-
api_data = {
|
|
375
|
-
'UID_': self.merchant_id,
|
|
376
|
-
'EncryptData_': encrypt_data,
|
|
377
|
-
'HashData_': hash_data,
|
|
378
|
-
'Version_': '1.0',
|
|
379
|
-
'RespondType_': 'JSON',
|
|
380
|
-
}
|
|
381
|
-
|
|
382
|
-
# 發送 API 請求
|
|
383
|
-
try:
|
|
384
|
-
response = requests.post(
|
|
385
|
-
f'{self.base_url}/createShipment',
|
|
386
|
-
data=api_data,
|
|
387
|
-
timeout=30,
|
|
388
|
-
)
|
|
389
|
-
response.raise_for_status()
|
|
390
|
-
result = response.json()
|
|
391
|
-
except Exception as e:
|
|
392
|
-
raise Exception(f'API 請求失敗: {str(e)}')
|
|
393
|
-
|
|
394
|
-
# 解析回應
|
|
395
|
-
if result.get('Status') != 'SUCCESS':
|
|
396
|
-
return CVSShipmentResponse(
|
|
397
|
-
success=False,
|
|
398
|
-
status=result.get('Status', 'ERROR'),
|
|
399
|
-
message=result.get('Message', '未知錯誤'),
|
|
400
|
-
merchant_order_no=data.merchant_order_no,
|
|
401
|
-
raw=result,
|
|
402
|
-
)
|
|
403
|
-
|
|
404
|
-
# 解密回應資料
|
|
405
|
-
response_encrypt_data = result.get('EncryptData_', '')
|
|
406
|
-
response_hash_data = result.get('HashData_', '')
|
|
407
|
-
|
|
408
|
-
if response_encrypt_data and response_hash_data:
|
|
409
|
-
try:
|
|
410
|
-
if not self.verify_hash_data(response_encrypt_data, response_hash_data):
|
|
411
|
-
raise ValueError('回應 HashData 驗證失敗')
|
|
412
|
-
|
|
413
|
-
decrypted_json = self.aes_decrypt(response_encrypt_data)
|
|
414
|
-
decrypted = json.loads(decrypted_json)
|
|
415
|
-
except Exception as e:
|
|
416
|
-
return CVSShipmentResponse(
|
|
417
|
-
success=False,
|
|
418
|
-
status='ERROR',
|
|
419
|
-
message=f'解密失敗: {str(e)}',
|
|
420
|
-
merchant_order_no=data.merchant_order_no,
|
|
421
|
-
raw=result,
|
|
422
|
-
)
|
|
423
|
-
else:
|
|
424
|
-
decrypted = {}
|
|
425
|
-
|
|
426
|
-
return CVSShipmentResponse(
|
|
427
|
-
success=True,
|
|
428
|
-
status=result.get('Status', ''),
|
|
429
|
-
message=result.get('Message', ''),
|
|
430
|
-
merchant_order_no=data.merchant_order_no,
|
|
431
|
-
logistics_no=decrypted.get('LogisticsNo'),
|
|
432
|
-
cvs_payment_no=decrypted.get('CVSPaymentNo'),
|
|
433
|
-
cvs_validation_no=decrypted.get('CVSValidationNo'),
|
|
434
|
-
booking_note=decrypted.get('BookingNote'),
|
|
435
|
-
raw=result,
|
|
436
|
-
)
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
# Usage Example
|
|
440
|
-
if __name__ == '__main__':
|
|
441
|
-
print('=' * 60)
|
|
442
|
-
print('NewebPay 藍新物流 CVS - Python 範例')
|
|
443
|
-
print('=' * 60)
|
|
444
|
-
print()
|
|
445
|
-
|
|
446
|
-
# 檢查依賴套件
|
|
447
|
-
if not HAS_DEPENDENCIES:
|
|
448
|
-
print('✗ 錯誤: 需要安裝必要套件')
|
|
449
|
-
print(' 請執行: pip install pycryptodome requests')
|
|
450
|
-
exit(1)
|
|
451
|
-
|
|
452
|
-
print('[注意] 請先至藍新金流申請測試帳號')
|
|
453
|
-
print('並將以下參數替換為您的測試環境資訊')
|
|
454
|
-
print()
|
|
455
|
-
|
|
456
|
-
# 初始化服務 (使用測試環境)
|
|
457
|
-
service = NewebPayCVSLogistics(
|
|
458
|
-
merchant_id='YOUR_MERCHANT_ID',
|
|
459
|
-
hash_key='YOUR_HASH_KEY', # 32 字元
|
|
460
|
-
hash_iv='YOUR_HASH_IV', # 16 字元
|
|
461
|
-
is_production=False,
|
|
462
|
-
)
|
|
463
|
-
|
|
464
|
-
# 範例 1: 查詢電子地圖 (門市選擇)
|
|
465
|
-
print('[範例 1] 查詢電子地圖 (門市選擇)')
|
|
466
|
-
print('-' * 60)
|
|
467
|
-
|
|
468
|
-
store_data = StoreMapData(
|
|
469
|
-
merchant_order_no=f'MAP{int(time.time())}',
|
|
470
|
-
lgs_type='C2C',
|
|
471
|
-
ship_type='1', # 7-ELEVEN
|
|
472
|
-
return_url='https://your-site.com/callback/store-map',
|
|
473
|
-
extra_data='order_id=123',
|
|
474
|
-
)
|
|
475
|
-
|
|
476
|
-
try:
|
|
477
|
-
redirect_url = service.query_store_map(store_data)
|
|
478
|
-
print(f'✓ 電子地圖網址: {redirect_url}')
|
|
479
|
-
print('請將使用者導向此網址選擇門市')
|
|
480
|
-
except Exception as e:
|
|
481
|
-
print(f'✗ 發生例外: {str(e)}')
|
|
482
|
-
|
|
483
|
-
print()
|
|
484
|
-
print('-' * 60)
|
|
485
|
-
|
|
486
|
-
# 範例 2: 建立 C2C 物流訂單
|
|
487
|
-
print('[範例 2] 建立 C2C 物流訂單')
|
|
488
|
-
print('-' * 60)
|
|
489
|
-
|
|
490
|
-
shipment_data = CVSShipmentData(
|
|
491
|
-
merchant_order_no=f'SHIP{int(time.time())}',
|
|
492
|
-
lgs_type='C2C',
|
|
493
|
-
ship_type='1', # 7-ELEVEN
|
|
494
|
-
receiver_store_code='123456', # 收件門市代號 (從電子地圖取得)
|
|
495
|
-
receiver_name='王小明',
|
|
496
|
-
receiver_cell_phone='0912345678',
|
|
497
|
-
goods_amount=500,
|
|
498
|
-
goods_name='測試商品',
|
|
499
|
-
sender_name='賣家',
|
|
500
|
-
sender_cell_phone='0987654321',
|
|
501
|
-
is_collection='N', # 不代收貨款
|
|
502
|
-
)
|
|
503
|
-
|
|
504
|
-
try:
|
|
505
|
-
result = service.create_shipment(shipment_data)
|
|
506
|
-
|
|
507
|
-
if result.success:
|
|
508
|
-
print(f'✓ 物流訂單建立成功')
|
|
509
|
-
print(f' 訂單編號: {result.merchant_order_no}')
|
|
510
|
-
print(f' 物流編號: {result.logistics_no}')
|
|
511
|
-
print(f' 寄貨編號: {result.cvs_payment_no}')
|
|
512
|
-
print(f' 驗證碼: {result.cvs_validation_no}')
|
|
513
|
-
print(f' 托運單號: {result.booking_note}')
|
|
514
|
-
else:
|
|
515
|
-
print(f'✗ 物流訂單建立失敗')
|
|
516
|
-
print(f' 狀態: {result.status}')
|
|
517
|
-
print(f' 訊息: {result.message}')
|
|
518
|
-
except Exception as e:
|
|
519
|
-
print(f'✗ 發生例外: {str(e)}')
|
|
520
|
-
|
|
521
|
-
print()
|
|
522
|
-
print('=' * 60)
|
|
523
|
-
print('範例執行完成')
|
|
524
|
-
print('=' * 60)
|
|
1
|
+
#!/usr/bin/env python3
|
|
2
|
+
"""
|
|
3
|
+
NewebPay 藍新物流 CVS 超商物流 Python 完整範例
|
|
4
|
+
|
|
5
|
+
依照 taiwan-logistics-skill 最高規範撰寫
|
|
6
|
+
支援: C2C 店到店 (7-11, 全家, 萊爾富, OK)、B2C 大宗寄倉
|
|
7
|
+
|
|
8
|
+
API 文件: https://www.newebpay.com
|
|
9
|
+
"""
|
|
10
|
+
|
|
11
|
+
import json
|
|
12
|
+
import hashlib
|
|
13
|
+
import time
|
|
14
|
+
import urllib.parse
|
|
15
|
+
from datetime import datetime
|
|
16
|
+
from typing import Dict, Literal, Optional
|
|
17
|
+
from dataclasses import dataclass, field
|
|
18
|
+
|
|
19
|
+
try:
|
|
20
|
+
from Crypto.Cipher import AES
|
|
21
|
+
from Crypto.Util.Padding import pad, unpad
|
|
22
|
+
import requests
|
|
23
|
+
HAS_DEPENDENCIES = True
|
|
24
|
+
except ImportError:
|
|
25
|
+
HAS_DEPENDENCIES = False
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
@dataclass
|
|
29
|
+
class CVSShipmentData:
|
|
30
|
+
"""CVS 超商物流訂單資料"""
|
|
31
|
+
merchant_order_no: str
|
|
32
|
+
lgs_type: Literal['B2C', 'C2C']
|
|
33
|
+
ship_type: Literal['1', '2', '3', '4'] # 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK
|
|
34
|
+
receiver_store_code: str
|
|
35
|
+
receiver_name: str
|
|
36
|
+
receiver_cell_phone: str
|
|
37
|
+
receiver_tel: Optional[str] = None
|
|
38
|
+
goods_amount: int = 0
|
|
39
|
+
goods_name: str = ''
|
|
40
|
+
sender_name: Optional[str] = None
|
|
41
|
+
sender_cell_phone: Optional[str] = None
|
|
42
|
+
is_collection: Literal['Y', 'N'] = 'N'
|
|
43
|
+
collection_amount: int = 0
|
|
44
|
+
note: Optional[str] = None
|
|
45
|
+
|
|
46
|
+
|
|
47
|
+
@dataclass
|
|
48
|
+
class CVSShipmentResponse:
|
|
49
|
+
"""CVS 超商物流訂單回應"""
|
|
50
|
+
success: bool
|
|
51
|
+
status: str
|
|
52
|
+
message: str
|
|
53
|
+
merchant_order_no: str
|
|
54
|
+
logistics_no: Optional[str] = None
|
|
55
|
+
cvs_payment_no: Optional[str] = None
|
|
56
|
+
cvs_validation_no: Optional[str] = None
|
|
57
|
+
booking_note: Optional[str] = None
|
|
58
|
+
raw: Dict = field(default_factory=dict)
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
@dataclass
|
|
62
|
+
class StoreMapData:
|
|
63
|
+
"""電子地圖門市查詢資料"""
|
|
64
|
+
merchant_order_no: str
|
|
65
|
+
lgs_type: Literal['B2C', 'C2C']
|
|
66
|
+
ship_type: Literal['1', '2', '3', '4']
|
|
67
|
+
return_url: str
|
|
68
|
+
extra_data: Optional[str] = None
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
@dataclass
|
|
72
|
+
class StoreMapCallback:
|
|
73
|
+
"""電子地圖門市選擇回傳"""
|
|
74
|
+
lgs_type: str
|
|
75
|
+
ship_type: str
|
|
76
|
+
merchant_order_no: str
|
|
77
|
+
store_id: str
|
|
78
|
+
store_name: str
|
|
79
|
+
store_addr: str
|
|
80
|
+
store_tel: str
|
|
81
|
+
extra_data: str
|
|
82
|
+
raw: Dict = field(default_factory=dict)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
class NewebPayCVSLogistics:
|
|
86
|
+
"""
|
|
87
|
+
NewebPay 藍新物流 CVS 超商物流服務
|
|
88
|
+
|
|
89
|
+
認證方式: AES-256-CBC + SHA256
|
|
90
|
+
加密方式: JSON + AES-256-CBC 加密 + SHA256 驗證
|
|
91
|
+
|
|
92
|
+
支援超商:
|
|
93
|
+
- 1: 7-ELEVEN 統一超商
|
|
94
|
+
- 2: FamilyMart 全家便利商店
|
|
95
|
+
- 3: Hi-Life 萊爾富便利商店
|
|
96
|
+
- 4: OK Mart OK 便利商店
|
|
97
|
+
|
|
98
|
+
物流類型:
|
|
99
|
+
- C2C: 店到店 (店取、店寄)
|
|
100
|
+
- B2C: 大宗寄倉 (僅 7-11)
|
|
101
|
+
|
|
102
|
+
測試環境:
|
|
103
|
+
- 需至藍新金流申請測試帳號
|
|
104
|
+
- API URL: https://ccore.newebpay.com/API/Logistic
|
|
105
|
+
"""
|
|
106
|
+
|
|
107
|
+
# 測試環境
|
|
108
|
+
TEST_BASE_URL = 'https://ccore.newebpay.com/API/Logistic'
|
|
109
|
+
|
|
110
|
+
# 正式環境
|
|
111
|
+
PROD_BASE_URL = 'https://core.newebpay.com/API/Logistic'
|
|
112
|
+
|
|
113
|
+
def __init__(
|
|
114
|
+
self,
|
|
115
|
+
merchant_id: str,
|
|
116
|
+
hash_key: str,
|
|
117
|
+
hash_iv: str,
|
|
118
|
+
is_production: bool = False
|
|
119
|
+
):
|
|
120
|
+
"""
|
|
121
|
+
初始化 NewebPay CVS 物流服務
|
|
122
|
+
|
|
123
|
+
Args:
|
|
124
|
+
merchant_id: 商店代號
|
|
125
|
+
hash_key: HashKey (32 字元)
|
|
126
|
+
hash_iv: HashIV (16 字元)
|
|
127
|
+
is_production: 是否為正式環境 (預設 False)
|
|
128
|
+
|
|
129
|
+
Raises:
|
|
130
|
+
ImportError: 缺少必要套件
|
|
131
|
+
"""
|
|
132
|
+
if not HAS_DEPENDENCIES:
|
|
133
|
+
raise ImportError(
|
|
134
|
+
'需要安裝必要套件:\n'
|
|
135
|
+
' pip install pycryptodome requests'
|
|
136
|
+
)
|
|
137
|
+
|
|
138
|
+
self.merchant_id = merchant_id
|
|
139
|
+
self.hash_key = hash_key.encode('utf-8')
|
|
140
|
+
self.hash_iv = hash_iv.encode('utf-8')
|
|
141
|
+
self.base_url = self.PROD_BASE_URL if is_production else self.TEST_BASE_URL
|
|
142
|
+
|
|
143
|
+
def aes_encrypt(self, data: str) -> str:
|
|
144
|
+
"""
|
|
145
|
+
AES-256-CBC 加密
|
|
146
|
+
|
|
147
|
+
Args:
|
|
148
|
+
data: 明文字串
|
|
149
|
+
|
|
150
|
+
Returns:
|
|
151
|
+
str: 加密後的 hex 字串
|
|
152
|
+
"""
|
|
153
|
+
cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
|
|
154
|
+
padded_data = pad(data.encode('utf-8'), AES.block_size)
|
|
155
|
+
encrypted = cipher.encrypt(padded_data)
|
|
156
|
+
return encrypted.hex()
|
|
157
|
+
|
|
158
|
+
def aes_decrypt(self, encrypted_data: str) -> str:
|
|
159
|
+
"""
|
|
160
|
+
AES-256-CBC 解密
|
|
161
|
+
|
|
162
|
+
Args:
|
|
163
|
+
encrypted_data: 加密的 hex 字串
|
|
164
|
+
|
|
165
|
+
Returns:
|
|
166
|
+
str: 解密後的明文
|
|
167
|
+
|
|
168
|
+
Raises:
|
|
169
|
+
ValueError: 解密失敗
|
|
170
|
+
"""
|
|
171
|
+
try:
|
|
172
|
+
cipher = AES.new(self.hash_key, AES.MODE_CBC, self.hash_iv)
|
|
173
|
+
decrypted = cipher.decrypt(bytes.fromhex(encrypted_data))
|
|
174
|
+
unpadded = unpad(decrypted, AES.block_size)
|
|
175
|
+
return unpadded.decode('utf-8')
|
|
176
|
+
except Exception as e:
|
|
177
|
+
raise ValueError(f'解密失敗: {str(e)}')
|
|
178
|
+
|
|
179
|
+
def generate_hash_data(self, encrypt_data: str) -> str:
|
|
180
|
+
"""
|
|
181
|
+
產生 HashData (SHA256)
|
|
182
|
+
|
|
183
|
+
Args:
|
|
184
|
+
encrypt_data: 加密後的資料
|
|
185
|
+
|
|
186
|
+
Returns:
|
|
187
|
+
str: SHA256 雜湊值 (大寫)
|
|
188
|
+
"""
|
|
189
|
+
raw = f"{self.hash_key.decode('utf-8')}{encrypt_data}{self.hash_iv.decode('utf-8')}"
|
|
190
|
+
return hashlib.sha256(raw.encode('utf-8')).hexdigest().upper()
|
|
191
|
+
|
|
192
|
+
def verify_hash_data(self, encrypt_data: str, hash_data: str) -> bool:
|
|
193
|
+
"""驗證 HashData"""
|
|
194
|
+
calculated_hash = self.generate_hash_data(encrypt_data)
|
|
195
|
+
return calculated_hash == hash_data.upper()
|
|
196
|
+
|
|
197
|
+
def query_store_map(
|
|
198
|
+
self,
|
|
199
|
+
data: StoreMapData,
|
|
200
|
+
) -> str:
|
|
201
|
+
"""
|
|
202
|
+
查詢電子地圖 (門市選擇)
|
|
203
|
+
|
|
204
|
+
Args:
|
|
205
|
+
data: 門市查詢資料 (StoreMapData)
|
|
206
|
+
|
|
207
|
+
Returns:
|
|
208
|
+
str: 重導向網址 (用戶選擇門市)
|
|
209
|
+
|
|
210
|
+
Example:
|
|
211
|
+
>>> store_data = StoreMapData(
|
|
212
|
+
... merchant_order_no='ORD123',
|
|
213
|
+
... lgs_type='C2C',
|
|
214
|
+
... ship_type='1',
|
|
215
|
+
... return_url='https://your-site.com/callback',
|
|
216
|
+
... )
|
|
217
|
+
>>> redirect_url = service.query_store_map(store_data)
|
|
218
|
+
"""
|
|
219
|
+
# 準備加密資料
|
|
220
|
+
encrypt_data_obj = {
|
|
221
|
+
'MerchantOrderNo': data.merchant_order_no,
|
|
222
|
+
'LgsType': data.lgs_type,
|
|
223
|
+
'ShipType': data.ship_type,
|
|
224
|
+
'ReturnURL': data.return_url,
|
|
225
|
+
'TimeStamp': str(int(time.time())),
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
if data.extra_data:
|
|
229
|
+
encrypt_data_obj['ExtraData'] = data.extra_data
|
|
230
|
+
|
|
231
|
+
# JSON 序列化並加密
|
|
232
|
+
json_str = json.dumps(encrypt_data_obj, ensure_ascii=False)
|
|
233
|
+
encrypt_data = self.aes_encrypt(json_str)
|
|
234
|
+
hash_data = self.generate_hash_data(encrypt_data)
|
|
235
|
+
|
|
236
|
+
# 準備 API 請求
|
|
237
|
+
api_data = {
|
|
238
|
+
'UID_': self.merchant_id,
|
|
239
|
+
'EncryptData_': encrypt_data,
|
|
240
|
+
'HashData_': hash_data,
|
|
241
|
+
'Version_': '1.0',
|
|
242
|
+
'RespondType_': 'JSON',
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
# 發送請求 (NewebPay 會重導向到門市選擇頁面)
|
|
246
|
+
response = requests.post(
|
|
247
|
+
f'{self.base_url}/storeMap',
|
|
248
|
+
data=api_data,
|
|
249
|
+
allow_redirects=False,
|
|
250
|
+
timeout=30,
|
|
251
|
+
)
|
|
252
|
+
|
|
253
|
+
# 回傳重導向網址
|
|
254
|
+
if response.status_code in [301, 302, 303]:
|
|
255
|
+
return response.headers.get('Location', '')
|
|
256
|
+
|
|
257
|
+
return response.url
|
|
258
|
+
|
|
259
|
+
def parse_store_map_callback(
|
|
260
|
+
self,
|
|
261
|
+
encrypt_data: str,
|
|
262
|
+
hash_data: str,
|
|
263
|
+
) -> StoreMapCallback:
|
|
264
|
+
"""
|
|
265
|
+
解析電子地圖回傳資料
|
|
266
|
+
|
|
267
|
+
Args:
|
|
268
|
+
encrypt_data: 加密資料
|
|
269
|
+
hash_data: 雜湊驗證值
|
|
270
|
+
|
|
271
|
+
Returns:
|
|
272
|
+
StoreMapCallback: 門市選擇結果
|
|
273
|
+
|
|
274
|
+
Raises:
|
|
275
|
+
ValueError: 驗證失敗
|
|
276
|
+
|
|
277
|
+
Example:
|
|
278
|
+
>>> callback = service.parse_store_map_callback(
|
|
279
|
+
... request.form['EncryptData_'],
|
|
280
|
+
... request.form['HashData_']
|
|
281
|
+
... )
|
|
282
|
+
>>> print(f"選擇門市: {callback.store_name}")
|
|
283
|
+
"""
|
|
284
|
+
# 驗證 HashData
|
|
285
|
+
if not self.verify_hash_data(encrypt_data, hash_data):
|
|
286
|
+
raise ValueError('HashData 驗證失敗')
|
|
287
|
+
|
|
288
|
+
# 解密資料
|
|
289
|
+
decrypted_json = self.aes_decrypt(encrypt_data)
|
|
290
|
+
decrypted = json.loads(decrypted_json)
|
|
291
|
+
|
|
292
|
+
return StoreMapCallback(
|
|
293
|
+
lgs_type=decrypted.get('LgsType', ''),
|
|
294
|
+
ship_type=decrypted.get('ShipType', ''),
|
|
295
|
+
merchant_order_no=decrypted.get('MerchantOrderNo', ''),
|
|
296
|
+
store_id=decrypted.get('StoreID', ''),
|
|
297
|
+
store_name=decrypted.get('StoreName', ''),
|
|
298
|
+
store_addr=decrypted.get('StoreAddr', ''),
|
|
299
|
+
store_tel=decrypted.get('StoreTel', ''),
|
|
300
|
+
extra_data=decrypted.get('ExtraData', ''),
|
|
301
|
+
raw=decrypted,
|
|
302
|
+
)
|
|
303
|
+
|
|
304
|
+
def create_shipment(
|
|
305
|
+
self,
|
|
306
|
+
data: CVSShipmentData,
|
|
307
|
+
) -> CVSShipmentResponse:
|
|
308
|
+
"""
|
|
309
|
+
建立 CVS 超商物流訂單
|
|
310
|
+
|
|
311
|
+
Args:
|
|
312
|
+
data: CVS 物流訂單資料 (CVSShipmentData)
|
|
313
|
+
|
|
314
|
+
Returns:
|
|
315
|
+
CVSShipmentResponse: 物流訂單回應
|
|
316
|
+
|
|
317
|
+
Raises:
|
|
318
|
+
ValueError: 參數驗證失敗
|
|
319
|
+
Exception: API 請求失敗
|
|
320
|
+
|
|
321
|
+
Example:
|
|
322
|
+
>>> shipment_data = CVSShipmentData(
|
|
323
|
+
... merchant_order_no='SHIP123',
|
|
324
|
+
... lgs_type='C2C',
|
|
325
|
+
... ship_type='1',
|
|
326
|
+
... receiver_store_code='123456',
|
|
327
|
+
... receiver_name='王小明',
|
|
328
|
+
... receiver_cell_phone='0912345678',
|
|
329
|
+
... goods_amount=500,
|
|
330
|
+
... goods_name='測試商品',
|
|
331
|
+
... is_collection='N',
|
|
332
|
+
... )
|
|
333
|
+
>>> result = service.create_shipment(shipment_data)
|
|
334
|
+
>>> print(result.logistics_no)
|
|
335
|
+
"""
|
|
336
|
+
# 參數驗證
|
|
337
|
+
if len(data.merchant_order_no) > 30:
|
|
338
|
+
raise ValueError('訂單編號不可超過 30 字元')
|
|
339
|
+
|
|
340
|
+
# 準備加密資料
|
|
341
|
+
encrypt_data_obj = {
|
|
342
|
+
'MerchantOrderNo': data.merchant_order_no,
|
|
343
|
+
'LgsType': data.lgs_type,
|
|
344
|
+
'ShipType': data.ship_type,
|
|
345
|
+
'ReceiverStoreCode': data.receiver_store_code,
|
|
346
|
+
'ReceiverName': data.receiver_name,
|
|
347
|
+
'ReceiverCellPhone': data.receiver_cell_phone,
|
|
348
|
+
'TimeStamp': str(int(time.time())),
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
# 可選參數
|
|
352
|
+
if data.receiver_tel:
|
|
353
|
+
encrypt_data_obj['ReceiverTel'] = data.receiver_tel
|
|
354
|
+
if data.goods_amount:
|
|
355
|
+
encrypt_data_obj['GoodsAmount'] = data.goods_amount
|
|
356
|
+
if data.goods_name:
|
|
357
|
+
encrypt_data_obj['GoodsName'] = data.goods_name
|
|
358
|
+
if data.sender_name:
|
|
359
|
+
encrypt_data_obj['SenderName'] = data.sender_name
|
|
360
|
+
if data.sender_cell_phone:
|
|
361
|
+
encrypt_data_obj['SenderCellPhone'] = data.sender_cell_phone
|
|
362
|
+
if data.is_collection == 'Y':
|
|
363
|
+
encrypt_data_obj['IsCollection'] = 'Y'
|
|
364
|
+
encrypt_data_obj['CollectionAmount'] = data.collection_amount
|
|
365
|
+
if data.note:
|
|
366
|
+
encrypt_data_obj['Note'] = data.note
|
|
367
|
+
|
|
368
|
+
# JSON 序列化並加密
|
|
369
|
+
json_str = json.dumps(encrypt_data_obj, ensure_ascii=False)
|
|
370
|
+
encrypt_data = self.aes_encrypt(json_str)
|
|
371
|
+
hash_data = self.generate_hash_data(encrypt_data)
|
|
372
|
+
|
|
373
|
+
# 準備 API 請求
|
|
374
|
+
api_data = {
|
|
375
|
+
'UID_': self.merchant_id,
|
|
376
|
+
'EncryptData_': encrypt_data,
|
|
377
|
+
'HashData_': hash_data,
|
|
378
|
+
'Version_': '1.0',
|
|
379
|
+
'RespondType_': 'JSON',
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
# 發送 API 請求
|
|
383
|
+
try:
|
|
384
|
+
response = requests.post(
|
|
385
|
+
f'{self.base_url}/createShipment',
|
|
386
|
+
data=api_data,
|
|
387
|
+
timeout=30,
|
|
388
|
+
)
|
|
389
|
+
response.raise_for_status()
|
|
390
|
+
result = response.json()
|
|
391
|
+
except Exception as e:
|
|
392
|
+
raise Exception(f'API 請求失敗: {str(e)}')
|
|
393
|
+
|
|
394
|
+
# 解析回應
|
|
395
|
+
if result.get('Status') != 'SUCCESS':
|
|
396
|
+
return CVSShipmentResponse(
|
|
397
|
+
success=False,
|
|
398
|
+
status=result.get('Status', 'ERROR'),
|
|
399
|
+
message=result.get('Message', '未知錯誤'),
|
|
400
|
+
merchant_order_no=data.merchant_order_no,
|
|
401
|
+
raw=result,
|
|
402
|
+
)
|
|
403
|
+
|
|
404
|
+
# 解密回應資料
|
|
405
|
+
response_encrypt_data = result.get('EncryptData_', '')
|
|
406
|
+
response_hash_data = result.get('HashData_', '')
|
|
407
|
+
|
|
408
|
+
if response_encrypt_data and response_hash_data:
|
|
409
|
+
try:
|
|
410
|
+
if not self.verify_hash_data(response_encrypt_data, response_hash_data):
|
|
411
|
+
raise ValueError('回應 HashData 驗證失敗')
|
|
412
|
+
|
|
413
|
+
decrypted_json = self.aes_decrypt(response_encrypt_data)
|
|
414
|
+
decrypted = json.loads(decrypted_json)
|
|
415
|
+
except Exception as e:
|
|
416
|
+
return CVSShipmentResponse(
|
|
417
|
+
success=False,
|
|
418
|
+
status='ERROR',
|
|
419
|
+
message=f'解密失敗: {str(e)}',
|
|
420
|
+
merchant_order_no=data.merchant_order_no,
|
|
421
|
+
raw=result,
|
|
422
|
+
)
|
|
423
|
+
else:
|
|
424
|
+
decrypted = {}
|
|
425
|
+
|
|
426
|
+
return CVSShipmentResponse(
|
|
427
|
+
success=True,
|
|
428
|
+
status=result.get('Status', ''),
|
|
429
|
+
message=result.get('Message', ''),
|
|
430
|
+
merchant_order_no=data.merchant_order_no,
|
|
431
|
+
logistics_no=decrypted.get('LogisticsNo'),
|
|
432
|
+
cvs_payment_no=decrypted.get('CVSPaymentNo'),
|
|
433
|
+
cvs_validation_no=decrypted.get('CVSValidationNo'),
|
|
434
|
+
booking_note=decrypted.get('BookingNote'),
|
|
435
|
+
raw=result,
|
|
436
|
+
)
|
|
437
|
+
|
|
438
|
+
|
|
439
|
+
# Usage Example
|
|
440
|
+
if __name__ == '__main__':
|
|
441
|
+
print('=' * 60)
|
|
442
|
+
print('NewebPay 藍新物流 CVS - Python 範例')
|
|
443
|
+
print('=' * 60)
|
|
444
|
+
print()
|
|
445
|
+
|
|
446
|
+
# 檢查依賴套件
|
|
447
|
+
if not HAS_DEPENDENCIES:
|
|
448
|
+
print('✗ 錯誤: 需要安裝必要套件')
|
|
449
|
+
print(' 請執行: pip install pycryptodome requests')
|
|
450
|
+
exit(1)
|
|
451
|
+
|
|
452
|
+
print('[注意] 請先至藍新金流申請測試帳號')
|
|
453
|
+
print('並將以下參數替換為您的測試環境資訊')
|
|
454
|
+
print()
|
|
455
|
+
|
|
456
|
+
# 初始化服務 (使用測試環境)
|
|
457
|
+
service = NewebPayCVSLogistics(
|
|
458
|
+
merchant_id='YOUR_MERCHANT_ID',
|
|
459
|
+
hash_key='YOUR_HASH_KEY', # 32 字元
|
|
460
|
+
hash_iv='YOUR_HASH_IV', # 16 字元
|
|
461
|
+
is_production=False,
|
|
462
|
+
)
|
|
463
|
+
|
|
464
|
+
# 範例 1: 查詢電子地圖 (門市選擇)
|
|
465
|
+
print('[範例 1] 查詢電子地圖 (門市選擇)')
|
|
466
|
+
print('-' * 60)
|
|
467
|
+
|
|
468
|
+
store_data = StoreMapData(
|
|
469
|
+
merchant_order_no=f'MAP{int(time.time())}',
|
|
470
|
+
lgs_type='C2C',
|
|
471
|
+
ship_type='1', # 7-ELEVEN
|
|
472
|
+
return_url='https://your-site.com/callback/store-map',
|
|
473
|
+
extra_data='order_id=123',
|
|
474
|
+
)
|
|
475
|
+
|
|
476
|
+
try:
|
|
477
|
+
redirect_url = service.query_store_map(store_data)
|
|
478
|
+
print(f'✓ 電子地圖網址: {redirect_url}')
|
|
479
|
+
print('請將使用者導向此網址選擇門市')
|
|
480
|
+
except Exception as e:
|
|
481
|
+
print(f'✗ 發生例外: {str(e)}')
|
|
482
|
+
|
|
483
|
+
print()
|
|
484
|
+
print('-' * 60)
|
|
485
|
+
|
|
486
|
+
# 範例 2: 建立 C2C 物流訂單
|
|
487
|
+
print('[範例 2] 建立 C2C 物流訂單')
|
|
488
|
+
print('-' * 60)
|
|
489
|
+
|
|
490
|
+
shipment_data = CVSShipmentData(
|
|
491
|
+
merchant_order_no=f'SHIP{int(time.time())}',
|
|
492
|
+
lgs_type='C2C',
|
|
493
|
+
ship_type='1', # 7-ELEVEN
|
|
494
|
+
receiver_store_code='123456', # 收件門市代號 (從電子地圖取得)
|
|
495
|
+
receiver_name='王小明',
|
|
496
|
+
receiver_cell_phone='0912345678',
|
|
497
|
+
goods_amount=500,
|
|
498
|
+
goods_name='測試商品',
|
|
499
|
+
sender_name='賣家',
|
|
500
|
+
sender_cell_phone='0987654321',
|
|
501
|
+
is_collection='N', # 不代收貨款
|
|
502
|
+
)
|
|
503
|
+
|
|
504
|
+
try:
|
|
505
|
+
result = service.create_shipment(shipment_data)
|
|
506
|
+
|
|
507
|
+
if result.success:
|
|
508
|
+
print(f'✓ 物流訂單建立成功')
|
|
509
|
+
print(f' 訂單編號: {result.merchant_order_no}')
|
|
510
|
+
print(f' 物流編號: {result.logistics_no}')
|
|
511
|
+
print(f' 寄貨編號: {result.cvs_payment_no}')
|
|
512
|
+
print(f' 驗證碼: {result.cvs_validation_no}')
|
|
513
|
+
print(f' 托運單號: {result.booking_note}')
|
|
514
|
+
else:
|
|
515
|
+
print(f'✗ 物流訂單建立失敗')
|
|
516
|
+
print(f' 狀態: {result.status}')
|
|
517
|
+
print(f' 訊息: {result.message}')
|
|
518
|
+
except Exception as e:
|
|
519
|
+
print(f'✗ 發生例外: {str(e)}')
|
|
520
|
+
|
|
521
|
+
print()
|
|
522
|
+
print('=' * 60)
|
|
523
|
+
print('範例執行完成')
|
|
524
|
+
print('=' * 60)
|