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.
@@ -1,1332 +1,1332 @@
1
- # SmilePay Logistics API Reference
2
-
3
- 速買配 (SmilePay) 物流 API 完整參考文件。
4
-
5
- > **重要前置觀念**
6
- > SmilePay 物流 API 與金流 API **共用同一個帳號** (`Dcvc` + `Verify_key`)。
7
- > 你不會再看到「物流商代號」之類的東西 — SmilePay 是「金物流整合服務商」,
8
- > 它在背後再串接 7-11、全家、黑貓 (TCAT) 等實際物流業者。
9
- > 對開發者而言,所有物流產品都透過「**SmilePay 同一組 API + 不同的 `Pay_zg` / `Pay_subzg` 編碼**」
10
- > 來路由。掌握這個矩陣是整合 SmilePay 物流的祖傳秘方。
11
-
12
- ---
13
-
14
- ## 目錄
15
-
16
- 1. [基本說明](#基本說明)
17
- 2. [環境資訊](#環境資訊)
18
- 3. [認證方式](#認證方式)
19
- 4. [API 端點總覽](#api-端點總覽)
20
- 5. [物流類型分類](#物流類型分類)
21
- 6. [Pay_zg / Pay_subzg 編碼矩陣](#pay_zg--pay_subzg-編碼矩陣)
22
- 7. [取得物流編號](#取得物流編號)
23
- 8. [電子地圖選店](#電子地圖選店)
24
- 9. [列印託運單](#列印託運單)
25
- 10. [通知與貨況](#通知與貨況)
26
- 11. [退貨流程](#退貨流程)
27
- 12. [錯誤代碼](#錯誤代碼)
28
- 13. [物流類型對照表](#物流類型對照表)
29
- 14. [常見問題排解](#常見問題排解)
30
-
31
- ---
32
-
33
- ## 基本說明
34
-
35
- ### 服務範圍
36
-
37
- SmilePay 物流 API 支援 **三大物流體系,共 7 種物流產品**:
38
-
39
- | 物流體系 | 子類型 | 說明 |
40
- |---------|--------|------|
41
- | 7-11 超商取貨 | C2C 店到店 | 個人/小商家取貨;走 7-11 交貨便系統 |
42
- | 7-11 超商取貨 | B2C 大宗寄倉 | 商家大量寄倉;走大智通配送中心 |
43
- | 全家 超商取貨 | C2C 店到店 | 個人/小商家取貨;走全家店到店系統 |
44
- | 全家 超商取貨 | B2C 大宗寄倉 | 商家大量寄倉 (走全家專屬配送) |
45
- | 黑貓宅急便 | 常溫 | TCAT 室溫宅配 |
46
- | 黑貓宅急便 | 冷藏 | TCAT 0~7°C 冷藏宅配 |
47
- | 黑貓宅急便 | 冷凍 | TCAT -18°C 冷凍宅配 |
48
-
49
- ### 整合方式
50
-
51
- SmilePay 的物流 API 不是「一個物流業者一支 API」,而是**統一進入點 + 編碼分流**:
52
-
53
- 1. **取號階段**:所有物流產品都先打 `SPPayment.asp`,用 `Pay_zg` 編碼指定要走哪一條路線。
54
- 2. **後續操作**:依照取號回應拿到的 `SmilePayNO` (跟金流的同一個 ID),搭配不同子端點處理。
55
- 3. **回呼通知**:所有物流貨況變更都會 POST 到商家設定的 `Logistics_Roturl`,由 `Shipstatus` 數值決定狀態。
56
-
57
- ### 資料格式
58
-
59
- - 請求格式:`application/x-www-form-urlencoded` (POST)
60
- - 回應格式:**XML**(注意:不是 JSON)
61
- - 編碼:請求送出 UTF-8;某些貨況通知會以 BIG5 回傳 (建議偵測並轉碼)
62
-
63
- ---
64
-
65
- ## 環境資訊
66
-
67
- ### 測試環境
68
-
69
- SmilePay 提供官方測試帳號,可直接用來打通流程:
70
-
71
- ```
72
- Dcvc: 107
73
- Rvg2c: 1
74
- Verify_key: 174A02F97A95F72CE301137B3F98D128
75
- Mid: 1111
76
- ```
77
-
78
- ### 正式環境
79
-
80
- 正式帳號需向 SmilePay 業務窗口申請,會發放:
81
-
82
- | 欄位 | 說明 | 範例 |
83
- |------|------|------|
84
- | `Dcvc` | 商家代號 | `12345` |
85
- | `Rvg2c` | 簽章驗證代碼 | `1` |
86
- | `Verify_key` | 共享密鑰 (32 碼 HEX) | `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` |
87
- | `Mid` | 商店 ID | `12345` |
88
-
89
- > **注意**:`Dcvc` + `Verify_key` 與 SmilePay **金流 API 共用**。同一個 SmilePay 帳號,
90
- > 同時管理金流交易與物流追蹤碼。
91
-
92
- ### API 主機
93
-
94
- | 用途 | Hostname |
95
- |------|----------|
96
- | 全部物流 API | `ssl.smse.com.tw` |
97
- | 電子地圖 (mtmk) | `ssl.smse.com.tw/ezpos/` |
98
-
99
- 所有端點皆為 HTTPS,唯一例外:`ezcatGetTrackNum.asp` 與 `C2BPayment.asp`
100
- 在原始程式碼中是 `http://`,但 `https://` 也可正常運作(建議統一用 HTTPS)。
101
-
102
- ---
103
-
104
- ## 認證方式
105
-
106
- ### 共享密鑰機制
107
-
108
- SmilePay 物流 API **沒有計算 CheckMacValue 之類的簽章**,而是透過 `Dcvc` + `Verify_key`
109
- 作為「請求 + 帳號識別」雙重密碼。每個請求都必須夾帶這兩個欄位。
110
-
111
- | 參數 | 必填 | 說明 |
112
- |------|------|------|
113
- | `Dcvc` | ● | 商家代號 |
114
- | `Verify_key` | ● | 共享密鑰 |
115
- | `Rvg2c` | △ | 部分端點需要(如 `SPPayment.asp`、退貨便、TCAT 列印) |
116
-
117
- ### PHP 範例
118
-
119
- ```php
120
- <?php
121
- $post_data = [
122
- 'Dcvc' => '107',
123
- 'Verify_key' => '174A02F97A95F72CE301137B3F98D128',
124
- 'Rvg2c' => '1',
125
- // ... 其他物流參數
126
- ];
127
-
128
- $body = http_build_query($post_data);
129
- $response = wp_remote_post('https://ssl.smse.com.tw/api/SPPayment.asp', [
130
- 'body' => $body,
131
- ]);
132
- $xml = simplexml_load_string(wp_remote_retrieve_body($response));
133
- ```
134
-
135
- ### Python 範例
136
-
137
- ```python
138
- import requests
139
- import xml.etree.ElementTree as ET
140
-
141
- post_data = {
142
- 'Dcvc': '107',
143
- 'Verify_key': '174A02F97A95F72CE301137B3F98D128',
144
- 'Rvg2c': '1',
145
- # ... 其他物流參數
146
- }
147
-
148
- resp = requests.post(
149
- 'https://ssl.smse.com.tw/api/SPPayment.asp',
150
- data=post_data,
151
- timeout=30,
152
- )
153
- root = ET.fromstring(resp.text)
154
- status = root.findtext('Status')
155
- ```
156
-
157
- ### 安全建議
158
-
159
- - `Verify_key` 屬於高敏感憑證,**絕不能**寫死在前端 / 提交到 git。
160
- - 建議用 WordPress option / 環境變數 (`SMILEPAY_VERIFY_KEY`) 集中管理。
161
- - 物流 API 與金流 API 共用密鑰,撤銷會同時影響兩邊 — 異常時聯絡 SmilePay 換鑰。
162
-
163
- ---
164
-
165
- ## API 端點總覽
166
-
167
- 所有端點 base URL 為:`https://ssl.smse.com.tw/api/`
168
-
169
- ### 取號 / 修改
170
-
171
- | 端點 | 方法 | 用途 |
172
- |------|------|------|
173
- | `SPPayment.asp` | POST | **建立物流訂單(取得 SmilePayNO)**;CVS C2C / B2C / TCAT 全部都從這裡開始 |
174
- | `SPPayment_Modify.asp` | POST | 修改 CVS 訂單(換取貨人 / 換門市) |
175
-
176
- ### 超商 (CVS) 後續流程
177
-
178
- | 端點 | 方法 | 用途 |
179
- |------|------|------|
180
- | `C2CPayment.asp` | POST | C2C **取貨付款** 取交貨便號碼 |
181
- | `C2CPaymentU.asp` | POST | C2C **純取貨(不付款)** 取交貨便號碼 |
182
- | `B2CPayment.asp` | POST | B2C 大宗寄倉取交貨便號碼 |
183
- | `B2C_MultiplePrint.asp` | GET | B2C 列印託運單(多單列印) |
184
- | `C2BPayment.asp` | GET | C2B 退貨便列印 |
185
- | `LogisticsEmap.asp` | GET | 電子地圖選店(C2C / B2C 共用) |
186
-
187
- ### 黑貓 (TCAT) 後續流程
188
-
189
- | 端點 | 方法 | 用途 |
190
- |------|------|------|
191
- | `ezcatGetTrackNum.asp` | POST | 取得黑貓託運編號(TrackNum) |
192
- | `ezcatPrintDelivery.asp` | GET | 列印黑貓託運單 |
193
-
194
- ### 電子地圖 / mtmk
195
-
196
- | 端點 | 方法 | 用途 |
197
- |------|------|------|
198
- | `https://ssl.smse.com.tw/ezpos/mtmk_utf.asp` | GET | C2B 退貨便電子地圖(讓消費者選退貨門市) |
199
-
200
- ---
201
-
202
- ## 物流類型分類
203
-
204
- SmilePay 物流可由「**寄送方式**」與「**金流方式**」兩個維度交叉。
205
-
206
- ### 寄送方式
207
-
208
- | 寄送方式 | 說明 |
209
- |----------|------|
210
- | 7-11 C2C 店到店 | `typesserver = 711C2C` |
211
- | 7-11 B2C 大宗寄倉 | `typesserver = 711B2C` |
212
- | 全家 C2C 店到店 | `typesserver = FAMIC2C` |
213
- | 全家 B2C 大宗寄倉 | `typesserver = FAMIB2C`(部分商家可選用) |
214
- | 黑貓 常溫 | TCAT (溫層 `0001`) |
215
- | 黑貓 冷藏 | TCAT (溫層 `0002`) |
216
- | 黑貓 冷凍 | TCAT (溫層 `0003`) |
217
-
218
- ### 金流方式
219
-
220
- | 金流方式 | 說明 | 影響 |
221
- |----------|------|------|
222
- | 取貨付款(COD) | 消費者取貨時付現給超商 / 黑貓 | 走 `_COD_PAY_ZG` 編碼 |
223
- | 純取貨(PICKUP) | 消費者已預先付款,只需取貨 | 走 `_PICKUP_PAY_ZG` 編碼 |
224
-
225
- ### WooCommerce 程式中的物流方法 ID
226
-
227
- ```
228
- WC_SmilePay_CVS_711 // 7-11 (C2C/B2C 由設定切換)
229
- WC_SmilePay_CVS_FAMI // 全家 (C2C only)
230
- WC_SmilePay_TCAT_NORMAL // 黑貓常溫
231
- WC_SmilePay_TCAT_REFRIGE // 黑貓冷藏
232
- WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
233
- ```
234
-
235
- ---
236
-
237
- ## Pay_zg / Pay_subzg 編碼矩陣
238
-
239
- > **這是 SmilePay 物流的祖傳秘方** — 所有物流產品都從同一支 `SPPayment.asp`
240
- > 進入,靠 `Pay_zg`(主要分類)+ `Pay_subzg`(副分類)來路由到實際物流業者。
241
-
242
- ### Pay_zg(物流主分類)
243
-
244
- | 常數名稱 | 值 | 用途 |
245
- |----------|----|------|
246
- | `C2C_COD_PAY_ZG` | `51` | 超商 C2C **取貨付款** |
247
- | `C2C_PICKUP_PAY_ZG` | `52` | 超商 C2C **純取貨(不付款)** |
248
- | `B2C_COD_PAY_ZG` | `55` | 超商 B2C **取貨付款** |
249
- | `B2C_PICKUP_PAY_ZG` | `56` | 超商 B2C **純取貨** |
250
- | `TCAT_COD_PAY_ZG` | `81` | 黑貓宅配 **取貨付款** |
251
- | `TCAT_PICKUP_PAY_ZG` | `82` | 黑貓宅配 **純取貨** |
252
- | `RETCAT_PAY_ZG` | `83` | 黑貓 **逆物流(退貨)** |
253
- | `c2b_payzg` | (商家自訂) | C2B 退貨便(由商家後台設定,常見值依超商而異) |
254
-
255
- ### Pay_subzg(物流副分類)
256
-
257
- | 常數名稱 | 值 | 用途 |
258
- |----------|----|------|
259
- | `_711_PAY_SUBZG` | `7NET` | 走 7-11 / 大智通系統(C2C 與 B2C 都用這個) |
260
- | `FAMI_PAY_SUBZG` | `FAMI` | 走全家系統 |
261
- | TCAT 固定值 | `TCAT` | 黑貓宅配(含逆物流) |
262
-
263
- ### 完整編碼對照表
264
-
265
- | 寄送方式 | 金流方式 | `Pay_zg` | `Pay_subzg` |
266
- |---------|---------|----------|-------------|
267
- | 7-11 C2C 店到店 | 取貨付款 | `51` | `7NET` |
268
- | 7-11 C2C 店到店 | 純取貨 | `52` | `7NET` |
269
- | 7-11 B2C 大宗寄倉 | 取貨付款 | `55` | `7NET` |
270
- | 7-11 B2C 大宗寄倉 | 純取貨 | `56` | `7NET` |
271
- | 全家 C2C 店到店 | 取貨付款 | `51` | `FAMI` |
272
- | 全家 C2C 店到店 | 純取貨 | `52` | `FAMI` |
273
- | 全家 B2C 大宗寄倉 | 取貨付款 | `55` | `FAMI` |
274
- | 全家 B2C 大宗寄倉 | 純取貨 | `56` | `FAMI` |
275
- | 黑貓常溫 / 冷藏 / 冷凍 | 取貨付款 | `81` | `TCAT` |
276
- | 黑貓常溫 / 冷藏 / 冷凍 | 純取貨 | `82` | `TCAT` |
277
- | 黑貓逆物流(退貨) | — | `83` | `TCAT` |
278
-
279
- **注意**:黑貓的「常溫 / 冷藏 / 冷凍」差異**不是**靠 `Pay_zg` 區分,
280
- 而是走第二支 API `ezcatGetTrackNum.asp` 時的 `temperature` 參數
281
- (`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍)。
282
-
283
- ### 路由邏輯(PHP 範例)
284
-
285
- ```php
286
- // 根據使用者選擇的物流 + 金流,決定 Pay_zg / Pay_subzg
287
- function determine_pay_codes(string $typesserver, string $payment_method): array {
288
- $is_cod = $payment_method === 'cod';
289
-
290
- // 7-11 與全家走同一組 Pay_zg,差別在 Pay_subzg
291
- switch ($typesserver) {
292
- case '711C2C':
293
- return [
294
- 'pay_zg' => $is_cod ? 51 : 52, // C2C_COD or C2C_PICKUP
295
- 'pay_subzg' => '7NET',
296
- ];
297
- case '711B2C':
298
- return [
299
- 'pay_zg' => $is_cod ? 55 : 56, // B2C_COD or B2C_PICKUP
300
- 'pay_subzg' => '7NET',
301
- ];
302
- case 'FAMIC2C':
303
- return [
304
- 'pay_zg' => $is_cod ? 51 : 52,
305
- 'pay_subzg' => 'FAMI',
306
- ];
307
- case 'FAMIB2C':
308
- return [
309
- 'pay_zg' => $is_cod ? 55 : 56,
310
- 'pay_subzg' => 'FAMI',
311
- ];
312
- }
313
- throw new InvalidArgumentException("Unknown typesserver: {$typesserver}");
314
- }
315
- ```
316
-
317
- ---
318
-
319
- ## 取得物流編號
320
-
321
- 物流取號分為兩個階段:
322
-
323
- 1. **第一階段(共通)**:呼叫 `SPPayment.asp` 取得 `SmilePayNO`
324
- 2. **第二階段(依物流產品)**:用 `SmilePayNO` 換取實際的「交貨便號碼」或「TCAT 託運單號」
325
-
326
- ### 第一階段:取得 SmilePayNO
327
-
328
- #### 端點
329
-
330
- ```
331
- POST https://ssl.smse.com.tw/api/SPPayment.asp
332
- ```
333
-
334
- #### 共通參數
335
-
336
- | 參數 | 類型 | 必填 | 說明 |
337
- |------|------|------|------|
338
- | `Dcvc` | String | ● | 商家代號 |
339
- | `Verify_key` | String(32) | ● | 共享密鑰 |
340
- | `Rvg2c` | String | ● | 簽章驗證代碼 |
341
- | `Pay_zg` | Integer | ● | 物流主分類(見上表) |
342
- | `Pay_subzg` | String | ● | 物流副分類(`7NET` / `FAMI` / `TCAT`) |
343
- | `Pur_name` | String | ● | 取貨人姓名 |
344
- | `Tel_number` | String | ● | 取貨人電話 |
345
- | `Mobile_number` | String | △ | 取貨人手機(建議與 Tel_number 同值) |
346
- | `Email` | String | △ | 取貨人 Email |
347
- | `Address` | String | △ | 取貨人地址(CVS 可省略,TCAT 必填) |
348
- | `Data_id` | String | ● | 商家自訂訂單編號(必須唯一) |
349
- | `od_sob` | String(35) / (45) | ● | 商品名稱(CVS 35 字 / TCAT 45 字內) |
350
- | `Amount` | Integer | ● | 訂單總金額(取整) |
351
- | `Logistics_store` | String | △ | CVS 必填,格式:`{store_id}/{store_name}/{store_address}` |
352
- | `Roturl` | String(URL) | △ | 商家通用回傳網址 |
353
- | `Logistics_Roturl` | String(URL) | ● | **物流貨況通知網址** |
354
- | `Roturl_status` | String | △ | 回傳狀態識別碼(如 `woook1.1.23`) |
355
- | `Remark` | String | △ | 備註(取自買家結帳備註) |
356
-
357
- #### 回應(XML)
358
-
359
- 成功:
360
-
361
- ```xml
362
- <?xml version="1.0" encoding="UTF-8"?>
363
- <SmilePay>
364
- <Status>1</Status>
365
- <Desc>交易成功</Desc>
366
- <SmilePayNO>1234567890</SmilePayNO>
367
- <Data_id>WC-1024</Data_id>
368
- <Amount>1500</Amount>
369
- </SmilePay>
370
- ```
371
-
372
- 失敗:
373
-
374
- ```xml
375
- <?xml version="1.0" encoding="UTF-8"?>
376
- <SmilePay>
377
- <Status>-2</Status>
378
- <Desc>驗證失敗</Desc>
379
- </SmilePay>
380
- ```
381
-
382
- 判斷成功的鐵則:
383
- - HTTP body 含 `<SmilePay>`
384
- - `<Status>` 等於 `1`
385
-
386
- ### 第二階段:取得實際物流編號
387
-
388
- 依物流產品分為三條路徑:
389
-
390
- #### A. 7-11 / 全家 C2C — 取交貨便號碼
391
-
392
- ```
393
- POST https://ssl.smse.com.tw/api/C2CPayment.asp # 取貨付款 (COD)
394
- POST https://ssl.smse.com.tw/api/C2CPaymentU.asp # 純取貨 (PICKUP)
395
- ```
396
-
397
- | 參數 | 必填 | 說明 |
398
- |------|------|------|
399
- | `Dcvc` | ● | 商家代號 |
400
- | `Verify_key` | ● | 共享密鑰 |
401
- | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
402
- | `Pay_subzg` | ● | `7NET` 或 `FAMI` |
403
- | `types` | ● | `Xml` (取得 XML 回應) 或 `Web` (取得 HTML 列印頁網址) |
404
-
405
- 回應(`types=Xml`):
406
-
407
- ```xml
408
- <SmilePay>
409
- <Status>1</Status>
410
- <paymentno>AB12345</paymentno>
411
- <validationno>1234</validationno>
412
- <storeid>131386</storeid>
413
- <storename>雙子星門市</storename>
414
- </SmilePay>
415
- ```
416
-
417
- 完整交貨便號碼 = `paymentno` + `validationno`(例:`AB123451234`)
418
-
419
- #### B. 7-11 B2C — 取大宗寄倉編號
420
-
421
- ```
422
- POST https://ssl.smse.com.tw/api/B2CPayment.asp
423
- ```
424
-
425
- | 參數 | 必填 | 說明 |
426
- |------|------|------|
427
- | `Dcvc` | ● | 商家代號 |
428
- | `Verify_key` | ● | 共享密鑰 |
429
- | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
430
-
431
- 回應:
432
-
433
- ```xml
434
- <SmilePay>
435
- <Status>1</Status>
436
- <EshopOrderNo>0987654321</EshopOrderNo>
437
- <Storeid>131386</Storeid>
438
- <StoreName>雙子星門市</StoreName>
439
- </SmilePay>
440
- ```
441
-
442
- 7-11 B2C 完整查詢碼:`766` + `EshopOrderNo`
443
-
444
- #### C. 黑貓 — 取託運單號
445
-
446
- ```
447
- POST https://ssl.smse.com.tw/api/ezcatGetTrackNum.asp
448
- ```
449
-
450
- | 參數 | 必填 | 說明 |
451
- |------|------|------|
452
- | `Dcvc` | ● | 商家代號 |
453
- | `Verify_key` | ● | 共享密鑰 |
454
- | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
455
- | `package_size` | ● | 包裹尺寸(60/90/120/150 cm) |
456
- | `temperature` | ● | 溫層:`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍 |
457
- | `delivery_date` | △ | 預定送達日 (`YYYY/MM/DD`) |
458
- | `delivery_timezone` | △ | 預定送達時段(`1`/`2`/`4`) |
459
- | `is_protect` | △ | 易碎品保護(`1` 啟用;`0` 不送出此參數) |
460
- | `shipment_type` | △ | 出貨類型 |
461
- | `receiver_address` | △ | 收件地址(逆物流時用) |
462
-
463
- 回應:
464
-
465
- ```xml
466
- <SmilePay>
467
- <Status>1</Status>
468
- <TrackNum>900123456789</TrackNum>
469
- <Smseid>1234567890</Smseid>
470
- <Pur_name>王小明</Pur_name>
471
- <Tel_number>0912345678</Tel_number>
472
- </SmilePay>
473
- ```
474
-
475
- #### PHP 完整範例(C2C 取貨付款)
476
-
477
- ```php
478
- <?php
479
- // === 第一階段:取得 SmilePayNO ===
480
- $post_data = [
481
- 'Dcvc' => '107',
482
- 'Rvg2c' => '1',
483
- 'Verify_key' => '174A02F97A95F72CE301137B3F98D128',
484
- 'Pay_zg' => 51, // C2C COD
485
- 'Pay_subzg' => '7NET', // 7-11
486
- 'Pur_name' => '王小明',
487
- 'Tel_number' => '0912345678',
488
- 'Mobile_number' => '0912345678',
489
- 'Email' => 'buyer@example.com',
490
- 'Data_id' => 'WC-' . time(),
491
- 'od_sob' => '商品A*1|商品B*2',
492
- 'Amount' => 1500,
493
- 'Logistics_store' => '131386/雙子星門市/台北市信義區市府路1號',
494
- 'Roturl' => 'https://your-site.com/wc-api/roturl',
495
- 'Logistics_Roturl' => 'https://your-site.com/wc-api/smilepay_cvs_logistic_status',
496
- 'Roturl_status' => 'woook1.1.23',
497
- 'Remark' => '請小心包裝',
498
- ];
499
-
500
- $response = wp_remote_post(
501
- 'https://ssl.smse.com.tw/api/SPPayment.asp',
502
- ['body' => http_build_query($post_data)]
503
- );
504
- $xml = simplexml_load_string(wp_remote_retrieve_body($response));
505
-
506
- if ((string)$xml->Status !== '1') {
507
- throw new Exception("取號失敗:{$xml->Desc}");
508
- }
509
- $smilepay_no = (string)$xml->SmilePayNO;
510
-
511
- // === 第二階段:取得交貨便號碼 ===
512
- $post_data2 = [
513
- 'Dcvc' => '107',
514
- 'Verify_key' => '174A02F97A95F72CE301137B3F98D128',
515
- 'smseid' => $smilepay_no,
516
- 'Pay_subzg' => '7NET',
517
- 'types' => 'Xml',
518
- ];
519
- $response2 = wp_remote_post(
520
- 'https://ssl.smse.com.tw/api/C2CPayment.asp', // 取貨付款用 C2CPayment.asp
521
- ['body' => $post_data2]
522
- );
523
- $xml2 = simplexml_load_string(wp_remote_retrieve_body($response2));
524
-
525
- $payment_no = (string)$xml2->paymentno . (string)$xml2->validationno;
526
- echo "交貨便號碼:{$payment_no}";
527
- ```
528
-
529
- #### Python 範例(黑貓常溫宅配)
530
-
531
- ```python
532
- import requests
533
- import xml.etree.ElementTree as ET
534
-
535
- # === 第一階段 ===
536
- post_data = {
537
- 'Dcvc': '107',
538
- 'Rvg2c': '1',
539
- 'Verify_key': '174A02F97A95F72CE301137B3F98D128',
540
- 'Pay_zg': 81, # TCAT COD
541
- 'Pay_subzg': 'TCAT',
542
- 'Pur_name': '王小明',
543
- 'Tel_number': '0912345678',
544
- 'Mobile_number': '0912345678',
545
- 'Email': 'buyer@example.com',
546
- 'Address': '台北市信義區市府路1號',
547
- 'Data_id': f'WC-{int(time.time())}',
548
- 'od_sob': '商品A*1|商品B*2',
549
- 'Amount': 1500,
550
- 'Logistics_Roturl': 'https://your-site.com/wc-api/smilepay_tcat_logistic_status',
551
- 'Roturl_status': 'woook1.1.23',
552
- }
553
-
554
- resp = requests.post('https://ssl.smse.com.tw/api/SPPayment.asp', data=post_data)
555
- xml = ET.fromstring(resp.text)
556
- assert xml.findtext('Status') == '1'
557
- smilepay_no = xml.findtext('SmilePayNO')
558
-
559
- # === 第二階段:取得 TCAT 託運單號 ===
560
- post_data2 = {
561
- 'Dcvc': '107',
562
- 'Verify_key': '174A02F97A95F72CE301137B3F98D128',
563
- 'smseid': smilepay_no,
564
- 'package_size': '60',
565
- 'temperature': '0001', # 0001=常溫
566
- 'delivery_date': '2026/05/15',
567
- 'delivery_timezone': '3', # 3=不限時
568
- }
569
- resp2 = requests.post('https://ssl.smse.com.tw/api/ezcatGetTrackNum.asp', data=post_data2)
570
- xml2 = ET.fromstring(resp2.text)
571
- track_num = xml2.findtext('TrackNum')
572
- print(f'託運單號:{track_num}')
573
- ```
574
-
575
- ---
576
-
577
- ## 電子地圖選店
578
-
579
- 讓消費者在結帳階段選擇取貨門市。
580
-
581
- ### 端點
582
-
583
- ```
584
- GET https://ssl.smse.com.tw/api/LogisticsEmap.asp
585
- ```
586
-
587
- ### 參數
588
-
589
- | 參數 | 必填 | 說明 |
590
- |------|------|------|
591
- | `method` | ● | 固定 `GET` |
592
- | `TypesServer` | ● | 物流伺服器類型 |
593
- | `TypesInterface` | ● | `MOBILE` 或 `WEB` |
594
- | `tempvar` | ● | 暫存參數(商家自訂的識別碼,會原樣回傳) |
595
- | `url` | ● | 選店完成後 SmilePay 重導回去的網址 |
596
-
597
- ### TypesServer 對照
598
-
599
- | 值 | 說明 |
600
- |------|------|
601
- | `711C2C` | 7-11 C2C 店到店 |
602
- | `711B2C` | 7-11 B2C 大宗寄倉 |
603
- | `FAMIC2C` | 全家 C2C 店到店 |
604
- | `FAMIB2C` | 全家 B2C 大宗寄倉 |
605
-
606
- ### TypesInterface 對照
607
-
608
- | 值 | 用途 |
609
- |----|------|
610
- | `MOBILE` | 手機介面 |
611
- | `WEB` | 桌機介面 |
612
-
613
- ### 範例網址
614
-
615
- ```
616
- https://ssl.smse.com.tw/api/LogisticsEmap.asp
617
- ?method=GET
618
- &TypesServer=711C2C
619
- &TypesInterface=MOBILE
620
- &tempvar=order_123
621
- &url=https%3A%2F%2Fyour-site.com%2Fwc-api%2Fsmilepay_save_emap
622
- ```
623
-
624
- ### 選店回呼參數
625
-
626
- 消費者選店完成後,SmilePay 會 POST/GET 以下欄位到 `url`:
627
-
628
- | 參數 | 說明 |
629
- |------|------|
630
- | `tempvar` | 你送過去的暫存識別碼 |
631
- | `Storeid` | 門市代號 |
632
- | `Storename` | 門市名稱 |
633
- | `StoreAddress` | 門市地址 |
634
- | `TypesServer` | 物流類型(同送出) |
635
-
636
- ### PHP 範例(產生選店連結)
637
-
638
- ```php
639
- <?php
640
- function build_emap_url(string $typesserver, string $interface, string $tempvar, string $callback_url): string {
641
- $base = 'https://ssl.smse.com.tw/api/LogisticsEmap.asp';
642
- return sprintf(
643
- '%s?method=GET&TypesServer=%s&TypesInterface=%s&tempvar=%s&url=%s',
644
- $base,
645
- $typesserver,
646
- $interface, // MOBILE / WEB
647
- urlencode($tempvar),
648
- urlencode($callback_url),
649
- );
650
- }
651
-
652
- // 例:開啟手機版的 7-11 C2C 電子地圖
653
- $emap = build_emap_url(
654
- '711C2C',
655
- wp_is_mobile() ? 'MOBILE' : 'WEB',
656
- 'order_' . get_current_user_id(),
657
- home_url('/wc-api/smilepay_save_emap')
658
- );
659
- header("Location: {$emap}");
660
- exit;
661
- ```
662
-
663
- ---
664
-
665
- ## 列印託運單
666
-
667
- ### 7-11 / 全家 C2C 列印
668
-
669
- C2C 不需要呼叫額外端點,**直接組成 GET URL** 開啟瀏覽器即可:
670
-
671
- ```php
672
- $print_url = sprintf(
673
- 'https://ssl.smse.com.tw/api/%s?%s',
674
- $is_cod ? 'C2CPayment.asp' : 'C2CPaymentU.asp',
675
- http_build_query([
676
- 'Dcvc' => $dcvc,
677
- 'Verify_key' => $verify_key,
678
- 'smseid' => $smilepay_no,
679
- 'Pay_subzg' => $pay_subzg,
680
- 'types' => 'Web', // ← 這個參數讓回應變 HTML 列印頁
681
- ])
682
- );
683
- // 開新分頁
684
- echo "<a href='{$print_url}' target='_blank'>列印託運單</a>";
685
- ```
686
-
687
- ### 7-11 B2C 列印(多單合併)
688
-
689
- ```
690
- GET https://ssl.smse.com.tw/api/B2C_MultiplePrint.asp
691
- ```
692
-
693
- | 參數 | 必填 | 說明 |
694
- |------|------|------|
695
- | `Dcvc` | ● | 商家代號 |
696
- | `Rvg2c` | ● | 固定 `1` |
697
- | `Verify_key` | ● | 共享密鑰 |
698
- | `PaperModel` | ● | 紙張規格(`1` = 標籤紙) |
699
- | `smseid` | ● | SmilePayNO;多筆用 `,` 串接 |
700
-
701
- ```php
702
- $url = 'https://ssl.smse.com.tw/api/B2C_MultiplePrint.asp?' . http_build_query([
703
- 'Rvg2c' => '1',
704
- 'Dcvc' => $dcvc,
705
- 'Verify_key' => $verify_key,
706
- 'PaperModel' => '1',
707
- 'smseid' => $smilepay_no, // 或多筆 '111,222,333'
708
- ]);
709
- ```
710
-
711
- ### 黑貓列印託運單
712
-
713
- ```
714
- GET https://ssl.smse.com.tw/api/ezcatPrintDelivery.asp
715
- ```
716
-
717
- | 參數 | 必填 | 說明 |
718
- |------|------|------|
719
- | `Dcvc` | ● | 商家代號 |
720
- | `Rvg2c` | ● | 簽章驗證代碼 |
721
- | `Verify_key` | ● | 共享密鑰 |
722
- | `Smseid` | ● | SmilePayNO(注意:是大寫 S) |
723
- | `print_format` | ● | 列印格式(依後台設定,常見 `1`/`2`) |
724
-
725
- ```php
726
- $url = 'https://ssl.smse.com.tw/api/ezcatPrintDelivery.asp?' . http_build_query([
727
- 'Dcvc' => $dcvc,
728
- 'Rvg2c' => $rvg2c,
729
- 'Verify_key' => $verify_key,
730
- 'Smseid' => $smilepay_no,
731
- 'print_format' => '1',
732
- ]);
733
- ```
734
-
735
- ### C2B 退貨便列印
736
-
737
- ```
738
- GET https://ssl.smse.com.tw/api/C2BPayment.asp
739
- ```
740
-
741
- | 參數 | 必填 | 說明 |
742
- |------|------|------|
743
- | `Dcvc` | ● | 商家代號 |
744
- | `Verify_key` | ● | 共享密鑰 |
745
- | `smseid` | ● | C2B 取號回呼拿到的 Smseid |
746
- | `types` | ● | `Web`(取得 HTML 列印頁) |
747
-
748
- ---
749
-
750
- ## 通知與貨況
751
-
752
- 物流貨況變更時,SmilePay 會 POST 到取號時提供的 `Logistics_Roturl`。
753
- **CVS 與 TCAT 走不同的 webhook 處理邏輯**。
754
-
755
- ### CVS 貨況通知
756
-
757
- #### 收到的欄位
758
-
759
- | 參數 | 說明 |
760
- |------|------|
761
- | `Data_id` | 商家訂單編號(取號時送的 Data_id) |
762
- | `Smseid` | SmilePay 物流追蹤碼 |
763
- | `Shipstatus` | 貨況狀態碼(**整數**) |
764
- | `Payment_no` | C2C:交貨便號碼 |
765
- | `EshopOrderNo` | B2C:大宗寄倉編號 |
766
- | `Storeid` | 門市代號 |
767
- | `Storename` | 門市名稱 (可能 BIG5 編碼) |
768
-
769
- #### Shipstatus 對照(C2C 7-11 / 全家)
770
-
771
- | 代碼 | 中文意思 | 建議訂單狀態 |
772
- |------|---------|-------------|
773
- | `1` | 已出貨 | shipped |
774
- | `2` | 已到達門市 | cvs-delivered |
775
- | `3` | 消費者已取貨 | cvs-pickedup / completed |
776
- | `4` | 消費者退貨 | cancelled |
777
- | `5` | 已到退貨門市 | (不變更 WC 狀態) |
778
- | `6` | 退貨已取貨 | (不變更 WC 狀態) |
779
- | `7` | 退貨已至物流中心 | (不變更 WC 狀態) |
780
-
781
- #### Shipstatus 對照(B2C — 7-11 大智通)
782
-
783
- | 代碼 | 中文意思 | 建議訂單狀態 |
784
- |------|---------|-------------|
785
- | `1` | 大智通配送中 | shipped |
786
- | `2` | 已到達門市 | cvs-delivered |
787
- | `3` | 消費者已取貨 | completed |
788
- | `4` | 消費者退貨 | cancelled |
789
- | `5` | 已到退貨門市 | — |
790
- | `6` | 退貨已取貨 | — |
791
- | `7` | 退貨已至物流中心 | — |
792
- | `11` | 已出貨(廠商出貨給大智通) | shipped |
793
-
794
- #### 編碼處理(重要!)
795
-
796
- CVS 通知中的 `Storename` 等中文欄位**可能以 BIG5 編碼回傳**。處理時必須偵測並轉碼:
797
-
798
- ```php
799
- foreach ($_REQUEST as $key => $val) {
800
- if (mb_detect_encoding(urldecode($val), 'BIG5', true)) {
801
- $_REQUEST[$key] = mb_convert_encoding(urldecode($val), 'UTF-8', 'BIG5');
802
- }
803
- }
804
- ```
805
-
806
- #### 回應格式
807
-
808
- 不論成功失敗,必須以 HTTP 200 回應一段含 `<Roturlstatus>` 的 XML 片段:
809
-
810
- ```php
811
- // 成功處理
812
- echo '<Roturlstatus>woook1.1.23</Roturlstatus>';
813
- // 找不到訂單
814
- echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應的Order物件</Roturlstatus>";
815
- ```
816
-
817
- `Roturl_status` 的字串需與取號時送出的 `Roturl_status` 相同(範例為 `woook1.1.23`)。
818
-
819
- ### TCAT 貨況通知
820
-
821
- #### 收到的欄位
822
-
823
- | 參數 | 說明 |
824
- |------|------|
825
- | `Data_id` | 商家訂單編號 |
826
- | `Smseid` | SmilePay 物流追蹤碼 |
827
- | `Shipstatus` | 主貨況狀態碼 |
828
- | `DetailStatus` | 配送異常子狀態碼(如有,優先處理) |
829
- | `Payment_no` | TCAT 託運單號 |
830
-
831
- #### Shipstatus 對照(黑貓)
832
-
833
- | 代碼 | 中文意思 | 建議訂單狀態 |
834
- |------|---------|-------------|
835
- | `1` | 配送中 | shipped |
836
- | `3` | 已配達 | ezcat-delivered |
837
- | `5` | 退貨中 | cancelled |
838
- | `7` | 退完 | cancelled |
839
- | `8` | 集貨失敗 | cancelled |
840
-
841
- > 黑貓只回 `1/3/5/7/8` 這幾個狀態,沒有 `2/4/6`。
842
-
843
- #### DetailStatus 異常代碼(節錄)
844
-
845
- | 代碼 | 異常類型 |
846
- |------|---------|
847
- | `00002` | 不在家 |
848
- | `00007` | 損壞 |
849
- | `00008` | 公司行號休息 |
850
- | `00009` | 地址不明 |
851
- | `00010` | 搬家 |
852
- | `00011` | 拒收 |
853
- | `00014` | 遺失 |
854
- | `00015` | 暫置營業所 |
855
- | `00016` | BASE 列管 |
856
- | `00021` | 超大 |
857
- | `00022` | 超重 |
858
- | `00023` | 地址錯誤 |
859
- | `00025` | 航班延誤 |
860
- | `00219` | 暫置營業所 |
861
- | `001` | 自行寄回 |
862
- | `002` | 不退了 |
863
- | `003` | 尚未收到商品 |
864
- | `004` | 另約取件時間 |
865
- | `005` | 電話錯誤 |
866
- | `006` | 電話空號 |
867
- | `007` | 電話未接 |
868
- | `008` | 電話關機 |
869
- | `009` | 超大 |
870
- | `010` | 人不在 |
871
- | `011` | 已收走 |
872
- | `014` | 商品送達時已拒收退回 |
873
- | `015` | 地址有誤 |
874
- | `017` | PCHOME 通知取消 |
875
- | `024` | 其他 |
876
- | `025` | 已集貨 |
877
- | `999` | 訂單復原 |
878
- | `P26` | 另約時間 |
879
- | `P27` | 電聯不上 |
880
- | `P28` | 資料有誤 |
881
- | `P29` | 無件可退 |
882
- | `P30` | 超大超重 |
883
- | `P31` | 已回收 |
884
- | `P32` | 別家收走 |
885
- | `P33` | 商品未到 |
886
-
887
- > **處理順序**:通知進來時先檢查 `DetailStatus`,**有值就優先記錄異常**,
888
- > 然後直接回應 `<Roturlstatus>接收到配送異常XXX</Roturlstatus>` 結束 (不再處理 `Shipstatus`)。
889
-
890
- #### 回應格式
891
-
892
- ```php
893
- // 一般成功
894
- echo '<Roturlstatus>woook1.1.23</Roturlstatus>';
895
- // 異常回報
896
- echo "<Roturlstatus>接收到配送異常{$detailstatus}</Roturlstatus>";
897
- ```
898
-
899
- ### 完整 PHP 通知處理範例
900
-
901
- ```php
902
- <?php
903
- function smilepay_cvs_logistic_status_handler() {
904
- $orderid = $_REQUEST['Data_id'] ?? null;
905
- $smseid = $_REQUEST['Smseid'] ?? null;
906
- $order = wc_get_order($orderid);
907
-
908
- if (!$order || $order->get_meta('_smilepay_logistic_info')['smseid'] !== $smseid) {
909
- wp_die("<Roturlstatus>訂單{$orderid}追蹤碼{$smseid}不存在</Roturlstatus>", '超商物流狀態', 200);
910
- }
911
-
912
- // BIG5 -> UTF-8
913
- $req = $_REQUEST;
914
- foreach ($req as $k => $v) {
915
- if (mb_detect_encoding(urldecode($v), 'BIG5', true)) {
916
- $req[$k] = mb_convert_encoding(urldecode($v), 'UTF-8', 'BIG5');
917
- }
918
- }
919
-
920
- $ship_status = (int)($req['Shipstatus'] ?? 0);
921
- $logistic_info = $order->get_meta('_smilepay_logistic_info');
922
-
923
- // C2C / B2C 走不同分支
924
- if (str_contains($logistic_info['cvs_service_type'], 'C2C')) {
925
- switch ($ship_status) {
926
- case 1: $order->update_status('shipped'); break;
927
- case 2: $order->update_status('cvs-delivered'); break;
928
- case 3: $order->update_status('cvs-pickedup'); break;
929
- case 4: $order->update_status('cancelled'); break;
930
- }
931
- } else { // B2C
932
- switch ($ship_status) {
933
- case 1:
934
- case 11: $order->update_status('shipped'); break;
935
- case 2: $order->update_status('cvs-delivered'); break;
936
- case 3: $order->update_status('completed'); break;
937
- case 4: $order->update_status('cancelled'); break;
938
- }
939
- }
940
-
941
- wp_die('<Roturlstatus>woook1.1.23</Roturlstatus>', '超商物流狀態', 200);
942
- }
943
- add_action('woocommerce_api_smilepay_cvs_logistic_status', 'smilepay_cvs_logistic_status_handler');
944
- ```
945
-
946
- ---
947
-
948
- ## 退貨流程
949
-
950
- SmilePay 提供兩種退貨流程:**CVS C2B 退貨便** 與 **TCAT 逆物流**。
951
-
952
- ### CVS C2B 退貨便(消費者寄回到商家)
953
-
954
- 讓消費者透過超商把商品寄回給商家。
955
-
956
- #### 流程
957
-
958
- 1. 商家後台對退貨訂單觸發 C2B 退貨便產生。
959
- 2. 系統開啟 SmilePay **mtmk 電子地圖頁**,讓消費者選一間退貨門市。
960
- 3. 選店完成後,SmilePay 會 POST 退貨便代碼到商家設定的 `MapRoturl`。
961
- 4. 商家可以再呼叫 `C2BPayment.asp?types=Web` 取得列印頁。
962
-
963
- #### 端點
964
-
965
- ```
966
- GET https://ssl.smse.com.tw/ezpos/mtmk_utf.asp
967
- ```
968
-
969
- #### 參數
970
-
971
- | 參數 | 必填 | 說明 |
972
- |------|------|------|
973
- | `Dcvc` | ● | 商家代號 |
974
- | `Rvg2c` | ● | 簽章驗證代碼 |
975
- | `Verify_key` | ● | 共享密鑰 |
976
- | `Od_sob` | ● | 訂單編號(會原樣回傳) |
977
- | `Pay_zg` | ● | C2B 退貨便用值(商家後台設定的 `c2b_payzg`,依超商不同) |
978
- | `Pay_subzg` | ● | `7NET` 或 `FAMI` |
979
- | `Data_id` | ● | 訂單編號 |
980
- | `Amount` | ● | 退款金額 |
981
- | `Pur_name` | ● | 退貨人姓名 |
982
- | `Tel_number` | ● | 退貨人電話 |
983
- | `Mobile_number` | △ | 手機 |
984
- | `Email` | △ | Email |
985
- | `Remark` | △ | 備註 |
986
- | `MapRoturl` | ● | **選店完成後 SmilePay 回呼的網址** |
987
- | `Logistics_Roturl` | ● | 物流貨況通知網址 |
988
- | `Roturl_status` | △ | 回傳識別碼 |
989
-
990
- #### MapRoturl 回呼欄位
991
-
992
- | 參數 | 說明 |
993
- |------|------|
994
- | `Status` | `1` = 成功 |
995
- | `Smseid` | SmilePay 退貨追蹤碼 |
996
- | `Paymentno` | 退貨便代碼前段 |
997
- | `Validationno` | 退貨便驗證碼 |
998
- | `Data_id` | 訂單編號(原樣回傳) |
999
-
1000
- 完整退貨便代碼 = `Paymentno` + `Validationno`
1001
-
1002
- #### PHP 範例
1003
-
1004
- ```php
1005
- <?php
1006
- function trigger_c2b_return($order) {
1007
- $logistic_info = $order->get_meta('_smilepay_logistic_info');
1008
-
1009
- $params = [
1010
- 'Dcvc' => SMILEPAY_DCVC,
1011
- 'Rvg2c' => SMILEPAY_RVG2C,
1012
- 'Verify_key' => SMILEPAY_VERIFY_KEY,
1013
- 'Od_sob' => $order->get_id(),
1014
- 'Pay_zg' => SMILEPAY_C2B_PAYZG, // 商家後台設定
1015
- 'Pay_subzg' => $logistic_info['pay_subzg'], // 7NET / FAMI
1016
- 'Data_id' => $order->get_id(),
1017
- 'Amount' => round($order->get_total()),
1018
- 'Pur_name' => $order->get_billing_last_name() . $order->get_billing_first_name(),
1019
- 'Tel_number' => $order->get_billing_phone(),
1020
- 'Mobile_number' => $order->get_billing_phone(),
1021
- 'Email' => $order->get_billing_email(),
1022
- 'Remark' => $order->get_customer_note(),
1023
- 'MapRoturl' => home_url('/wc-api/smilepay_save_c2b'),
1024
- 'Logistics_Roturl' => home_url('/wc-api/smilepay_cvs_logistic_status'),
1025
- 'Roturl_status' => 'woook1.1.23',
1026
- ];
1027
-
1028
- $url = 'https://ssl.smse.com.tw/ezpos/mtmk_utf.asp?' . http_build_query($params);
1029
- // 在新分頁開啟讓消費者選店
1030
- echo "<script>window.open('{$url}', '_blank')</script>";
1031
- }
1032
-
1033
- // MapRoturl callback handler
1034
- function smilepay_save_c2b_handler() {
1035
- if ($_REQUEST['Status'] != 1) wp_die('退貨便建立失敗');
1036
-
1037
- $order_id = $_REQUEST['Data_id'];
1038
- $order = wc_get_order($order_id);
1039
-
1040
- $code = $_REQUEST['Paymentno'] . $_REQUEST['Validationno'];
1041
- $order->add_order_note("退貨便代碼:{$code}", 1);
1042
-
1043
- // 開啟列印頁
1044
- $print_url = 'https://ssl.smse.com.tw/api/C2BPayment.asp?' . http_build_query([
1045
- 'Dcvc' => SMILEPAY_DCVC,
1046
- 'Verify_key' => SMILEPAY_VERIFY_KEY,
1047
- 'smseid' => $_REQUEST['Smseid'],
1048
- 'types' => 'Web',
1049
- ]);
1050
- wp_redirect($print_url);
1051
- exit;
1052
- }
1053
- add_action('woocommerce_api_smilepay_save_c2b', 'smilepay_save_c2b_handler');
1054
- ```
1055
-
1056
- ### TCAT 逆物流(黑貓到府收件後寄回)
1057
-
1058
- 讓黑貓到消費者府上收件,再寄回商家倉庫。
1059
-
1060
- #### 流程(兩階段呼叫)
1061
-
1062
- 1. 第一階段:呼叫 `SPPayment.asp`,`Pay_zg = 83`、`Pay_subzg = TCAT`,取得退貨用 `SmilePayNO`。
1063
- 2. 第二階段:拿這個 `SmilePayNO` 呼叫 `ezcatGetTrackNum.asp`,取得逆物流 `TrackNum`。
1064
-
1065
- #### 第一階段參數(與正向取號類似)
1066
-
1067
- ```php
1068
- $post_data = [
1069
- 'Dcvc' => $dcvc,
1070
- 'Rvg2c' => $rvg2c,
1071
- 'Verify_key' => $verify_key,
1072
- 'Od_sob' => $order->get_id(),
1073
- 'Pay_zg' => 83, // RETCAT_PAY_ZG
1074
- 'Pay_subzg' => 'TCAT',
1075
- 'Data_id' => $order->get_id(),
1076
- 'Address' => $consumer_address, // 消費者地址(要去取件的地方)
1077
- 'Amount' => round($order->get_total()),
1078
- 'Pur_name' => $consumer_name,
1079
- 'Tel_number' => $consumer_phone,
1080
- 'Mobile_number' => $consumer_phone,
1081
- 'Email' => $order->get_billing_email(),
1082
- 'Remark' => $order->get_customer_note(),
1083
- 'Logistics_Roturl' => home_url('/wc-api/smilepay_tcat_logistic_status'),
1084
- 'Roturl_status' => 'woook1.1.23',
1085
- ];
1086
- $response = wp_remote_post('https://ssl.smse.com.tw/api/SPPayment.asp', ['body' => http_build_query($post_data)]);
1087
- $xml = simplexml_load_string(wp_remote_retrieve_body($response));
1088
- $retcat_smseid = (string)$xml->SmilePayNO;
1089
- ```
1090
-
1091
- #### 第二階段:取得逆物流 TrackNum
1092
-
1093
- | 參數 | 必填 | 說明 |
1094
- |------|------|------|
1095
- | `Dcvc` | ● | 商家代號 |
1096
- | `Verify_key` | ● | 共享密鑰 |
1097
- | `smseid` | ● | 第一階段拿到的退貨 SmilePayNO |
1098
- | `package_size` | ● | 包裹尺寸 |
1099
- | `temperature` | ● | 溫層(同正向:`0001`/`0002`/`0003`) |
1100
- | `delivery_date` | △ | 預定收件日 |
1101
- | `delivery_timezone` | △ | 預定收件時段 |
1102
- | `is_protect` | △ | 易碎品保護 |
1103
- | `shipment_type` | △ | 出貨類型 |
1104
- | `receiver_address` | ● | **收件地址**(這裡指商家的倉庫地址,黑貓送回去的目的地) |
1105
-
1106
- #### 回應
1107
-
1108
- ```xml
1109
- <SmilePay>
1110
- <Status>1</Status>
1111
- <Smseid>1234567890</Smseid>
1112
- <TrackNum>900987654321</TrackNum>
1113
- <Pur_name>王小明</Pur_name>
1114
- <Tel_number>0912345678</Tel_number>
1115
- </SmilePay>
1116
- ```
1117
-
1118
- ---
1119
-
1120
- ## 錯誤代碼
1121
-
1122
- ### 共用 Status 代碼
1123
-
1124
- | Status | 說明 | 處理方式 |
1125
- |--------|------|---------|
1126
- | `1` | 成功 | 正常處理 |
1127
- | `非 1` | 失敗(具體原因見 `<Desc>`) | 依 `Desc` 處理;常見錯誤見下表 |
1128
-
1129
- ### 常見失敗訊息(出現在 `<Desc>` 中)
1130
-
1131
- | Desc | 意思 | 處理 |
1132
- |------|------|------|
1133
- | 驗證失敗 | `Dcvc` 或 `Verify_key` 錯誤 | 檢查憑證;測試 / 正式不要混用 |
1134
- | 必填欄位不完整 | 漏送必填欄位 | 比對請求參數表 |
1135
- | Pay_zg 錯誤 | `Pay_zg` 數值與 `Pay_subzg` 不匹配 | 檢查編碼矩陣表 |
1136
- | 訂單編號重複 | `Data_id` 已使用過 | 改用獨立的訂單號(建議 prefix + timestamp) |
1137
- | 商品名稱過長 | `od_sob` 超過字數上限 | CVS 截 35 字 / TCAT 截 45 字 |
1138
- | 金額異常 | `Amount` 超出商品金額限制 | 7-11 / 全家 C2C 最高 19,999;確認商家後台額度 |
1139
- | 該物流業者拒收 | 例如 7-11 不收冷凍 | 改用合適的物流產品 |
1140
-
1141
- ### 連線錯誤
1142
-
1143
- WordPress / cURL 層級的錯誤(例如 `WP_Error`):
1144
-
1145
- ```php
1146
- if (is_wp_error($response)) {
1147
- $msg = $response->get_error_message();
1148
- // 常見:cURL error 28: Operation timed out
1149
- // cURL error 6: Could not resolve host
1150
- error_log("SmilePay 物流連線失敗:{$msg}");
1151
- }
1152
- ```
1153
-
1154
- 建議重試策略:
1155
- - 連線層失敗:可重試(最多 2 次,間隔 30 秒)
1156
- - `Status != 1` 且為驗證/參數類錯誤:**不要重試**,直接記錄並讓人工介入。
1157
-
1158
- ---
1159
-
1160
- ## 物流類型對照表
1161
-
1162
- ### 物流方法 ID 與超商代碼
1163
-
1164
- | WC 物流方法 ID | 顯示名稱 | typesserver | store_type | API 入口 |
1165
- |---------------|---------|-------------|------------|---------|
1166
- | `WC_SmilePay_CVS_711` | 速買配 7-11 超商取貨 | `711C2C` 或 `711B2C` | `711` | `SPPayment.asp` |
1167
- | `WC_SmilePay_CVS_FAMI` | 速買配 全家超商取貨 | `FAMIC2C` | `FAMI` | `SPPayment.asp` |
1168
- | `WC_SmilePay_TCAT_NORMAL` | 速買配 黑貓常溫宅配 | — | `TCAT` | `SPPayment.asp` |
1169
- | `WC_SmilePay_TCAT_REFRIGE` | 速買配 黑貓冷藏宅配 | — | `TCAT` | `SPPayment.asp` |
1170
- | `WC_SmilePay_TCAT_FREEZE` | 速買配 黑貓冷凍宅配 | — | `TCAT` | `SPPayment.asp` |
1171
-
1172
- ### TCAT 溫層代碼
1173
-
1174
- | WC 物流方法 | temperature | 溫度區間 |
1175
- |-------------|-------------|---------|
1176
- | `WC_SmilePay_TCAT_NORMAL` | `0001` | 常溫 |
1177
- | `WC_SmilePay_TCAT_REFRIGE` | `0002` | 冷藏 0~7°C |
1178
- | `WC_SmilePay_TCAT_FREEZE` | `0003` | 冷凍 -18°C |
1179
-
1180
- ### 包裹尺寸(TCAT)
1181
-
1182
- | package_size | 尺寸 |
1183
- |--------------|------|
1184
- | `60` | 60cm |
1185
- | `90` | 90cm |
1186
- | `120` | 120cm |
1187
- | `150` | 150cm |
1188
-
1189
- ### 預定送達時段(TCAT)
1190
-
1191
- | delivery_timezone | 時段 |
1192
- |-------------------|------|
1193
- | `1` | 13:00 前 |
1194
- | `2` | 14:00–18:00 |
1195
- | `4` | 不限時 |
1196
-
1197
- ### CVS 追蹤頁
1198
-
1199
- | 物流類型 | 追蹤網址 |
1200
- |---------|---------|
1201
- | 7-11 (C2C / B2C) | `https://eservice.7-11.com.tw/E-Tracking/search.aspx` |
1202
- | 全家 (C2C) | `https://www.famiport.com.tw/Web_Famiport/page/process.aspx` |
1203
- | 黑貓 (TCAT) | `https://www.t-cat.com.tw/inquire/trace.aspx` |
1204
-
1205
- ### B2C 7-11 號碼前綴
1206
-
1207
- 7-11 B2C 大宗寄倉的查詢碼必須加上 **`766`** 前綴:
1208
-
1209
- ```
1210
- 完整查詢碼 = '766' + EshopOrderNo
1211
- ```
1212
-
1213
- 例:`EshopOrderNo = 0987654321` → 至 7-11 查詢頁輸入 `7660987654321`
1214
-
1215
- ---
1216
-
1217
- ## 常見問題排解
1218
-
1219
- ### Q1:取號時收到 `Status=-2`,但所有欄位都填了?
1220
-
1221
- A:通常是 `Verify_key` 錯誤,或測試 / 正式環境憑證混用。
1222
- 請確認 `Dcvc` 與 `Verify_key` 配對正確,以及 `testmode_enabled` 切換是否正確。
1223
-
1224
- ### Q2:`Pay_zg` 與 `Pay_subzg` 怎麼選錯了會怎樣?
1225
-
1226
- A:常見錯誤情境:
1227
- - `Pay_zg=51` (C2C COD) + `Pay_subzg=TCAT` → 編碼矛盾,會回 `Pay_zg 錯誤` 或無聲失敗。
1228
- - `Pay_zg=81` (TCAT) + `Pay_subzg=7NET` → 同樣矛盾。
1229
- - 一律對著「Pay_zg / Pay_subzg 完整編碼對照表」核對,再送 API。
1230
-
1231
- ### Q3:超商取貨地圖選店後資料丟了?
1232
-
1233
- A:檢查 `tempvar` 與 `url` 是否被 URL Encode。SmilePay 是用 GET 把所有資料附在
1234
- 網址後面,未轉義的特殊字元(`#`、`&`)會截斷參數。請務必 `urlencode()` 包過。
1235
-
1236
- ### Q4:CVS 通知亂碼?
1237
-
1238
- A:SmilePay 部分 CVS 通知欄位以 BIG5 編碼回傳(特別是 `Storename`)。
1239
- 務必加入 BIG5 偵測 + 轉碼邏輯(見「通知與貨況」章節範例)。
1240
-
1241
- ### Q5:TCAT 取號成功但 `ezcatGetTrackNum` 失敗?
1242
-
1243
- A:黑貓比超商更嚴格,常見原因:
1244
- - `Address` 不完整(少寫縣市),TCAT 會拒絕。
1245
- - `temperature` 與 `package_size` 組合違反黑貓規則(例如 150cm 冷凍)。
1246
- - `delivery_date` 過去或太遠(建議 T+1 ~ T+7 內)。
1247
-
1248
- ### Q6:通知端點要不要驗證簽章?
1249
-
1250
- A:SmilePay 物流通知**不送簽章**,也沒有 IP 白名單可驗。
1251
- 建議的防護方式:
1252
- 1. 比對 `Smseid` 是否與訂單記錄的 `_smilepay_logistic_info[smseid]` 一致。
1253
- 2. URL 帶 secret token (例如 `/wc-api/smilepay_cvs_logistic_status?token=xxx`),
1254
- server 端驗證 token。
1255
- 3. 寫入 log 後,再定期對帳。
1256
-
1257
- ### Q7:物流訂單成立失敗,要怎麼處理?
1258
-
1259
- A:建議流程(參考 plugin 中 `_sp_logistic_failed` 機制):
1260
- 1. 取號失敗時,把訂單狀態設成 `failed`。
1261
- 2. 在感謝頁顯示「物流訂單成立失敗,請重新下單」。
1262
- 3. 寫入 `wc-logger` 來源 `smilepay-logistic-info` 留下完整紀錄。
1263
- 4. 視需要寄通知給商家。
1264
-
1265
- ### Q8:能不能只用「純取貨(不付款)」搭超商?
1266
-
1267
- A:可以。`Pay_zg` 改用 `52` (C2C) 或 `56` (B2C) 即可,
1268
- WC 端記得**禁用「貨到付款」金流**避免重複扣款。
1269
- 原始 plugin 用 `cvs_only_cod` filter 控制這個邏輯。
1270
-
1271
- ### Q9:B2C 大宗寄倉與 C2C 店到店有什麼差?
1272
-
1273
- | 比較 | C2C 店到店 | B2C 大宗寄倉 |
1274
- |------|-----------|-------------|
1275
- | 取號 API | `C2CPayment(U).asp` | `B2CPayment.asp` |
1276
- | 列印 API | 自帶 (`types=Web`) | `B2C_MultiplePrint.asp` |
1277
- | 適合對象 | 個人 / 小批量出貨 | 商家大量出貨 |
1278
- | 號碼格式 | `paymentno` + `validationno` | `766` + `EshopOrderNo` |
1279
- | 可選店 | 7-11 / 全家 | 7-11(全家 B2C 較少見) |
1280
-
1281
- ### Q10:能否 B2C 與 C2C 同時開?
1282
-
1283
- A:可以。`SmilePay_Logistic` plugin 的 `cvs_service_type` 設為 `B2C` 時,
1284
- 全家 C2C 物流方法會被隱藏(`add_shipping_methods` 邏輯)。
1285
- 若要兩種同時提供,需要把超商分散至不同的 WC Shipping Zone。
1286
-
1287
- ### Q11:黑貓「異常通知」要顯示給消費者嗎?
1288
-
1289
- A:建議不要直接顯示。`DetailStatus` 中的 `00007 損壞`、`00014 遺失`
1290
- 這類可能造成消費者恐慌。建議:
1291
- 1. 寫入訂單 meta `_smilepay_logistic_info[logistic_status]`。
1292
- 2. 商家後台先看到、人工聯絡確認後,再決定要不要更新前台。
1293
-
1294
- ### Q12:SmilePay 物流 API 與金流 API 的 `Dcvc` 真的一樣嗎?
1295
-
1296
- A:**是**。原始 plugin 中物流設定有獨立的 `smilepay_logistic_dcvc` option,
1297
- 但「正式環境」實際使用的就是同一組 SmilePay 帳號。
1298
- 只是物流端與金流端可能有獨立的「服務權限」(例如某些帳號只開金流不開物流),
1299
- 申請時要確認兩邊都有開通。
1300
-
1301
- ### Q13:取號時 `Logistics_store` 該怎麼填?
1302
-
1303
- A:CVS 必填,格式為 `{store_id}/{store_name}/{store_address}`。
1304
- 例如:`131386/雙子星門市/台北市信義區市府路1號`。
1305
- 這份資料來自電子地圖選店的回呼,記得用 `/` 連接,不要用空白。
1306
-
1307
- ### Q14:訂單金額有上下限嗎?
1308
-
1309
- A:依物流類型有所不同(plugin 預設值參考):
1310
- - 7-11 / 全家 C2C:13 ~ 19,999 元
1311
- - 7-11 B2C:依與大智通的合約
1312
- - 黑貓宅配:無硬性上限,但超過一定金額需事先告知 SmilePay
1313
-
1314
- ### Q15:能否事先用測試帳號(107 / 1111)跑全流程?
1315
-
1316
- A:可以打 API 取號(會回正常的 `<SmilePay>` XML),
1317
- 但**實際物流不會執行**。建議的測試方法:
1318
- 1. 用測試帳號驗 API 流程、回呼處理、訂單狀態切換邏輯。
1319
- 2. 換正式帳號後,先以小額(10 元)真實下單一筆,驗證號碼可在超商查到。
1320
-
1321
- ---
1322
-
1323
- ## 官方資源
1324
-
1325
- - **官方網站**:https://www.smilepay.net/
1326
- - **物流文件**:請向 SmilePay 業務窗口索取最新版 PDF(不公開於官網)
1327
- - **技術客服**:customerservice@smilepay.net
1328
- - **服務電話**:(07)559-1828
1329
-
1330
- ---
1331
-
1332
- 最後更新:2026/05/07
1
+ # SmilePay Logistics API Reference
2
+
3
+ 速買配 (SmilePay) 物流 API 完整參考文件。
4
+
5
+ > **重要前置觀念**
6
+ > SmilePay 物流 API 與金流 API **共用同一個帳號** (`Dcvc` + `Verify_key`)。
7
+ > 你不會再看到「物流商代號」之類的東西 — SmilePay 是「金物流整合服務商」,
8
+ > 它在背後再串接 7-11、全家、黑貓 (TCAT) 等實際物流業者。
9
+ > 對開發者而言,所有物流產品都透過「**SmilePay 同一組 API + 不同的 `Pay_zg` / `Pay_subzg` 編碼**」
10
+ > 來路由。掌握這個矩陣是整合 SmilePay 物流的祖傳秘方。
11
+
12
+ ---
13
+
14
+ ## 目錄
15
+
16
+ 1. [基本說明](#基本說明)
17
+ 2. [環境資訊](#環境資訊)
18
+ 3. [認證方式](#認證方式)
19
+ 4. [API 端點總覽](#api-端點總覽)
20
+ 5. [物流類型分類](#物流類型分類)
21
+ 6. [Pay_zg / Pay_subzg 編碼矩陣](#pay_zg--pay_subzg-編碼矩陣)
22
+ 7. [取得物流編號](#取得物流編號)
23
+ 8. [電子地圖選店](#電子地圖選店)
24
+ 9. [列印託運單](#列印託運單)
25
+ 10. [通知與貨況](#通知與貨況)
26
+ 11. [退貨流程](#退貨流程)
27
+ 12. [錯誤代碼](#錯誤代碼)
28
+ 13. [物流類型對照表](#物流類型對照表)
29
+ 14. [常見問題排解](#常見問題排解)
30
+
31
+ ---
32
+
33
+ ## 基本說明
34
+
35
+ ### 服務範圍
36
+
37
+ SmilePay 物流 API 支援 **三大物流體系,共 7 種物流產品**:
38
+
39
+ | 物流體系 | 子類型 | 說明 |
40
+ |---------|--------|------|
41
+ | 7-11 超商取貨 | C2C 店到店 | 個人/小商家取貨;走 7-11 交貨便系統 |
42
+ | 7-11 超商取貨 | B2C 大宗寄倉 | 商家大量寄倉;走大智通配送中心 |
43
+ | 全家 超商取貨 | C2C 店到店 | 個人/小商家取貨;走全家店到店系統 |
44
+ | 全家 超商取貨 | B2C 大宗寄倉 | 商家大量寄倉 (走全家專屬配送) |
45
+ | 黑貓宅急便 | 常溫 | TCAT 室溫宅配 |
46
+ | 黑貓宅急便 | 冷藏 | TCAT 0~7°C 冷藏宅配 |
47
+ | 黑貓宅急便 | 冷凍 | TCAT -18°C 冷凍宅配 |
48
+
49
+ ### 整合方式
50
+
51
+ SmilePay 的物流 API 不是「一個物流業者一支 API」,而是**統一進入點 + 編碼分流**:
52
+
53
+ 1. **取號階段**:所有物流產品都先打 `SPPayment.asp`,用 `Pay_zg` 編碼指定要走哪一條路線。
54
+ 2. **後續操作**:依照取號回應拿到的 `SmilePayNO` (跟金流的同一個 ID),搭配不同子端點處理。
55
+ 3. **回呼通知**:所有物流貨況變更都會 POST 到商家設定的 `Logistics_Roturl`,由 `Shipstatus` 數值決定狀態。
56
+
57
+ ### 資料格式
58
+
59
+ - 請求格式:`application/x-www-form-urlencoded` (POST)
60
+ - 回應格式:**XML**(注意:不是 JSON)
61
+ - 編碼:請求送出 UTF-8;某些貨況通知會以 BIG5 回傳 (建議偵測並轉碼)
62
+
63
+ ---
64
+
65
+ ## 環境資訊
66
+
67
+ ### 測試環境
68
+
69
+ SmilePay 提供官方測試帳號,可直接用來打通流程:
70
+
71
+ ```
72
+ Dcvc: 107
73
+ Rvg2c: 1
74
+ Verify_key: 174A02F97A95F72CE301137B3F98D128
75
+ Mid: 1111
76
+ ```
77
+
78
+ ### 正式環境
79
+
80
+ 正式帳號需向 SmilePay 業務窗口申請,會發放:
81
+
82
+ | 欄位 | 說明 | 範例 |
83
+ |------|------|------|
84
+ | `Dcvc` | 商家代號 | `12345` |
85
+ | `Rvg2c` | 簽章驗證代碼 | `1` |
86
+ | `Verify_key` | 共享密鑰 (32 碼 HEX) | `XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX` |
87
+ | `Mid` | 商店 ID | `12345` |
88
+
89
+ > **注意**:`Dcvc` + `Verify_key` 與 SmilePay **金流 API 共用**。同一個 SmilePay 帳號,
90
+ > 同時管理金流交易與物流追蹤碼。
91
+
92
+ ### API 主機
93
+
94
+ | 用途 | Hostname |
95
+ |------|----------|
96
+ | 全部物流 API | `ssl.smse.com.tw` |
97
+ | 電子地圖 (mtmk) | `ssl.smse.com.tw/ezpos/` |
98
+
99
+ 所有端點皆為 HTTPS,唯一例外:`ezcatGetTrackNum.asp` 與 `C2BPayment.asp`
100
+ 在原始程式碼中是 `http://`,但 `https://` 也可正常運作(建議統一用 HTTPS)。
101
+
102
+ ---
103
+
104
+ ## 認證方式
105
+
106
+ ### 共享密鑰機制
107
+
108
+ SmilePay 物流 API **沒有計算 CheckMacValue 之類的簽章**,而是透過 `Dcvc` + `Verify_key`
109
+ 作為「請求 + 帳號識別」雙重密碼。每個請求都必須夾帶這兩個欄位。
110
+
111
+ | 參數 | 必填 | 說明 |
112
+ |------|------|------|
113
+ | `Dcvc` | ● | 商家代號 |
114
+ | `Verify_key` | ● | 共享密鑰 |
115
+ | `Rvg2c` | △ | 部分端點需要(如 `SPPayment.asp`、退貨便、TCAT 列印) |
116
+
117
+ ### PHP 範例
118
+
119
+ ```php
120
+ <?php
121
+ $post_data = [
122
+ 'Dcvc' => '107',
123
+ 'Verify_key' => '174A02F97A95F72CE301137B3F98D128',
124
+ 'Rvg2c' => '1',
125
+ // ... 其他物流參數
126
+ ];
127
+
128
+ $body = http_build_query($post_data);
129
+ $response = wp_remote_post('https://ssl.smse.com.tw/api/SPPayment.asp', [
130
+ 'body' => $body,
131
+ ]);
132
+ $xml = simplexml_load_string(wp_remote_retrieve_body($response));
133
+ ```
134
+
135
+ ### Python 範例
136
+
137
+ ```python
138
+ import requests
139
+ import xml.etree.ElementTree as ET
140
+
141
+ post_data = {
142
+ 'Dcvc': '107',
143
+ 'Verify_key': '174A02F97A95F72CE301137B3F98D128',
144
+ 'Rvg2c': '1',
145
+ # ... 其他物流參數
146
+ }
147
+
148
+ resp = requests.post(
149
+ 'https://ssl.smse.com.tw/api/SPPayment.asp',
150
+ data=post_data,
151
+ timeout=30,
152
+ )
153
+ root = ET.fromstring(resp.text)
154
+ status = root.findtext('Status')
155
+ ```
156
+
157
+ ### 安全建議
158
+
159
+ - `Verify_key` 屬於高敏感憑證,**絕不能**寫死在前端 / 提交到 git。
160
+ - 建議用 WordPress option / 環境變數 (`SMILEPAY_VERIFY_KEY`) 集中管理。
161
+ - 物流 API 與金流 API 共用密鑰,撤銷會同時影響兩邊 — 異常時聯絡 SmilePay 換鑰。
162
+
163
+ ---
164
+
165
+ ## API 端點總覽
166
+
167
+ 所有端點 base URL 為:`https://ssl.smse.com.tw/api/`
168
+
169
+ ### 取號 / 修改
170
+
171
+ | 端點 | 方法 | 用途 |
172
+ |------|------|------|
173
+ | `SPPayment.asp` | POST | **建立物流訂單(取得 SmilePayNO)**;CVS C2C / B2C / TCAT 全部都從這裡開始 |
174
+ | `SPPayment_Modify.asp` | POST | 修改 CVS 訂單(換取貨人 / 換門市) |
175
+
176
+ ### 超商 (CVS) 後續流程
177
+
178
+ | 端點 | 方法 | 用途 |
179
+ |------|------|------|
180
+ | `C2CPayment.asp` | POST | C2C **取貨付款** 取交貨便號碼 |
181
+ | `C2CPaymentU.asp` | POST | C2C **純取貨(不付款)** 取交貨便號碼 |
182
+ | `B2CPayment.asp` | POST | B2C 大宗寄倉取交貨便號碼 |
183
+ | `B2C_MultiplePrint.asp` | GET | B2C 列印託運單(多單列印) |
184
+ | `C2BPayment.asp` | GET | C2B 退貨便列印 |
185
+ | `LogisticsEmap.asp` | GET | 電子地圖選店(C2C / B2C 共用) |
186
+
187
+ ### 黑貓 (TCAT) 後續流程
188
+
189
+ | 端點 | 方法 | 用途 |
190
+ |------|------|------|
191
+ | `ezcatGetTrackNum.asp` | POST | 取得黑貓託運編號(TrackNum) |
192
+ | `ezcatPrintDelivery.asp` | GET | 列印黑貓託運單 |
193
+
194
+ ### 電子地圖 / mtmk
195
+
196
+ | 端點 | 方法 | 用途 |
197
+ |------|------|------|
198
+ | `https://ssl.smse.com.tw/ezpos/mtmk_utf.asp` | GET | C2B 退貨便電子地圖(讓消費者選退貨門市) |
199
+
200
+ ---
201
+
202
+ ## 物流類型分類
203
+
204
+ SmilePay 物流可由「**寄送方式**」與「**金流方式**」兩個維度交叉。
205
+
206
+ ### 寄送方式
207
+
208
+ | 寄送方式 | 說明 |
209
+ |----------|------|
210
+ | 7-11 C2C 店到店 | `typesserver = 711C2C` |
211
+ | 7-11 B2C 大宗寄倉 | `typesserver = 711B2C` |
212
+ | 全家 C2C 店到店 | `typesserver = FAMIC2C` |
213
+ | 全家 B2C 大宗寄倉 | `typesserver = FAMIB2C`(部分商家可選用) |
214
+ | 黑貓 常溫 | TCAT (溫層 `0001`) |
215
+ | 黑貓 冷藏 | TCAT (溫層 `0002`) |
216
+ | 黑貓 冷凍 | TCAT (溫層 `0003`) |
217
+
218
+ ### 金流方式
219
+
220
+ | 金流方式 | 說明 | 影響 |
221
+ |----------|------|------|
222
+ | 取貨付款(COD) | 消費者取貨時付現給超商 / 黑貓 | 走 `_COD_PAY_ZG` 編碼 |
223
+ | 純取貨(PICKUP) | 消費者已預先付款,只需取貨 | 走 `_PICKUP_PAY_ZG` 編碼 |
224
+
225
+ ### WooCommerce 程式中的物流方法 ID
226
+
227
+ ```
228
+ WC_SmilePay_CVS_711 // 7-11 (C2C/B2C 由設定切換)
229
+ WC_SmilePay_CVS_FAMI // 全家 (C2C only)
230
+ WC_SmilePay_TCAT_NORMAL // 黑貓常溫
231
+ WC_SmilePay_TCAT_REFRIGE // 黑貓冷藏
232
+ WC_SmilePay_TCAT_FREEZE // 黑貓冷凍
233
+ ```
234
+
235
+ ---
236
+
237
+ ## Pay_zg / Pay_subzg 編碼矩陣
238
+
239
+ > **這是 SmilePay 物流的祖傳秘方** — 所有物流產品都從同一支 `SPPayment.asp`
240
+ > 進入,靠 `Pay_zg`(主要分類)+ `Pay_subzg`(副分類)來路由到實際物流業者。
241
+
242
+ ### Pay_zg(物流主分類)
243
+
244
+ | 常數名稱 | 值 | 用途 |
245
+ |----------|----|------|
246
+ | `C2C_COD_PAY_ZG` | `51` | 超商 C2C **取貨付款** |
247
+ | `C2C_PICKUP_PAY_ZG` | `52` | 超商 C2C **純取貨(不付款)** |
248
+ | `B2C_COD_PAY_ZG` | `55` | 超商 B2C **取貨付款** |
249
+ | `B2C_PICKUP_PAY_ZG` | `56` | 超商 B2C **純取貨** |
250
+ | `TCAT_COD_PAY_ZG` | `81` | 黑貓宅配 **取貨付款** |
251
+ | `TCAT_PICKUP_PAY_ZG` | `82` | 黑貓宅配 **純取貨** |
252
+ | `RETCAT_PAY_ZG` | `83` | 黑貓 **逆物流(退貨)** |
253
+ | `c2b_payzg` | (商家自訂) | C2B 退貨便(由商家後台設定,常見值依超商而異) |
254
+
255
+ ### Pay_subzg(物流副分類)
256
+
257
+ | 常數名稱 | 值 | 用途 |
258
+ |----------|----|------|
259
+ | `_711_PAY_SUBZG` | `7NET` | 走 7-11 / 大智通系統(C2C 與 B2C 都用這個) |
260
+ | `FAMI_PAY_SUBZG` | `FAMI` | 走全家系統 |
261
+ | TCAT 固定值 | `TCAT` | 黑貓宅配(含逆物流) |
262
+
263
+ ### 完整編碼對照表
264
+
265
+ | 寄送方式 | 金流方式 | `Pay_zg` | `Pay_subzg` |
266
+ |---------|---------|----------|-------------|
267
+ | 7-11 C2C 店到店 | 取貨付款 | `51` | `7NET` |
268
+ | 7-11 C2C 店到店 | 純取貨 | `52` | `7NET` |
269
+ | 7-11 B2C 大宗寄倉 | 取貨付款 | `55` | `7NET` |
270
+ | 7-11 B2C 大宗寄倉 | 純取貨 | `56` | `7NET` |
271
+ | 全家 C2C 店到店 | 取貨付款 | `51` | `FAMI` |
272
+ | 全家 C2C 店到店 | 純取貨 | `52` | `FAMI` |
273
+ | 全家 B2C 大宗寄倉 | 取貨付款 | `55` | `FAMI` |
274
+ | 全家 B2C 大宗寄倉 | 純取貨 | `56` | `FAMI` |
275
+ | 黑貓常溫 / 冷藏 / 冷凍 | 取貨付款 | `81` | `TCAT` |
276
+ | 黑貓常溫 / 冷藏 / 冷凍 | 純取貨 | `82` | `TCAT` |
277
+ | 黑貓逆物流(退貨) | — | `83` | `TCAT` |
278
+
279
+ **注意**:黑貓的「常溫 / 冷藏 / 冷凍」差異**不是**靠 `Pay_zg` 區分,
280
+ 而是走第二支 API `ezcatGetTrackNum.asp` 時的 `temperature` 參數
281
+ (`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍)。
282
+
283
+ ### 路由邏輯(PHP 範例)
284
+
285
+ ```php
286
+ // 根據使用者選擇的物流 + 金流,決定 Pay_zg / Pay_subzg
287
+ function determine_pay_codes(string $typesserver, string $payment_method): array {
288
+ $is_cod = $payment_method === 'cod';
289
+
290
+ // 7-11 與全家走同一組 Pay_zg,差別在 Pay_subzg
291
+ switch ($typesserver) {
292
+ case '711C2C':
293
+ return [
294
+ 'pay_zg' => $is_cod ? 51 : 52, // C2C_COD or C2C_PICKUP
295
+ 'pay_subzg' => '7NET',
296
+ ];
297
+ case '711B2C':
298
+ return [
299
+ 'pay_zg' => $is_cod ? 55 : 56, // B2C_COD or B2C_PICKUP
300
+ 'pay_subzg' => '7NET',
301
+ ];
302
+ case 'FAMIC2C':
303
+ return [
304
+ 'pay_zg' => $is_cod ? 51 : 52,
305
+ 'pay_subzg' => 'FAMI',
306
+ ];
307
+ case 'FAMIB2C':
308
+ return [
309
+ 'pay_zg' => $is_cod ? 55 : 56,
310
+ 'pay_subzg' => 'FAMI',
311
+ ];
312
+ }
313
+ throw new InvalidArgumentException("Unknown typesserver: {$typesserver}");
314
+ }
315
+ ```
316
+
317
+ ---
318
+
319
+ ## 取得物流編號
320
+
321
+ 物流取號分為兩個階段:
322
+
323
+ 1. **第一階段(共通)**:呼叫 `SPPayment.asp` 取得 `SmilePayNO`
324
+ 2. **第二階段(依物流產品)**:用 `SmilePayNO` 換取實際的「交貨便號碼」或「TCAT 託運單號」
325
+
326
+ ### 第一階段:取得 SmilePayNO
327
+
328
+ #### 端點
329
+
330
+ ```
331
+ POST https://ssl.smse.com.tw/api/SPPayment.asp
332
+ ```
333
+
334
+ #### 共通參數
335
+
336
+ | 參數 | 類型 | 必填 | 說明 |
337
+ |------|------|------|------|
338
+ | `Dcvc` | String | ● | 商家代號 |
339
+ | `Verify_key` | String(32) | ● | 共享密鑰 |
340
+ | `Rvg2c` | String | ● | 簽章驗證代碼 |
341
+ | `Pay_zg` | Integer | ● | 物流主分類(見上表) |
342
+ | `Pay_subzg` | String | ● | 物流副分類(`7NET` / `FAMI` / `TCAT`) |
343
+ | `Pur_name` | String | ● | 取貨人姓名 |
344
+ | `Tel_number` | String | ● | 取貨人電話 |
345
+ | `Mobile_number` | String | △ | 取貨人手機(建議與 Tel_number 同值) |
346
+ | `Email` | String | △ | 取貨人 Email |
347
+ | `Address` | String | △ | 取貨人地址(CVS 可省略,TCAT 必填) |
348
+ | `Data_id` | String | ● | 商家自訂訂單編號(必須唯一) |
349
+ | `od_sob` | String(35) / (45) | ● | 商品名稱(CVS 35 字 / TCAT 45 字內) |
350
+ | `Amount` | Integer | ● | 訂單總金額(取整) |
351
+ | `Logistics_store` | String | △ | CVS 必填,格式:`{store_id}/{store_name}/{store_address}` |
352
+ | `Roturl` | String(URL) | △ | 商家通用回傳網址 |
353
+ | `Logistics_Roturl` | String(URL) | ● | **物流貨況通知網址** |
354
+ | `Roturl_status` | String | △ | 回傳狀態識別碼(如 `woook1.1.23`) |
355
+ | `Remark` | String | △ | 備註(取自買家結帳備註) |
356
+
357
+ #### 回應(XML)
358
+
359
+ 成功:
360
+
361
+ ```xml
362
+ <?xml version="1.0" encoding="UTF-8"?>
363
+ <SmilePay>
364
+ <Status>1</Status>
365
+ <Desc>交易成功</Desc>
366
+ <SmilePayNO>1234567890</SmilePayNO>
367
+ <Data_id>WC-1024</Data_id>
368
+ <Amount>1500</Amount>
369
+ </SmilePay>
370
+ ```
371
+
372
+ 失敗:
373
+
374
+ ```xml
375
+ <?xml version="1.0" encoding="UTF-8"?>
376
+ <SmilePay>
377
+ <Status>-2</Status>
378
+ <Desc>驗證失敗</Desc>
379
+ </SmilePay>
380
+ ```
381
+
382
+ 判斷成功的鐵則:
383
+ - HTTP body 含 `<SmilePay>`
384
+ - `<Status>` 等於 `1`
385
+
386
+ ### 第二階段:取得實際物流編號
387
+
388
+ 依物流產品分為三條路徑:
389
+
390
+ #### A. 7-11 / 全家 C2C — 取交貨便號碼
391
+
392
+ ```
393
+ POST https://ssl.smse.com.tw/api/C2CPayment.asp # 取貨付款 (COD)
394
+ POST https://ssl.smse.com.tw/api/C2CPaymentU.asp # 純取貨 (PICKUP)
395
+ ```
396
+
397
+ | 參數 | 必填 | 說明 |
398
+ |------|------|------|
399
+ | `Dcvc` | ● | 商家代號 |
400
+ | `Verify_key` | ● | 共享密鑰 |
401
+ | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
402
+ | `Pay_subzg` | ● | `7NET` 或 `FAMI` |
403
+ | `types` | ● | `Xml` (取得 XML 回應) 或 `Web` (取得 HTML 列印頁網址) |
404
+
405
+ 回應(`types=Xml`):
406
+
407
+ ```xml
408
+ <SmilePay>
409
+ <Status>1</Status>
410
+ <paymentno>AB12345</paymentno>
411
+ <validationno>1234</validationno>
412
+ <storeid>131386</storeid>
413
+ <storename>雙子星門市</storename>
414
+ </SmilePay>
415
+ ```
416
+
417
+ 完整交貨便號碼 = `paymentno` + `validationno`(例:`AB123451234`)
418
+
419
+ #### B. 7-11 B2C — 取大宗寄倉編號
420
+
421
+ ```
422
+ POST https://ssl.smse.com.tw/api/B2CPayment.asp
423
+ ```
424
+
425
+ | 參數 | 必填 | 說明 |
426
+ |------|------|------|
427
+ | `Dcvc` | ● | 商家代號 |
428
+ | `Verify_key` | ● | 共享密鑰 |
429
+ | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
430
+
431
+ 回應:
432
+
433
+ ```xml
434
+ <SmilePay>
435
+ <Status>1</Status>
436
+ <EshopOrderNo>0987654321</EshopOrderNo>
437
+ <Storeid>131386</Storeid>
438
+ <StoreName>雙子星門市</StoreName>
439
+ </SmilePay>
440
+ ```
441
+
442
+ 7-11 B2C 完整查詢碼:`766` + `EshopOrderNo`
443
+
444
+ #### C. 黑貓 — 取託運單號
445
+
446
+ ```
447
+ POST https://ssl.smse.com.tw/api/ezcatGetTrackNum.asp
448
+ ```
449
+
450
+ | 參數 | 必填 | 說明 |
451
+ |------|------|------|
452
+ | `Dcvc` | ● | 商家代號 |
453
+ | `Verify_key` | ● | 共享密鑰 |
454
+ | `smseid` | ● | 第一階段拿到的 `SmilePayNO` |
455
+ | `package_size` | ● | 包裹尺寸(60/90/120/150 cm) |
456
+ | `temperature` | ● | 溫層:`0001` 常溫 / `0002` 冷藏 / `0003` 冷凍 |
457
+ | `delivery_date` | △ | 預定送達日 (`YYYY/MM/DD`) |
458
+ | `delivery_timezone` | △ | 預定送達時段(`1`/`2`/`4`) |
459
+ | `is_protect` | △ | 易碎品保護(`1` 啟用;`0` 不送出此參數) |
460
+ | `shipment_type` | △ | 出貨類型 |
461
+ | `receiver_address` | △ | 收件地址(逆物流時用) |
462
+
463
+ 回應:
464
+
465
+ ```xml
466
+ <SmilePay>
467
+ <Status>1</Status>
468
+ <TrackNum>900123456789</TrackNum>
469
+ <Smseid>1234567890</Smseid>
470
+ <Pur_name>王小明</Pur_name>
471
+ <Tel_number>0912345678</Tel_number>
472
+ </SmilePay>
473
+ ```
474
+
475
+ #### PHP 完整範例(C2C 取貨付款)
476
+
477
+ ```php
478
+ <?php
479
+ // === 第一階段:取得 SmilePayNO ===
480
+ $post_data = [
481
+ 'Dcvc' => '107',
482
+ 'Rvg2c' => '1',
483
+ 'Verify_key' => '174A02F97A95F72CE301137B3F98D128',
484
+ 'Pay_zg' => 51, // C2C COD
485
+ 'Pay_subzg' => '7NET', // 7-11
486
+ 'Pur_name' => '王小明',
487
+ 'Tel_number' => '0912345678',
488
+ 'Mobile_number' => '0912345678',
489
+ 'Email' => 'buyer@example.com',
490
+ 'Data_id' => 'WC-' . time(),
491
+ 'od_sob' => '商品A*1|商品B*2',
492
+ 'Amount' => 1500,
493
+ 'Logistics_store' => '131386/雙子星門市/台北市信義區市府路1號',
494
+ 'Roturl' => 'https://your-site.com/wc-api/roturl',
495
+ 'Logistics_Roturl' => 'https://your-site.com/wc-api/smilepay_cvs_logistic_status',
496
+ 'Roturl_status' => 'woook1.1.23',
497
+ 'Remark' => '請小心包裝',
498
+ ];
499
+
500
+ $response = wp_remote_post(
501
+ 'https://ssl.smse.com.tw/api/SPPayment.asp',
502
+ ['body' => http_build_query($post_data)]
503
+ );
504
+ $xml = simplexml_load_string(wp_remote_retrieve_body($response));
505
+
506
+ if ((string)$xml->Status !== '1') {
507
+ throw new Exception("取號失敗:{$xml->Desc}");
508
+ }
509
+ $smilepay_no = (string)$xml->SmilePayNO;
510
+
511
+ // === 第二階段:取得交貨便號碼 ===
512
+ $post_data2 = [
513
+ 'Dcvc' => '107',
514
+ 'Verify_key' => '174A02F97A95F72CE301137B3F98D128',
515
+ 'smseid' => $smilepay_no,
516
+ 'Pay_subzg' => '7NET',
517
+ 'types' => 'Xml',
518
+ ];
519
+ $response2 = wp_remote_post(
520
+ 'https://ssl.smse.com.tw/api/C2CPayment.asp', // 取貨付款用 C2CPayment.asp
521
+ ['body' => $post_data2]
522
+ );
523
+ $xml2 = simplexml_load_string(wp_remote_retrieve_body($response2));
524
+
525
+ $payment_no = (string)$xml2->paymentno . (string)$xml2->validationno;
526
+ echo "交貨便號碼:{$payment_no}";
527
+ ```
528
+
529
+ #### Python 範例(黑貓常溫宅配)
530
+
531
+ ```python
532
+ import requests
533
+ import xml.etree.ElementTree as ET
534
+
535
+ # === 第一階段 ===
536
+ post_data = {
537
+ 'Dcvc': '107',
538
+ 'Rvg2c': '1',
539
+ 'Verify_key': '174A02F97A95F72CE301137B3F98D128',
540
+ 'Pay_zg': 81, # TCAT COD
541
+ 'Pay_subzg': 'TCAT',
542
+ 'Pur_name': '王小明',
543
+ 'Tel_number': '0912345678',
544
+ 'Mobile_number': '0912345678',
545
+ 'Email': 'buyer@example.com',
546
+ 'Address': '台北市信義區市府路1號',
547
+ 'Data_id': f'WC-{int(time.time())}',
548
+ 'od_sob': '商品A*1|商品B*2',
549
+ 'Amount': 1500,
550
+ 'Logistics_Roturl': 'https://your-site.com/wc-api/smilepay_tcat_logistic_status',
551
+ 'Roturl_status': 'woook1.1.23',
552
+ }
553
+
554
+ resp = requests.post('https://ssl.smse.com.tw/api/SPPayment.asp', data=post_data)
555
+ xml = ET.fromstring(resp.text)
556
+ assert xml.findtext('Status') == '1'
557
+ smilepay_no = xml.findtext('SmilePayNO')
558
+
559
+ # === 第二階段:取得 TCAT 託運單號 ===
560
+ post_data2 = {
561
+ 'Dcvc': '107',
562
+ 'Verify_key': '174A02F97A95F72CE301137B3F98D128',
563
+ 'smseid': smilepay_no,
564
+ 'package_size': '60',
565
+ 'temperature': '0001', # 0001=常溫
566
+ 'delivery_date': '2026/05/15',
567
+ 'delivery_timezone': '3', # 3=不限時
568
+ }
569
+ resp2 = requests.post('https://ssl.smse.com.tw/api/ezcatGetTrackNum.asp', data=post_data2)
570
+ xml2 = ET.fromstring(resp2.text)
571
+ track_num = xml2.findtext('TrackNum')
572
+ print(f'託運單號:{track_num}')
573
+ ```
574
+
575
+ ---
576
+
577
+ ## 電子地圖選店
578
+
579
+ 讓消費者在結帳階段選擇取貨門市。
580
+
581
+ ### 端點
582
+
583
+ ```
584
+ GET https://ssl.smse.com.tw/api/LogisticsEmap.asp
585
+ ```
586
+
587
+ ### 參數
588
+
589
+ | 參數 | 必填 | 說明 |
590
+ |------|------|------|
591
+ | `method` | ● | 固定 `GET` |
592
+ | `TypesServer` | ● | 物流伺服器類型 |
593
+ | `TypesInterface` | ● | `MOBILE` 或 `WEB` |
594
+ | `tempvar` | ● | 暫存參數(商家自訂的識別碼,會原樣回傳) |
595
+ | `url` | ● | 選店完成後 SmilePay 重導回去的網址 |
596
+
597
+ ### TypesServer 對照
598
+
599
+ | 值 | 說明 |
600
+ |------|------|
601
+ | `711C2C` | 7-11 C2C 店到店 |
602
+ | `711B2C` | 7-11 B2C 大宗寄倉 |
603
+ | `FAMIC2C` | 全家 C2C 店到店 |
604
+ | `FAMIB2C` | 全家 B2C 大宗寄倉 |
605
+
606
+ ### TypesInterface 對照
607
+
608
+ | 值 | 用途 |
609
+ |----|------|
610
+ | `MOBILE` | 手機介面 |
611
+ | `WEB` | 桌機介面 |
612
+
613
+ ### 範例網址
614
+
615
+ ```
616
+ https://ssl.smse.com.tw/api/LogisticsEmap.asp
617
+ ?method=GET
618
+ &TypesServer=711C2C
619
+ &TypesInterface=MOBILE
620
+ &tempvar=order_123
621
+ &url=https%3A%2F%2Fyour-site.com%2Fwc-api%2Fsmilepay_save_emap
622
+ ```
623
+
624
+ ### 選店回呼參數
625
+
626
+ 消費者選店完成後,SmilePay 會 POST/GET 以下欄位到 `url`:
627
+
628
+ | 參數 | 說明 |
629
+ |------|------|
630
+ | `tempvar` | 你送過去的暫存識別碼 |
631
+ | `Storeid` | 門市代號 |
632
+ | `Storename` | 門市名稱 |
633
+ | `StoreAddress` | 門市地址 |
634
+ | `TypesServer` | 物流類型(同送出) |
635
+
636
+ ### PHP 範例(產生選店連結)
637
+
638
+ ```php
639
+ <?php
640
+ function build_emap_url(string $typesserver, string $interface, string $tempvar, string $callback_url): string {
641
+ $base = 'https://ssl.smse.com.tw/api/LogisticsEmap.asp';
642
+ return sprintf(
643
+ '%s?method=GET&TypesServer=%s&TypesInterface=%s&tempvar=%s&url=%s',
644
+ $base,
645
+ $typesserver,
646
+ $interface, // MOBILE / WEB
647
+ urlencode($tempvar),
648
+ urlencode($callback_url),
649
+ );
650
+ }
651
+
652
+ // 例:開啟手機版的 7-11 C2C 電子地圖
653
+ $emap = build_emap_url(
654
+ '711C2C',
655
+ wp_is_mobile() ? 'MOBILE' : 'WEB',
656
+ 'order_' . get_current_user_id(),
657
+ home_url('/wc-api/smilepay_save_emap')
658
+ );
659
+ header("Location: {$emap}");
660
+ exit;
661
+ ```
662
+
663
+ ---
664
+
665
+ ## 列印託運單
666
+
667
+ ### 7-11 / 全家 C2C 列印
668
+
669
+ C2C 不需要呼叫額外端點,**直接組成 GET URL** 開啟瀏覽器即可:
670
+
671
+ ```php
672
+ $print_url = sprintf(
673
+ 'https://ssl.smse.com.tw/api/%s?%s',
674
+ $is_cod ? 'C2CPayment.asp' : 'C2CPaymentU.asp',
675
+ http_build_query([
676
+ 'Dcvc' => $dcvc,
677
+ 'Verify_key' => $verify_key,
678
+ 'smseid' => $smilepay_no,
679
+ 'Pay_subzg' => $pay_subzg,
680
+ 'types' => 'Web', // ← 這個參數讓回應變 HTML 列印頁
681
+ ])
682
+ );
683
+ // 開新分頁
684
+ echo "<a href='{$print_url}' target='_blank'>列印託運單</a>";
685
+ ```
686
+
687
+ ### 7-11 B2C 列印(多單合併)
688
+
689
+ ```
690
+ GET https://ssl.smse.com.tw/api/B2C_MultiplePrint.asp
691
+ ```
692
+
693
+ | 參數 | 必填 | 說明 |
694
+ |------|------|------|
695
+ | `Dcvc` | ● | 商家代號 |
696
+ | `Rvg2c` | ● | 固定 `1` |
697
+ | `Verify_key` | ● | 共享密鑰 |
698
+ | `PaperModel` | ● | 紙張規格(`1` = 標籤紙) |
699
+ | `smseid` | ● | SmilePayNO;多筆用 `,` 串接 |
700
+
701
+ ```php
702
+ $url = 'https://ssl.smse.com.tw/api/B2C_MultiplePrint.asp?' . http_build_query([
703
+ 'Rvg2c' => '1',
704
+ 'Dcvc' => $dcvc,
705
+ 'Verify_key' => $verify_key,
706
+ 'PaperModel' => '1',
707
+ 'smseid' => $smilepay_no, // 或多筆 '111,222,333'
708
+ ]);
709
+ ```
710
+
711
+ ### 黑貓列印託運單
712
+
713
+ ```
714
+ GET https://ssl.smse.com.tw/api/ezcatPrintDelivery.asp
715
+ ```
716
+
717
+ | 參數 | 必填 | 說明 |
718
+ |------|------|------|
719
+ | `Dcvc` | ● | 商家代號 |
720
+ | `Rvg2c` | ● | 簽章驗證代碼 |
721
+ | `Verify_key` | ● | 共享密鑰 |
722
+ | `Smseid` | ● | SmilePayNO(注意:是大寫 S) |
723
+ | `print_format` | ● | 列印格式(依後台設定,常見 `1`/`2`) |
724
+
725
+ ```php
726
+ $url = 'https://ssl.smse.com.tw/api/ezcatPrintDelivery.asp?' . http_build_query([
727
+ 'Dcvc' => $dcvc,
728
+ 'Rvg2c' => $rvg2c,
729
+ 'Verify_key' => $verify_key,
730
+ 'Smseid' => $smilepay_no,
731
+ 'print_format' => '1',
732
+ ]);
733
+ ```
734
+
735
+ ### C2B 退貨便列印
736
+
737
+ ```
738
+ GET https://ssl.smse.com.tw/api/C2BPayment.asp
739
+ ```
740
+
741
+ | 參數 | 必填 | 說明 |
742
+ |------|------|------|
743
+ | `Dcvc` | ● | 商家代號 |
744
+ | `Verify_key` | ● | 共享密鑰 |
745
+ | `smseid` | ● | C2B 取號回呼拿到的 Smseid |
746
+ | `types` | ● | `Web`(取得 HTML 列印頁) |
747
+
748
+ ---
749
+
750
+ ## 通知與貨況
751
+
752
+ 物流貨況變更時,SmilePay 會 POST 到取號時提供的 `Logistics_Roturl`。
753
+ **CVS 與 TCAT 走不同的 webhook 處理邏輯**。
754
+
755
+ ### CVS 貨況通知
756
+
757
+ #### 收到的欄位
758
+
759
+ | 參數 | 說明 |
760
+ |------|------|
761
+ | `Data_id` | 商家訂單編號(取號時送的 Data_id) |
762
+ | `Smseid` | SmilePay 物流追蹤碼 |
763
+ | `Shipstatus` | 貨況狀態碼(**整數**) |
764
+ | `Payment_no` | C2C:交貨便號碼 |
765
+ | `EshopOrderNo` | B2C:大宗寄倉編號 |
766
+ | `Storeid` | 門市代號 |
767
+ | `Storename` | 門市名稱 (可能 BIG5 編碼) |
768
+
769
+ #### Shipstatus 對照(C2C 7-11 / 全家)
770
+
771
+ | 代碼 | 中文意思 | 建議訂單狀態 |
772
+ |------|---------|-------------|
773
+ | `1` | 已出貨 | shipped |
774
+ | `2` | 已到達門市 | cvs-delivered |
775
+ | `3` | 消費者已取貨 | cvs-pickedup / completed |
776
+ | `4` | 消費者退貨 | cancelled |
777
+ | `5` | 已到退貨門市 | (不變更 WC 狀態) |
778
+ | `6` | 退貨已取貨 | (不變更 WC 狀態) |
779
+ | `7` | 退貨已至物流中心 | (不變更 WC 狀態) |
780
+
781
+ #### Shipstatus 對照(B2C — 7-11 大智通)
782
+
783
+ | 代碼 | 中文意思 | 建議訂單狀態 |
784
+ |------|---------|-------------|
785
+ | `1` | 大智通配送中 | shipped |
786
+ | `2` | 已到達門市 | cvs-delivered |
787
+ | `3` | 消費者已取貨 | completed |
788
+ | `4` | 消費者退貨 | cancelled |
789
+ | `5` | 已到退貨門市 | — |
790
+ | `6` | 退貨已取貨 | — |
791
+ | `7` | 退貨已至物流中心 | — |
792
+ | `11` | 已出貨(廠商出貨給大智通) | shipped |
793
+
794
+ #### 編碼處理(重要!)
795
+
796
+ CVS 通知中的 `Storename` 等中文欄位**可能以 BIG5 編碼回傳**。處理時必須偵測並轉碼:
797
+
798
+ ```php
799
+ foreach ($_REQUEST as $key => $val) {
800
+ if (mb_detect_encoding(urldecode($val), 'BIG5', true)) {
801
+ $_REQUEST[$key] = mb_convert_encoding(urldecode($val), 'UTF-8', 'BIG5');
802
+ }
803
+ }
804
+ ```
805
+
806
+ #### 回應格式
807
+
808
+ 不論成功失敗,必須以 HTTP 200 回應一段含 `<Roturlstatus>` 的 XML 片段:
809
+
810
+ ```php
811
+ // 成功處理
812
+ echo '<Roturlstatus>woook1.1.23</Roturlstatus>';
813
+ // 找不到訂單
814
+ echo "<Roturlstatus>訂單編號:{$id} 速買配追蹤碼:{$smseid} 沒有對應的Order物件</Roturlstatus>";
815
+ ```
816
+
817
+ `Roturl_status` 的字串需與取號時送出的 `Roturl_status` 相同(範例為 `woook1.1.23`)。
818
+
819
+ ### TCAT 貨況通知
820
+
821
+ #### 收到的欄位
822
+
823
+ | 參數 | 說明 |
824
+ |------|------|
825
+ | `Data_id` | 商家訂單編號 |
826
+ | `Smseid` | SmilePay 物流追蹤碼 |
827
+ | `Shipstatus` | 主貨況狀態碼 |
828
+ | `DetailStatus` | 配送異常子狀態碼(如有,優先處理) |
829
+ | `Payment_no` | TCAT 託運單號 |
830
+
831
+ #### Shipstatus 對照(黑貓)
832
+
833
+ | 代碼 | 中文意思 | 建議訂單狀態 |
834
+ |------|---------|-------------|
835
+ | `1` | 配送中 | shipped |
836
+ | `3` | 已配達 | ezcat-delivered |
837
+ | `5` | 退貨中 | cancelled |
838
+ | `7` | 退完 | cancelled |
839
+ | `8` | 集貨失敗 | cancelled |
840
+
841
+ > 黑貓只回 `1/3/5/7/8` 這幾個狀態,沒有 `2/4/6`。
842
+
843
+ #### DetailStatus 異常代碼(節錄)
844
+
845
+ | 代碼 | 異常類型 |
846
+ |------|---------|
847
+ | `00002` | 不在家 |
848
+ | `00007` | 損壞 |
849
+ | `00008` | 公司行號休息 |
850
+ | `00009` | 地址不明 |
851
+ | `00010` | 搬家 |
852
+ | `00011` | 拒收 |
853
+ | `00014` | 遺失 |
854
+ | `00015` | 暫置營業所 |
855
+ | `00016` | BASE 列管 |
856
+ | `00021` | 超大 |
857
+ | `00022` | 超重 |
858
+ | `00023` | 地址錯誤 |
859
+ | `00025` | 航班延誤 |
860
+ | `00219` | 暫置營業所 |
861
+ | `001` | 自行寄回 |
862
+ | `002` | 不退了 |
863
+ | `003` | 尚未收到商品 |
864
+ | `004` | 另約取件時間 |
865
+ | `005` | 電話錯誤 |
866
+ | `006` | 電話空號 |
867
+ | `007` | 電話未接 |
868
+ | `008` | 電話關機 |
869
+ | `009` | 超大 |
870
+ | `010` | 人不在 |
871
+ | `011` | 已收走 |
872
+ | `014` | 商品送達時已拒收退回 |
873
+ | `015` | 地址有誤 |
874
+ | `017` | PCHOME 通知取消 |
875
+ | `024` | 其他 |
876
+ | `025` | 已集貨 |
877
+ | `999` | 訂單復原 |
878
+ | `P26` | 另約時間 |
879
+ | `P27` | 電聯不上 |
880
+ | `P28` | 資料有誤 |
881
+ | `P29` | 無件可退 |
882
+ | `P30` | 超大超重 |
883
+ | `P31` | 已回收 |
884
+ | `P32` | 別家收走 |
885
+ | `P33` | 商品未到 |
886
+
887
+ > **處理順序**:通知進來時先檢查 `DetailStatus`,**有值就優先記錄異常**,
888
+ > 然後直接回應 `<Roturlstatus>接收到配送異常XXX</Roturlstatus>` 結束 (不再處理 `Shipstatus`)。
889
+
890
+ #### 回應格式
891
+
892
+ ```php
893
+ // 一般成功
894
+ echo '<Roturlstatus>woook1.1.23</Roturlstatus>';
895
+ // 異常回報
896
+ echo "<Roturlstatus>接收到配送異常{$detailstatus}</Roturlstatus>";
897
+ ```
898
+
899
+ ### 完整 PHP 通知處理範例
900
+
901
+ ```php
902
+ <?php
903
+ function smilepay_cvs_logistic_status_handler() {
904
+ $orderid = $_REQUEST['Data_id'] ?? null;
905
+ $smseid = $_REQUEST['Smseid'] ?? null;
906
+ $order = wc_get_order($orderid);
907
+
908
+ if (!$order || $order->get_meta('_smilepay_logistic_info')['smseid'] !== $smseid) {
909
+ wp_die("<Roturlstatus>訂單{$orderid}追蹤碼{$smseid}不存在</Roturlstatus>", '超商物流狀態', 200);
910
+ }
911
+
912
+ // BIG5 -> UTF-8
913
+ $req = $_REQUEST;
914
+ foreach ($req as $k => $v) {
915
+ if (mb_detect_encoding(urldecode($v), 'BIG5', true)) {
916
+ $req[$k] = mb_convert_encoding(urldecode($v), 'UTF-8', 'BIG5');
917
+ }
918
+ }
919
+
920
+ $ship_status = (int)($req['Shipstatus'] ?? 0);
921
+ $logistic_info = $order->get_meta('_smilepay_logistic_info');
922
+
923
+ // C2C / B2C 走不同分支
924
+ if (str_contains($logistic_info['cvs_service_type'], 'C2C')) {
925
+ switch ($ship_status) {
926
+ case 1: $order->update_status('shipped'); break;
927
+ case 2: $order->update_status('cvs-delivered'); break;
928
+ case 3: $order->update_status('cvs-pickedup'); break;
929
+ case 4: $order->update_status('cancelled'); break;
930
+ }
931
+ } else { // B2C
932
+ switch ($ship_status) {
933
+ case 1:
934
+ case 11: $order->update_status('shipped'); break;
935
+ case 2: $order->update_status('cvs-delivered'); break;
936
+ case 3: $order->update_status('completed'); break;
937
+ case 4: $order->update_status('cancelled'); break;
938
+ }
939
+ }
940
+
941
+ wp_die('<Roturlstatus>woook1.1.23</Roturlstatus>', '超商物流狀態', 200);
942
+ }
943
+ add_action('woocommerce_api_smilepay_cvs_logistic_status', 'smilepay_cvs_logistic_status_handler');
944
+ ```
945
+
946
+ ---
947
+
948
+ ## 退貨流程
949
+
950
+ SmilePay 提供兩種退貨流程:**CVS C2B 退貨便** 與 **TCAT 逆物流**。
951
+
952
+ ### CVS C2B 退貨便(消費者寄回到商家)
953
+
954
+ 讓消費者透過超商把商品寄回給商家。
955
+
956
+ #### 流程
957
+
958
+ 1. 商家後台對退貨訂單觸發 C2B 退貨便產生。
959
+ 2. 系統開啟 SmilePay **mtmk 電子地圖頁**,讓消費者選一間退貨門市。
960
+ 3. 選店完成後,SmilePay 會 POST 退貨便代碼到商家設定的 `MapRoturl`。
961
+ 4. 商家可以再呼叫 `C2BPayment.asp?types=Web` 取得列印頁。
962
+
963
+ #### 端點
964
+
965
+ ```
966
+ GET https://ssl.smse.com.tw/ezpos/mtmk_utf.asp
967
+ ```
968
+
969
+ #### 參數
970
+
971
+ | 參數 | 必填 | 說明 |
972
+ |------|------|------|
973
+ | `Dcvc` | ● | 商家代號 |
974
+ | `Rvg2c` | ● | 簽章驗證代碼 |
975
+ | `Verify_key` | ● | 共享密鑰 |
976
+ | `Od_sob` | ● | 訂單編號(會原樣回傳) |
977
+ | `Pay_zg` | ● | C2B 退貨便用值(商家後台設定的 `c2b_payzg`,依超商不同) |
978
+ | `Pay_subzg` | ● | `7NET` 或 `FAMI` |
979
+ | `Data_id` | ● | 訂單編號 |
980
+ | `Amount` | ● | 退款金額 |
981
+ | `Pur_name` | ● | 退貨人姓名 |
982
+ | `Tel_number` | ● | 退貨人電話 |
983
+ | `Mobile_number` | △ | 手機 |
984
+ | `Email` | △ | Email |
985
+ | `Remark` | △ | 備註 |
986
+ | `MapRoturl` | ● | **選店完成後 SmilePay 回呼的網址** |
987
+ | `Logistics_Roturl` | ● | 物流貨況通知網址 |
988
+ | `Roturl_status` | △ | 回傳識別碼 |
989
+
990
+ #### MapRoturl 回呼欄位
991
+
992
+ | 參數 | 說明 |
993
+ |------|------|
994
+ | `Status` | `1` = 成功 |
995
+ | `Smseid` | SmilePay 退貨追蹤碼 |
996
+ | `Paymentno` | 退貨便代碼前段 |
997
+ | `Validationno` | 退貨便驗證碼 |
998
+ | `Data_id` | 訂單編號(原樣回傳) |
999
+
1000
+ 完整退貨便代碼 = `Paymentno` + `Validationno`
1001
+
1002
+ #### PHP 範例
1003
+
1004
+ ```php
1005
+ <?php
1006
+ function trigger_c2b_return($order) {
1007
+ $logistic_info = $order->get_meta('_smilepay_logistic_info');
1008
+
1009
+ $params = [
1010
+ 'Dcvc' => SMILEPAY_DCVC,
1011
+ 'Rvg2c' => SMILEPAY_RVG2C,
1012
+ 'Verify_key' => SMILEPAY_VERIFY_KEY,
1013
+ 'Od_sob' => $order->get_id(),
1014
+ 'Pay_zg' => SMILEPAY_C2B_PAYZG, // 商家後台設定
1015
+ 'Pay_subzg' => $logistic_info['pay_subzg'], // 7NET / FAMI
1016
+ 'Data_id' => $order->get_id(),
1017
+ 'Amount' => round($order->get_total()),
1018
+ 'Pur_name' => $order->get_billing_last_name() . $order->get_billing_first_name(),
1019
+ 'Tel_number' => $order->get_billing_phone(),
1020
+ 'Mobile_number' => $order->get_billing_phone(),
1021
+ 'Email' => $order->get_billing_email(),
1022
+ 'Remark' => $order->get_customer_note(),
1023
+ 'MapRoturl' => home_url('/wc-api/smilepay_save_c2b'),
1024
+ 'Logistics_Roturl' => home_url('/wc-api/smilepay_cvs_logistic_status'),
1025
+ 'Roturl_status' => 'woook1.1.23',
1026
+ ];
1027
+
1028
+ $url = 'https://ssl.smse.com.tw/ezpos/mtmk_utf.asp?' . http_build_query($params);
1029
+ // 在新分頁開啟讓消費者選店
1030
+ echo "<script>window.open('{$url}', '_blank')</script>";
1031
+ }
1032
+
1033
+ // MapRoturl callback handler
1034
+ function smilepay_save_c2b_handler() {
1035
+ if ($_REQUEST['Status'] != 1) wp_die('退貨便建立失敗');
1036
+
1037
+ $order_id = $_REQUEST['Data_id'];
1038
+ $order = wc_get_order($order_id);
1039
+
1040
+ $code = $_REQUEST['Paymentno'] . $_REQUEST['Validationno'];
1041
+ $order->add_order_note("退貨便代碼:{$code}", 1);
1042
+
1043
+ // 開啟列印頁
1044
+ $print_url = 'https://ssl.smse.com.tw/api/C2BPayment.asp?' . http_build_query([
1045
+ 'Dcvc' => SMILEPAY_DCVC,
1046
+ 'Verify_key' => SMILEPAY_VERIFY_KEY,
1047
+ 'smseid' => $_REQUEST['Smseid'],
1048
+ 'types' => 'Web',
1049
+ ]);
1050
+ wp_redirect($print_url);
1051
+ exit;
1052
+ }
1053
+ add_action('woocommerce_api_smilepay_save_c2b', 'smilepay_save_c2b_handler');
1054
+ ```
1055
+
1056
+ ### TCAT 逆物流(黑貓到府收件後寄回)
1057
+
1058
+ 讓黑貓到消費者府上收件,再寄回商家倉庫。
1059
+
1060
+ #### 流程(兩階段呼叫)
1061
+
1062
+ 1. 第一階段:呼叫 `SPPayment.asp`,`Pay_zg = 83`、`Pay_subzg = TCAT`,取得退貨用 `SmilePayNO`。
1063
+ 2. 第二階段:拿這個 `SmilePayNO` 呼叫 `ezcatGetTrackNum.asp`,取得逆物流 `TrackNum`。
1064
+
1065
+ #### 第一階段參數(與正向取號類似)
1066
+
1067
+ ```php
1068
+ $post_data = [
1069
+ 'Dcvc' => $dcvc,
1070
+ 'Rvg2c' => $rvg2c,
1071
+ 'Verify_key' => $verify_key,
1072
+ 'Od_sob' => $order->get_id(),
1073
+ 'Pay_zg' => 83, // RETCAT_PAY_ZG
1074
+ 'Pay_subzg' => 'TCAT',
1075
+ 'Data_id' => $order->get_id(),
1076
+ 'Address' => $consumer_address, // 消費者地址(要去取件的地方)
1077
+ 'Amount' => round($order->get_total()),
1078
+ 'Pur_name' => $consumer_name,
1079
+ 'Tel_number' => $consumer_phone,
1080
+ 'Mobile_number' => $consumer_phone,
1081
+ 'Email' => $order->get_billing_email(),
1082
+ 'Remark' => $order->get_customer_note(),
1083
+ 'Logistics_Roturl' => home_url('/wc-api/smilepay_tcat_logistic_status'),
1084
+ 'Roturl_status' => 'woook1.1.23',
1085
+ ];
1086
+ $response = wp_remote_post('https://ssl.smse.com.tw/api/SPPayment.asp', ['body' => http_build_query($post_data)]);
1087
+ $xml = simplexml_load_string(wp_remote_retrieve_body($response));
1088
+ $retcat_smseid = (string)$xml->SmilePayNO;
1089
+ ```
1090
+
1091
+ #### 第二階段:取得逆物流 TrackNum
1092
+
1093
+ | 參數 | 必填 | 說明 |
1094
+ |------|------|------|
1095
+ | `Dcvc` | ● | 商家代號 |
1096
+ | `Verify_key` | ● | 共享密鑰 |
1097
+ | `smseid` | ● | 第一階段拿到的退貨 SmilePayNO |
1098
+ | `package_size` | ● | 包裹尺寸 |
1099
+ | `temperature` | ● | 溫層(同正向:`0001`/`0002`/`0003`) |
1100
+ | `delivery_date` | △ | 預定收件日 |
1101
+ | `delivery_timezone` | △ | 預定收件時段 |
1102
+ | `is_protect` | △ | 易碎品保護 |
1103
+ | `shipment_type` | △ | 出貨類型 |
1104
+ | `receiver_address` | ● | **收件地址**(這裡指商家的倉庫地址,黑貓送回去的目的地) |
1105
+
1106
+ #### 回應
1107
+
1108
+ ```xml
1109
+ <SmilePay>
1110
+ <Status>1</Status>
1111
+ <Smseid>1234567890</Smseid>
1112
+ <TrackNum>900987654321</TrackNum>
1113
+ <Pur_name>王小明</Pur_name>
1114
+ <Tel_number>0912345678</Tel_number>
1115
+ </SmilePay>
1116
+ ```
1117
+
1118
+ ---
1119
+
1120
+ ## 錯誤代碼
1121
+
1122
+ ### 共用 Status 代碼
1123
+
1124
+ | Status | 說明 | 處理方式 |
1125
+ |--------|------|---------|
1126
+ | `1` | 成功 | 正常處理 |
1127
+ | `非 1` | 失敗(具體原因見 `<Desc>`) | 依 `Desc` 處理;常見錯誤見下表 |
1128
+
1129
+ ### 常見失敗訊息(出現在 `<Desc>` 中)
1130
+
1131
+ | Desc | 意思 | 處理 |
1132
+ |------|------|------|
1133
+ | 驗證失敗 | `Dcvc` 或 `Verify_key` 錯誤 | 檢查憑證;測試 / 正式不要混用 |
1134
+ | 必填欄位不完整 | 漏送必填欄位 | 比對請求參數表 |
1135
+ | Pay_zg 錯誤 | `Pay_zg` 數值與 `Pay_subzg` 不匹配 | 檢查編碼矩陣表 |
1136
+ | 訂單編號重複 | `Data_id` 已使用過 | 改用獨立的訂單號(建議 prefix + timestamp) |
1137
+ | 商品名稱過長 | `od_sob` 超過字數上限 | CVS 截 35 字 / TCAT 截 45 字 |
1138
+ | 金額異常 | `Amount` 超出商品金額限制 | 7-11 / 全家 C2C 最高 19,999;確認商家後台額度 |
1139
+ | 該物流業者拒收 | 例如 7-11 不收冷凍 | 改用合適的物流產品 |
1140
+
1141
+ ### 連線錯誤
1142
+
1143
+ WordPress / cURL 層級的錯誤(例如 `WP_Error`):
1144
+
1145
+ ```php
1146
+ if (is_wp_error($response)) {
1147
+ $msg = $response->get_error_message();
1148
+ // 常見:cURL error 28: Operation timed out
1149
+ // cURL error 6: Could not resolve host
1150
+ error_log("SmilePay 物流連線失敗:{$msg}");
1151
+ }
1152
+ ```
1153
+
1154
+ 建議重試策略:
1155
+ - 連線層失敗:可重試(最多 2 次,間隔 30 秒)
1156
+ - `Status != 1` 且為驗證/參數類錯誤:**不要重試**,直接記錄並讓人工介入。
1157
+
1158
+ ---
1159
+
1160
+ ## 物流類型對照表
1161
+
1162
+ ### 物流方法 ID 與超商代碼
1163
+
1164
+ | WC 物流方法 ID | 顯示名稱 | typesserver | store_type | API 入口 |
1165
+ |---------------|---------|-------------|------------|---------|
1166
+ | `WC_SmilePay_CVS_711` | 速買配 7-11 超商取貨 | `711C2C` 或 `711B2C` | `711` | `SPPayment.asp` |
1167
+ | `WC_SmilePay_CVS_FAMI` | 速買配 全家超商取貨 | `FAMIC2C` | `FAMI` | `SPPayment.asp` |
1168
+ | `WC_SmilePay_TCAT_NORMAL` | 速買配 黑貓常溫宅配 | — | `TCAT` | `SPPayment.asp` |
1169
+ | `WC_SmilePay_TCAT_REFRIGE` | 速買配 黑貓冷藏宅配 | — | `TCAT` | `SPPayment.asp` |
1170
+ | `WC_SmilePay_TCAT_FREEZE` | 速買配 黑貓冷凍宅配 | — | `TCAT` | `SPPayment.asp` |
1171
+
1172
+ ### TCAT 溫層代碼
1173
+
1174
+ | WC 物流方法 | temperature | 溫度區間 |
1175
+ |-------------|-------------|---------|
1176
+ | `WC_SmilePay_TCAT_NORMAL` | `0001` | 常溫 |
1177
+ | `WC_SmilePay_TCAT_REFRIGE` | `0002` | 冷藏 0~7°C |
1178
+ | `WC_SmilePay_TCAT_FREEZE` | `0003` | 冷凍 -18°C |
1179
+
1180
+ ### 包裹尺寸(TCAT)
1181
+
1182
+ | package_size | 尺寸 |
1183
+ |--------------|------|
1184
+ | `60` | 60cm |
1185
+ | `90` | 90cm |
1186
+ | `120` | 120cm |
1187
+ | `150` | 150cm |
1188
+
1189
+ ### 預定送達時段(TCAT)
1190
+
1191
+ | delivery_timezone | 時段 |
1192
+ |-------------------|------|
1193
+ | `1` | 13:00 前 |
1194
+ | `2` | 14:00–18:00 |
1195
+ | `4` | 不限時 |
1196
+
1197
+ ### CVS 追蹤頁
1198
+
1199
+ | 物流類型 | 追蹤網址 |
1200
+ |---------|---------|
1201
+ | 7-11 (C2C / B2C) | `https://eservice.7-11.com.tw/E-Tracking/search.aspx` |
1202
+ | 全家 (C2C) | `https://www.famiport.com.tw/Web_Famiport/page/process.aspx` |
1203
+ | 黑貓 (TCAT) | `https://www.t-cat.com.tw/inquire/trace.aspx` |
1204
+
1205
+ ### B2C 7-11 號碼前綴
1206
+
1207
+ 7-11 B2C 大宗寄倉的查詢碼必須加上 **`766`** 前綴:
1208
+
1209
+ ```
1210
+ 完整查詢碼 = '766' + EshopOrderNo
1211
+ ```
1212
+
1213
+ 例:`EshopOrderNo = 0987654321` → 至 7-11 查詢頁輸入 `7660987654321`
1214
+
1215
+ ---
1216
+
1217
+ ## 常見問題排解
1218
+
1219
+ ### Q1:取號時收到 `Status=-2`,但所有欄位都填了?
1220
+
1221
+ A:通常是 `Verify_key` 錯誤,或測試 / 正式環境憑證混用。
1222
+ 請確認 `Dcvc` 與 `Verify_key` 配對正確,以及 `testmode_enabled` 切換是否正確。
1223
+
1224
+ ### Q2:`Pay_zg` 與 `Pay_subzg` 怎麼選錯了會怎樣?
1225
+
1226
+ A:常見錯誤情境:
1227
+ - `Pay_zg=51` (C2C COD) + `Pay_subzg=TCAT` → 編碼矛盾,會回 `Pay_zg 錯誤` 或無聲失敗。
1228
+ - `Pay_zg=81` (TCAT) + `Pay_subzg=7NET` → 同樣矛盾。
1229
+ - 一律對著「Pay_zg / Pay_subzg 完整編碼對照表」核對,再送 API。
1230
+
1231
+ ### Q3:超商取貨地圖選店後資料丟了?
1232
+
1233
+ A:檢查 `tempvar` 與 `url` 是否被 URL Encode。SmilePay 是用 GET 把所有資料附在
1234
+ 網址後面,未轉義的特殊字元(`#`、`&`)會截斷參數。請務必 `urlencode()` 包過。
1235
+
1236
+ ### Q4:CVS 通知亂碼?
1237
+
1238
+ A:SmilePay 部分 CVS 通知欄位以 BIG5 編碼回傳(特別是 `Storename`)。
1239
+ 務必加入 BIG5 偵測 + 轉碼邏輯(見「通知與貨況」章節範例)。
1240
+
1241
+ ### Q5:TCAT 取號成功但 `ezcatGetTrackNum` 失敗?
1242
+
1243
+ A:黑貓比超商更嚴格,常見原因:
1244
+ - `Address` 不完整(少寫縣市),TCAT 會拒絕。
1245
+ - `temperature` 與 `package_size` 組合違反黑貓規則(例如 150cm 冷凍)。
1246
+ - `delivery_date` 過去或太遠(建議 T+1 ~ T+7 內)。
1247
+
1248
+ ### Q6:通知端點要不要驗證簽章?
1249
+
1250
+ A:SmilePay 物流通知**不送簽章**,也沒有 IP 白名單可驗。
1251
+ 建議的防護方式:
1252
+ 1. 比對 `Smseid` 是否與訂單記錄的 `_smilepay_logistic_info[smseid]` 一致。
1253
+ 2. URL 帶 secret token (例如 `/wc-api/smilepay_cvs_logistic_status?token=xxx`),
1254
+ server 端驗證 token。
1255
+ 3. 寫入 log 後,再定期對帳。
1256
+
1257
+ ### Q7:物流訂單成立失敗,要怎麼處理?
1258
+
1259
+ A:建議流程(參考 plugin 中 `_sp_logistic_failed` 機制):
1260
+ 1. 取號失敗時,把訂單狀態設成 `failed`。
1261
+ 2. 在感謝頁顯示「物流訂單成立失敗,請重新下單」。
1262
+ 3. 寫入 `wc-logger` 來源 `smilepay-logistic-info` 留下完整紀錄。
1263
+ 4. 視需要寄通知給商家。
1264
+
1265
+ ### Q8:能不能只用「純取貨(不付款)」搭超商?
1266
+
1267
+ A:可以。`Pay_zg` 改用 `52` (C2C) 或 `56` (B2C) 即可,
1268
+ WC 端記得**禁用「貨到付款」金流**避免重複扣款。
1269
+ 原始 plugin 用 `cvs_only_cod` filter 控制這個邏輯。
1270
+
1271
+ ### Q9:B2C 大宗寄倉與 C2C 店到店有什麼差?
1272
+
1273
+ | 比較 | C2C 店到店 | B2C 大宗寄倉 |
1274
+ |------|-----------|-------------|
1275
+ | 取號 API | `C2CPayment(U).asp` | `B2CPayment.asp` |
1276
+ | 列印 API | 自帶 (`types=Web`) | `B2C_MultiplePrint.asp` |
1277
+ | 適合對象 | 個人 / 小批量出貨 | 商家大量出貨 |
1278
+ | 號碼格式 | `paymentno` + `validationno` | `766` + `EshopOrderNo` |
1279
+ | 可選店 | 7-11 / 全家 | 7-11(全家 B2C 較少見) |
1280
+
1281
+ ### Q10:能否 B2C 與 C2C 同時開?
1282
+
1283
+ A:可以。`SmilePay_Logistic` plugin 的 `cvs_service_type` 設為 `B2C` 時,
1284
+ 全家 C2C 物流方法會被隱藏(`add_shipping_methods` 邏輯)。
1285
+ 若要兩種同時提供,需要把超商分散至不同的 WC Shipping Zone。
1286
+
1287
+ ### Q11:黑貓「異常通知」要顯示給消費者嗎?
1288
+
1289
+ A:建議不要直接顯示。`DetailStatus` 中的 `00007 損壞`、`00014 遺失`
1290
+ 這類可能造成消費者恐慌。建議:
1291
+ 1. 寫入訂單 meta `_smilepay_logistic_info[logistic_status]`。
1292
+ 2. 商家後台先看到、人工聯絡確認後,再決定要不要更新前台。
1293
+
1294
+ ### Q12:SmilePay 物流 API 與金流 API 的 `Dcvc` 真的一樣嗎?
1295
+
1296
+ A:**是**。原始 plugin 中物流設定有獨立的 `smilepay_logistic_dcvc` option,
1297
+ 但「正式環境」實際使用的就是同一組 SmilePay 帳號。
1298
+ 只是物流端與金流端可能有獨立的「服務權限」(例如某些帳號只開金流不開物流),
1299
+ 申請時要確認兩邊都有開通。
1300
+
1301
+ ### Q13:取號時 `Logistics_store` 該怎麼填?
1302
+
1303
+ A:CVS 必填,格式為 `{store_id}/{store_name}/{store_address}`。
1304
+ 例如:`131386/雙子星門市/台北市信義區市府路1號`。
1305
+ 這份資料來自電子地圖選店的回呼,記得用 `/` 連接,不要用空白。
1306
+
1307
+ ### Q14:訂單金額有上下限嗎?
1308
+
1309
+ A:依物流類型有所不同(plugin 預設值參考):
1310
+ - 7-11 / 全家 C2C:13 ~ 19,999 元
1311
+ - 7-11 B2C:依與大智通的合約
1312
+ - 黑貓宅配:無硬性上限,但超過一定金額需事先告知 SmilePay
1313
+
1314
+ ### Q15:能否事先用測試帳號(107 / 1111)跑全流程?
1315
+
1316
+ A:可以打 API 取號(會回正常的 `<SmilePay>` XML),
1317
+ 但**實際物流不會執行**。建議的測試方法:
1318
+ 1. 用測試帳號驗 API 流程、回呼處理、訂單狀態切換邏輯。
1319
+ 2. 換正式帳號後,先以小額(10 元)真實下單一筆,驗證號碼可在超商查到。
1320
+
1321
+ ---
1322
+
1323
+ ## 官方資源
1324
+
1325
+ - **官方網站**:https://www.smilepay.net/
1326
+ - **物流文件**:請向 SmilePay 業務窗口索取最新版 PDF(不公開於官網)
1327
+ - **技術客服**:customerservice@smilepay.net
1328
+ - **服務電話**:(07)559-1828
1329
+
1330
+ ---
1331
+
1332
+ 最後更新:2026/05/07