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.
@@ -0,0 +1,255 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ PChomePay 拍錢包物流 Python 範例
4
+
5
+ 依 taiwan-logistics-skill 規範撰寫。
6
+ PChomePay 物流走 7-11 / 全家 / 萊爾富 / OK 四大超商,金物流二合一設計。
7
+
8
+ 支援:
9
+ - 取號列印交寄單 (/v1/logistic/batch)
10
+ - 物流歷程查詢 (/v1/logistic/query/{order_id}/history)
11
+ - 未出貨/未取貨查詢 (/v1/logistic/yet, /v1/logistic/store_return/{date})
12
+ - 物流手續費對帳 (/v1/logistic/accounting/{date} - NDJSON 格式)
13
+ - 賠款入帳查詢 (/v1/logistic/compensation/{date})
14
+
15
+ ⚠️ Notify IP 白名單: 113.196.231.190(必加)
16
+
17
+ API 文件: 參見 references/pchomepay-logistics-api.md
18
+
19
+ 依賴:
20
+ pip install requests
21
+ """
22
+
23
+ import json
24
+ import time
25
+ from base64 import b64encode
26
+ from dataclasses import dataclass, field
27
+ from typing import Dict, List, Literal, Optional
28
+
29
+ import requests
30
+
31
+
32
+ @dataclass
33
+ class LogisticBatchRequest:
34
+ """取號列印交寄單"""
35
+ order_id: str # 商家訂單編號(與金流訂單關聯)
36
+ store_id: str # 取貨門市編號
37
+ return_store_id: str = '' # 退貨門市
38
+ name: str = '' # 收件人
39
+ phone: str = ''
40
+ address: str = ''
41
+ email: str = ''
42
+
43
+
44
+ @dataclass
45
+ class PChomePayResponse:
46
+ success: bool
47
+ code: str = ''
48
+ message: str = ''
49
+ data: Dict[str, any] = field(default_factory=dict)
50
+ raw: Dict[str, any] = field(default_factory=dict)
51
+
52
+
53
+ class PChomePayLogisticService:
54
+ """
55
+ PChomePay 物流服務.
56
+
57
+ 認證: 兩段式
58
+ 1. HTTP Basic Auth (APP_ID + SECRET) → /v1/token
59
+ 2. 後續 API 帶 `pcpay-token` header (8 小時有效)
60
+
61
+ Logistic types:
62
+ PL711 = 7-11
63
+ PLFMI = 全家 (FamilyMart)
64
+ PLHIL = 萊爾富 (Hi-Life)
65
+ PLOK = OK 超商
66
+ """
67
+
68
+ SANDBOX_BASE = 'https://sandbox-api.pchomepay.com.tw'
69
+ PROD_BASE = 'https://api.pchomepay.com.tw'
70
+
71
+ NOTIFY_IP = '113.196.231.190' # 白名單必加
72
+
73
+ def __init__(self, app_id: str, secret: str, is_test: bool = True):
74
+ self.app_id = app_id
75
+ self.secret = secret
76
+ self.base_url = self.SANDBOX_BASE if is_test else self.PROD_BASE
77
+ self._token = None
78
+ self._token_expire = 0
79
+
80
+ def _get_token(self) -> str:
81
+ """取得 / 刷新 pcpay-token (cache 8h)"""
82
+ if self._token and time.time() < self._token_expire - 60:
83
+ return self._token
84
+
85
+ # Basic Auth 取 token
86
+ creds = b64encode(f'{self.app_id}:{self.secret}'.encode()).decode()
87
+ try:
88
+ r = requests.post(
89
+ self.base_url + '/v1/token',
90
+ headers={'Authorization': f'Basic {creds}'},
91
+ timeout=30,
92
+ )
93
+ r.raise_for_status()
94
+ data = r.json()
95
+ self._token = data.get('token', '')
96
+ self._token_expire = time.time() + data.get('expires_in', 28800)
97
+ return self._token
98
+ except Exception as e:
99
+ raise ConnectionError(f'PChomePay token 取得失敗: {e}')
100
+
101
+ @property
102
+ def headers(self) -> Dict[str, str]:
103
+ return {
104
+ 'pcpay-token': self._get_token(),
105
+ 'Content-Type': 'application/json',
106
+ 'Accept': 'application/json',
107
+ }
108
+
109
+ # -- Operations -----------------------------------------------------------
110
+
111
+ def create_logistic(self, req: LogisticBatchRequest) -> PChomePayResponse:
112
+ """取號列印交寄單"""
113
+ body = {
114
+ 'order_id': req.order_id,
115
+ 'store_id': req.store_id,
116
+ 'return_store_id': req.return_store_id,
117
+ 'name': req.name,
118
+ 'phone': req.phone,
119
+ 'address': req.address,
120
+ 'email': req.email,
121
+ }
122
+ return self._submit('POST', '/v1/logistic/batch', body=body)
123
+
124
+ def query_history(self, order_id: str) -> PChomePayResponse:
125
+ """查詢物流歷程"""
126
+ return self._submit('GET', f'/v1/logistic/query/{order_id}/history')
127
+
128
+ def get_history_page_url(self, order_id: str) -> str:
129
+ """取得物流歷程 HTML 查詢頁 URL(不需 token, 直接給客戶)"""
130
+ return f'{self.base_url}/v1/logistic/query/{order_id}/history-page'
131
+
132
+ def query_yet_shipped(self) -> PChomePayResponse:
133
+ """查詢尚未出貨的訂單"""
134
+ return self._submit('GET', '/v1/logistic/yet')
135
+
136
+ def query_store_return(self, date_yyyymmdd: str) -> PChomePayResponse:
137
+ """查詢未取貨退倉訂單"""
138
+ return self._submit('GET', f'/v1/logistic/store_return/{date_yyyymmdd}')
139
+
140
+ def query_accounting(self, date_yyyymmdd: str) -> List[Dict[str, any]]:
141
+ """
142
+ 查詢物流手續費對帳資料(NDJSON 格式).
143
+
144
+ 每行為一個獨立 JSON 物件,須逐行 parse。
145
+ """
146
+ url = self.base_url + f'/v1/logistic/accounting/{date_yyyymmdd}'
147
+ try:
148
+ r = requests.get(url, headers=self.headers, timeout=30)
149
+ r.raise_for_status()
150
+ # NDJSON: 每行一個 JSON
151
+ records = []
152
+ for line in r.text.strip().split('\n'):
153
+ if line.strip():
154
+ try:
155
+ records.append(json.loads(line))
156
+ except json.JSONDecodeError:
157
+ pass
158
+ return records
159
+ except requests.exceptions.RequestException as e:
160
+ raise ConnectionError(f'PChomePay 對帳 API 連線失敗: {e}')
161
+
162
+ def query_compensation(self, date_yyyymm: str) -> PChomePayResponse:
163
+ """查詢貨物寄丟之賠款入帳資料"""
164
+ return self._submit('GET', f'/v1/logistic/compensation/{date_yyyymm}')
165
+
166
+ # -- HTTP submit ----------------------------------------------------------
167
+
168
+ def _submit(self, method: str, path: str, body: Optional[Dict[str, any]] = None) -> PChomePayResponse:
169
+ url = self.base_url + path
170
+ try:
171
+ if method == 'GET':
172
+ r = requests.get(url, headers=self.headers, timeout=30)
173
+ else:
174
+ r = requests.post(url, headers=self.headers, json=body, timeout=30)
175
+ except requests.exceptions.RequestException as e:
176
+ raise ConnectionError(f'PChomePay API 連線失敗: {e}')
177
+
178
+ try:
179
+ resp = r.json()
180
+ except ValueError:
181
+ return PChomePayResponse(
182
+ success=False,
183
+ code=str(r.status_code),
184
+ message=f'回應非 JSON: {r.text[:200]}',
185
+ )
186
+
187
+ is_success = 200 <= r.status_code < 300
188
+ return PChomePayResponse(
189
+ success=is_success,
190
+ code=str(resp.get('code', r.status_code)),
191
+ message=resp.get('message', ''),
192
+ data=resp.get('data', {}),
193
+ raw=resp,
194
+ )
195
+
196
+
197
+ # ============================================================================
198
+ # Examples
199
+ # ============================================================================
200
+
201
+ def example_create_logistic():
202
+ print('=== PChomePay 7-11 取貨付款 取號 ===\n')
203
+ svc = PChomePayLogisticService(app_id='YOUR_APP_ID', secret='YOUR_SECRET', is_test=True)
204
+ req = LogisticBatchRequest(
205
+ order_id=f'ORD{int(time.time())}',
206
+ store_id='123456', # 7-11 門市編號
207
+ return_store_id='123456',
208
+ name='王小明',
209
+ phone='0912345678',
210
+ email='test@example.com',
211
+ )
212
+ try:
213
+ resp = svc.create_logistic(req)
214
+ if resp.success:
215
+ print(f'[OK] 取號成功: {json.dumps(resp.data, ensure_ascii=False)}')
216
+ else:
217
+ print(f'[FAIL] {resp.code}: {resp.message}')
218
+ except Exception as e:
219
+ print(f'[ERROR] {e}')
220
+
221
+
222
+ def example_query_history():
223
+ print('\n=== PChomePay 物流歷程查詢 ===\n')
224
+ svc = PChomePayLogisticService('YOUR_APP_ID', 'YOUR_SECRET', is_test=True)
225
+ try:
226
+ resp = svc.query_history(order_id='ORD123456')
227
+ print(json.dumps(resp.raw, ensure_ascii=False, indent=2)[:500])
228
+ except Exception as e:
229
+ print(f'[ERROR] {e}')
230
+
231
+
232
+ def example_accounting():
233
+ print('\n=== PChomePay 物流手續費對帳(NDJSON)===\n')
234
+ svc = PChomePayLogisticService('YOUR_APP_ID', 'YOUR_SECRET', is_test=True)
235
+ try:
236
+ records = svc.query_accounting(date_yyyymmdd='20260101')
237
+ print(f'共 {len(records)} 筆對帳記錄')
238
+ for record in records[:3]:
239
+ print(f' - {record}')
240
+ except Exception as e:
241
+ print(f'[ERROR] {e}')
242
+
243
+
244
+ def example_history_page():
245
+ print('\n=== PChomePay HTML 物流歷程頁(給客戶端)===\n')
246
+ svc = PChomePayLogisticService('YOUR_APP_ID', 'YOUR_SECRET', is_test=True)
247
+ url = svc.get_history_page_url('ORD123456')
248
+ print(f'客戶可開啟: {url}')
249
+
250
+
251
+ if __name__ == '__main__':
252
+ example_create_logistic()
253
+ example_query_history()
254
+ example_accounting()
255
+ example_history_page()
@@ -0,0 +1,298 @@
1
+ #!/usr/bin/env python3
2
+ """
3
+ SmilePay 速買配物流 Python 範例
4
+
5
+ 依 taiwan-logistics-skill 規範撰寫。
6
+ SmilePay 物流以 Pay_zg + Pay_subzg 編碼涵蓋:
7
+ C2C_COD=51, C2C_PICKUP=52, B2C_COD=55, B2C_PICKUP=56
8
+ TCAT_COD=81, TCAT_PICKUP=82, RETCAT=83
9
+ Pay_subzg=7NET (7-11), FAMI (全家)
10
+
11
+ 支援:
12
+ - 7-11 / 全家 C2C+B2C 取貨付款 / 取貨不付款
13
+ - 黑貓宅急便 COD / PICKUP / 逆物流
14
+ - 電子地圖選店 (LogisticsEmap)
15
+ - 列印託運單
16
+
17
+ API 文件: 參見 references/smilepay-logistics-api.md
18
+
19
+ 依賴:
20
+ pip install requests
21
+ """
22
+
23
+ import time
24
+ from dataclasses import dataclass, field
25
+ from typing import Dict, List, Literal, Optional
26
+
27
+ import requests
28
+
29
+
30
+ @dataclass
31
+ class CvsLogisticOrder:
32
+ """7-11 / 全家 取貨訂單"""
33
+ data_id: str # 訂單編號 (唯一, 30 字內)
34
+ amount: int # 金額(COD 才有意義)
35
+ pur_name: str # 收件人姓名
36
+ pur_telno: str # 收件人電話
37
+ address: str = '' # 收件地址
38
+ email: str = ''
39
+ od_sob: str = '' # 商品名稱
40
+ roturl: str = '' # 通知 URL
41
+ cvs_provider: Literal['7NET', 'FAMI'] = '7NET' # 7-11 or FAMI
42
+ is_b2c: bool = False
43
+ is_cod: bool = True
44
+
45
+
46
+ @dataclass
47
+ class TcatLogisticOrder:
48
+ """黑貓宅急便訂單"""
49
+ data_id: str
50
+ amount: int # COD 才有意義
51
+ pur_name: str
52
+ pur_telno: str
53
+ address: str
54
+ od_sob: str = ''
55
+ roturl: str = ''
56
+ is_cod: bool = True
57
+ temperature: Literal['1', '2', '3'] = '1' # 1=常溫 2=冷藏 3=冷凍
58
+ is_reverse: bool = False # 逆物流 (Pay_zg=83)
59
+
60
+
61
+ @dataclass
62
+ class SmilePayLogisticResponse:
63
+ success: bool
64
+ status: str = ''
65
+ desc: str = ''
66
+ paymentno: str = '' # SmilePay 內部編號
67
+ smseid: str = '' # 物流商編號
68
+ storeid: str = '' # 門市編號
69
+ storename: str = ''
70
+ raw: Dict[str, any] = field(default_factory=dict)
71
+
72
+
73
+ class SmilePayLogisticService:
74
+ """
75
+ SmilePay 物流服務.
76
+
77
+ 認證: Dcvc + Verify_key(與金流端相同)
78
+ 端點:
79
+ - 7-11/全家 C2C 取號: /api/C2CPayment.asp
80
+ - 7-11/全家 B2C 取號: /api/B2CPayment.asp
81
+ - 黑貓取號: /api/ezcatGetTrackNum.asp
82
+ - 黑貓列印: /api/ezcatPrintDelivery.asp
83
+ - 超商列印 B2C: /api/B2C_MultiplePrint.asp
84
+ - 超商列印 C2B: /api/C2BPayment.asp
85
+ - 電子地圖選店: /api/LogisticsEmap.asp
86
+ - 修改: /api/SPPayment_Modify.asp
87
+
88
+ Pay_zg 矩陣(從 PHP plugin 反推):
89
+ 51 = C2C COD, 52 = C2C PICKUP
90
+ 55 = B2C COD, 56 = B2C PICKUP
91
+ 81 = TCAT COD, 82 = TCAT PICKUP, 83 = TCAT 逆物流
92
+ """
93
+
94
+ BASE_URL = 'https://ssl.smse.com.tw/api'
95
+ EMAP_URL = 'https://ssl.smse.com.tw/api/LogisticsEmap.asp'
96
+
97
+ # Pay_zg constants
98
+ C2C_COD_PAY_ZG = 51
99
+ C2C_PICKUP_PAY_ZG = 52
100
+ B2C_COD_PAY_ZG = 55
101
+ B2C_PICKUP_PAY_ZG = 56
102
+ TCAT_COD_PAY_ZG = 81
103
+ TCAT_PICKUP_PAY_ZG = 82
104
+ RETCAT_PAY_ZG = 83
105
+
106
+ def __init__(self, dcvc: str, verify_key: str, rvg2c: str = '1'):
107
+ self.dcvc = dcvc
108
+ self.verify_key = verify_key
109
+ self.rvg2c = rvg2c
110
+
111
+ # -- 7-11 / 全家 取號 -----------------------------------------------------
112
+
113
+ def create_cvs_order(self, order: CvsLogisticOrder) -> SmilePayLogisticResponse:
114
+ """建立 7-11 / 全家 物流訂單"""
115
+ # 決定 Pay_zg
116
+ if order.is_b2c:
117
+ pay_zg = self.B2C_COD_PAY_ZG if order.is_cod else self.B2C_PICKUP_PAY_ZG
118
+ endpoint = '/B2CPayment.asp'
119
+ else:
120
+ pay_zg = self.C2C_COD_PAY_ZG if order.is_cod else self.C2C_PICKUP_PAY_ZG
121
+ endpoint = '/C2CPayment.asp'
122
+
123
+ body = {
124
+ 'Dcvc': self.dcvc,
125
+ 'Rvg2c': self.rvg2c,
126
+ 'Verify_key': self.verify_key,
127
+ 'Pay_zg': str(pay_zg),
128
+ 'Pay_subzg': order.cvs_provider, # 7NET / FAMI
129
+ 'Data_id': order.data_id,
130
+ 'Amount': str(order.amount) if order.is_cod else '0',
131
+ 'Pur_name': order.pur_name,
132
+ 'Pur_telno': order.pur_telno,
133
+ 'Address': order.address,
134
+ 'Email': order.email,
135
+ 'od_sob': order.od_sob,
136
+ 'Roturl': order.roturl,
137
+ }
138
+ return self._submit(self.BASE_URL + endpoint, body)
139
+
140
+ # -- 黑貓宅急便 -----------------------------------------------------------
141
+
142
+ def create_tcat_order(self, order: TcatLogisticOrder) -> SmilePayLogisticResponse:
143
+ """建立黑貓宅急便訂單(COD / PICKUP / 逆物流)"""
144
+ if order.is_reverse:
145
+ pay_zg = self.RETCAT_PAY_ZG
146
+ elif order.is_cod:
147
+ pay_zg = self.TCAT_COD_PAY_ZG
148
+ else:
149
+ pay_zg = self.TCAT_PICKUP_PAY_ZG
150
+
151
+ body = {
152
+ 'Dcvc': self.dcvc,
153
+ 'Rvg2c': self.rvg2c,
154
+ 'Verify_key': self.verify_key,
155
+ 'Pay_zg': str(pay_zg),
156
+ 'Data_id': order.data_id,
157
+ 'Amount': str(order.amount) if order.is_cod else '0',
158
+ 'Pur_name': order.pur_name,
159
+ 'Pur_telno': order.pur_telno,
160
+ 'Address': order.address,
161
+ 'od_sob': order.od_sob,
162
+ 'Roturl': order.roturl,
163
+ 'Temperature': order.temperature, # 1常溫 2冷藏 3冷凍
164
+ }
165
+ return self._submit(self.BASE_URL + '/ezcatGetTrackNum.asp', body)
166
+
167
+ # -- 電子地圖選店 ---------------------------------------------------------
168
+
169
+ def get_emap_url(
170
+ self,
171
+ types_server: Literal['711C2C', 'FAMIC2C', '711B2C', 'FAMIB2C'],
172
+ return_url: str,
173
+ types_interface: Literal['MOBILE', 'WEB'] = 'WEB',
174
+ ) -> str:
175
+ """取得電子地圖選店 URL(讓客戶於 SmilePay 託管頁選擇取貨門市)"""
176
+ params = f'Dcvc={self.dcvc}&TypesServer={types_server}&TypesInterface={types_interface}&RtURL={return_url}'
177
+ return f'{self.EMAP_URL}?{params}'
178
+
179
+ # -- HTTP submit ----------------------------------------------------------
180
+
181
+ def _submit(self, url: str, body: Dict[str, any]) -> SmilePayLogisticResponse:
182
+ try:
183
+ r = requests.post(url, data=body, timeout=30)
184
+ r.raise_for_status()
185
+ except requests.exceptions.RequestException as e:
186
+ raise ConnectionError(f'SmilePay API 連線失敗: {e}')
187
+
188
+ # SmilePay 回應為 XML; 簡易 parse
189
+ import xml.etree.ElementTree as ET
190
+ try:
191
+ root = ET.fromstring(r.text)
192
+ status = root.findtext('Status', '')
193
+ desc = root.findtext('Desc', '')
194
+ paymentno = root.findtext('PaymentNo', '')
195
+ smseid = root.findtext('Smseid', '')
196
+ storeid = root.findtext('Storeid', '')
197
+ storename = root.findtext('Storename', '')
198
+ return SmilePayLogisticResponse(
199
+ success=(status == '1'),
200
+ status=status,
201
+ desc=desc,
202
+ paymentno=paymentno,
203
+ smseid=smseid,
204
+ storeid=storeid,
205
+ storename=storename,
206
+ raw={'text': r.text},
207
+ )
208
+ except ET.ParseError:
209
+ return SmilePayLogisticResponse(
210
+ success=False,
211
+ desc=f'XML parse 失敗: {r.text[:200]}',
212
+ )
213
+
214
+
215
+ # ============================================================================
216
+ # Examples
217
+ # ============================================================================
218
+
219
+ def example_711_cvs_cod():
220
+ print('=== SmilePay 7-11 C2C COD ===\n')
221
+ svc = SmilePayLogisticService(dcvc='107', verify_key='174A02F97A95F72CE301137B3F98D128')
222
+ order = CvsLogisticOrder(
223
+ data_id=f'ORD{int(time.time())}',
224
+ amount=1500,
225
+ pur_name='王小明',
226
+ pur_telno='0912345678',
227
+ email='test@example.com',
228
+ od_sob='測試商品',
229
+ roturl='https://your-shop.com/api/smilepay/notify',
230
+ cvs_provider='7NET',
231
+ is_b2c=False,
232
+ is_cod=True,
233
+ )
234
+ resp = svc.create_cvs_order(order)
235
+ if resp.success:
236
+ print(f'[OK] PaymentNo={resp.paymentno} 物流編號={resp.smseid}')
237
+ else:
238
+ print(f'[FAIL] {resp.status}: {resp.desc}')
239
+
240
+
241
+ def example_tcat_frozen_cod():
242
+ print('\n=== SmilePay 黑貓冷凍 COD ===\n')
243
+ svc = SmilePayLogisticService(dcvc='107', verify_key='174A02F97A95F72CE301137B3F98D128')
244
+ order = TcatLogisticOrder(
245
+ data_id=f'ORD{int(time.time())}',
246
+ amount=2000,
247
+ pur_name='王小明',
248
+ pur_telno='0912345678',
249
+ address='台北市信義區信義路五段7號',
250
+ od_sob='生鮮食品',
251
+ roturl='https://your-shop.com/api/smilepay/notify',
252
+ is_cod=True,
253
+ temperature='3', # 冷凍
254
+ )
255
+ resp = svc.create_tcat_order(order)
256
+ if resp.success:
257
+ print(f'[OK] PaymentNo={resp.paymentno} 黑貓編號={resp.smseid}')
258
+ else:
259
+ print(f'[FAIL] {resp.status}: {resp.desc}')
260
+
261
+
262
+ def example_tcat_reverse():
263
+ print('\n=== SmilePay 黑貓逆物流(退貨)===\n')
264
+ svc = SmilePayLogisticService(dcvc='107', verify_key='174A02F97A95F72CE301137B3F98D128')
265
+ order = TcatLogisticOrder(
266
+ data_id=f'RTN{int(time.time())}',
267
+ amount=0, # 逆物流不收 COD
268
+ pur_name='王小明',
269
+ pur_telno='0912345678',
270
+ address='台北市信義區信義路五段7號',
271
+ od_sob='退貨商品',
272
+ roturl='https://your-shop.com/api/smilepay/return-notify',
273
+ is_cod=False,
274
+ is_reverse=True, # Pay_zg=83
275
+ )
276
+ resp = svc.create_tcat_order(order)
277
+ if resp.success:
278
+ print(f'[OK] 逆物流取號成功 PaymentNo={resp.paymentno}')
279
+ else:
280
+ print(f'[FAIL] {resp.status}: {resp.desc}')
281
+
282
+
283
+ def example_emap():
284
+ print('\n=== SmilePay 電子地圖選店 ===\n')
285
+ svc = SmilePayLogisticService(dcvc='107', verify_key='174A02F97A95F72CE301137B3F98D128')
286
+ url = svc.get_emap_url(
287
+ types_server='711C2C',
288
+ return_url='https://your-shop.com/checkout/store-selected',
289
+ types_interface='WEB',
290
+ )
291
+ print(f'導轉至:\n{url}')
292
+
293
+
294
+ if __name__ == '__main__':
295
+ example_711_cvs_cod()
296
+ example_tcat_frozen_cod()
297
+ example_tcat_reverse()
298
+ example_emap()