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.
@@ -1,263 +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()
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()