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,1670 +1,1670 @@
1
- # PayNow Logistics API Reference
2
-
3
- 立吉富 PayNow 物流 API 完整參考文件,涵蓋 7-11、全家、黑貓、海外配送等 11 條產品線。
4
-
5
- ---
6
-
7
- ## 目錄
8
-
9
- 1. [API 端點總覽](#api-端點總覽)
10
- 2. [測試環境與認證](#測試環境與認證)
11
- 3. [物流服務代碼](#物流服務代碼)
12
- 4. [TripleDES 加密](#tripledes-加密)
13
- 5. [PassCode 計算 (SHA-1)](#passcode-計算-sha-1)
14
- 6. [選擇物流服務 (電子地圖)](#選擇物流服務-電子地圖)
15
- 7. [建立物流訂單](#建立物流訂單)
16
- 8. [7-11 大宗物流](#7-11-大宗物流)
17
- 9. [7-11 冷凍大宗 B2C](#7-11-冷凍大宗-b2c)
18
- 10. [7-11 冷凍店到店 (C2C)](#7-11-冷凍店到店-c2c)
19
- 11. [7-11 海外配送](#7-11-海外配送)
20
- 12. [全家大宗物流](#全家大宗物流)
21
- 13. [全家冷凍大宗 B2C](#全家冷凍大宗-b2c)
22
- 14. [全家冷凍店到店 (C2C)](#全家冷凍店到店-c2c)
23
- 15. [四大超商常溫 C2C](#四大超商常溫-c2c)
24
- 16. [黑貓宅配](#黑貓宅配)
25
- 17. [黑貓店到店](#黑貓店到店)
26
- 18. [查詢物流單](#查詢物流單)
27
- 19. [取消物流單](#取消物流單)
28
- 20. [重新取號](#重新取號)
29
- 21. [門市更新 (關轉)](#門市更新-關轉)
30
- 22. [物流貨態回傳 (Callback)](#物流貨態回傳-callback)
31
- 23. [貨態代碼對照表](#貨態代碼對照表)
32
-
33
- ---
34
-
35
- ## API 端點總覽
36
-
37
- ### 基礎網址
38
-
39
- | 環境 | 網址 |
40
- |------|------|
41
- | **正式環境** | `https://logistic.paynow.com.tw` |
42
- | **測試環境** | `https://testlogistic.paynow.com.tw` |
43
-
44
- > 注意:PayNow 物流 API 與金流共用同一網域結構,但物流走 `logistic.paynow.com.tw`,金流走 `www.paynow.com.tw/service/etopm.aspx`,兩者**不可混用**。
45
-
46
- ### 主要 API 路徑
47
-
48
- | 功能 | API URL | 方法 |
49
- |------|---------|------|
50
- | 選擇物流服務 (電子地圖) | `/Member/Order/Choselogistics` | POST |
51
- | 建立物流訂單 | `/api/Orderapi/Add_Order` | POST |
52
- | 7-11 大宗獲取出貨單號 | `/api/Bulk711Order/ShipBulk711paymentno` | POST |
53
- | 7-11 冷凍大宗獲取出貨單號 | `/api/711FreezingB2C/Ship711B2Cpaymentno` | POST |
54
- | 列印 7-11 大宗物流單 | `/Member/Order/Print711bulkLabel` | POST |
55
- | 列印 7-11 冷凍大宗物流單 | `/Member/Order/Print711FreezingB2CLabel` | POST |
56
- | 列印 7-11 冷凍 C2C 物流單 | `/Member/Order/Print711FreezingC2CLabel` | POST |
57
- | 列印 7-11 海外配送物流單 | `/api/OverSeas711Order` | GET |
58
- | 列印 7-11 交貨便物流單 | `/api/Order711` | GET |
59
- | 列印全家 C2C 物流單 | `/api/OrderFamiC2C` | GET |
60
- | 列印萊爾富物流單 | `/api/OrderHiLife` | GET |
61
- | 列印 OK 物流單 | `/api/OKC2C` | GET |
62
- | 列印黑貓宅急便標籤 | `/Member/Order/PrintBlackCatLabel` | POST |
63
- | 查詢物流單 (PayNow 單號) | `/api/Orderapi/Get_Order_Info` | GET |
64
- | 查詢物流單 (商家訂單編號) | `/api/Orderapi/Get_Order_Info_orderno` | GET |
65
- | 取消物流單 | `/api/Orderapi/CancelOrder` | DELETE |
66
- | 重新取號 | `/api/Orderapi/ReNewOrder` | POST |
67
- | 門市更新 (關轉) | `/api/Orderapi/Put` | PUT |
68
- | 更新物流訂單 (7-11 大宗) | `/api/Bulk711Order/UpdateB2C711Order` | PUT |
69
- | 更新物流訂單 (7-11 冷凍 B2C) | `/api/711FreezingB2C/Update711B2COrder` | PUT |
70
- | 建立 7-11 退貨物流單 | `/api/Orderapi/ReturnPaymentno` | PUT |
71
- | 7-11 海外配送-國家代碼 | `/api/OverSeas711Order/SelCountryID` | POST |
72
- | 7-11 海外配送-運費試算 | `/api/Orderapi/SelWeightChart` | POST |
73
- | 7-11 海外配送-費用查詢 (依訂單) | `/api/OverSeas711Order/SelBillDetail` | POST |
74
- | 7-11 海外配送-費用查詢 (依日期) | `/api/OverSeas711Order/SelBillDetailDate` | POST |
75
- | 全家 C2C 店號轉換 | `/api/OrderFamiC2C/GetFamiStoreID` | GET |
76
- | 全家冷凍店鋪空間保留 | `/api/FamiFreezingB2C/UpSpaceConfirm` | POST |
77
-
78
- ---
79
-
80
- ## 測試環境與認證
81
-
82
- ### 認證資料
83
-
84
- PayNow 物流 API 使用「商家主帳號 (`user_account`) + API 密碼 (`apicode`)」雙鑰機制,並透過 TripleDES 加密 + SHA-1 PassCode 雙重保護。
85
-
86
- | 項目 | 說明 |
87
- |------|------|
88
- | `user_account` | 商家主帳號,10 碼 |
89
- | `apicode` | 商家 API 密碼,30 碼,請以 TripleDES 加密後傳送 |
90
- | `partner_token` | 合作夥伴識別碼 (HTTP Header 帶入),用於回傭計算,非必填 |
91
-
92
- ### partner_token (合作夥伴識別)
93
-
94
- `partner_token` 為 HTTP Header 參數,用於辨識合作夥伴身份並計算回傭:
95
-
96
- ```http
97
- POST /api/Orderapi/Add_Order HTTP/1.1
98
- Host: logistic.paynow.com.tw
99
- Content-Type: application/x-www-form-urlencoded
100
- partner_token: YOUR_PARTNER_TOKEN
101
- ```
102
-
103
- 注意事項:
104
-
105
- - `partner_token` 為合作夥伴專屬識別碼,請妥善保管,不同合作夥伴的 token 不可共用
106
- - 如 token 遺失或洩漏,請立即聯繫 PayNow 申請更換
107
- - 未提供 `partner_token` 或 token 錯誤時,訂單仍可正常建立,但無法正確計算回傭
108
-
109
- ### 取得測試帳號
110
-
111
- 請聯繫 PayNow 客服 (`service@paynow.com.tw`) 申請測試環境帳號,取得:
112
-
113
- - 測試 `user_account`
114
- - 測試 `apicode`
115
- - TripleDES 公鑰 (8 bytes)
116
- - TripleDES 私鑰 (24 bytes)
117
-
118
- ---
119
-
120
- ## 物流服務代碼
121
-
122
- PayNow 物流以 `Logistic_serviceID` (對應建立訂單的 `Logistic_service` 欄位) 區分產品線:
123
-
124
- | Service ID | 物流服務 | 類型 |
125
- |------------|----------|------|
126
- | `01` | 7-11 交貨便 | C2C 常溫 |
127
- | `02` | 7-11 大宗物流 | B2C 常溫 |
128
- | `03` | 全家店到店 | C2C 常溫 |
129
- | `04` | 全家大宗物流 | B2C 常溫 |
130
- | `05` | 萊爾富店到店 | C2C 常溫 |
131
- | `06` | 黑貓宅急便 | 宅配 |
132
- | `07` | 7-11 海外配送 (店配) | 跨境店配 |
133
- | `08` | 7-11 海外配送 (宅配) | 跨境宅配 |
134
- | `10` | OK 店到店 | C2C 常溫 |
135
- | `12` | 7-11 大宗退貨便 | 退貨 |
136
- | `21` | 7-11 交貨便 (冷凍) | C2C 冷凍 |
137
- | `22` | 7-11 大宗物流 (冷凍) | B2C 冷凍 |
138
- | `23` | 全家店到店物流 (冷凍) | C2C 冷凍 |
139
- | `24` | 全家大宗物流 (冷凍) | B2C 冷凍 |
140
- | `36` | 黑貓宅急便 (PayNow) | 宅配 (含自動保險) |
141
- | `46` | 黑貓到店 (PayNow) | 店到店 |
142
-
143
- ---
144
-
145
- ## TripleDES 加密
146
-
147
- PayNow 物流的 `JsonOrder` 與 `apicode` 都需使用 TripleDES 加密後再 URLEncode 傳送,**這是與一般 PayNow 金流動態 AES-256 不同的加密機制**,物流端固定為 3DES/ECB/Zero Padding。
148
-
149
- ### 加密規格
150
-
151
- | 項目 | 值 |
152
- |------|-----|
153
- | 演算法 | 3DES (TripleDES) |
154
- | 模式 | ECB |
155
- | Padding | Zero Padding |
156
- | 公鑰 (IV) | 8 bytes (例:`12345678`) |
157
- | 私鑰 (Key) | 24 bytes (例:`123456789070828783123456`) |
158
- | 編碼輸出 | Base64,並把空白字元 `' '` 換成 `+` |
159
-
160
- ### 加解密前後範例 (摘自官方附錄)
161
-
162
- 加密前:
163
-
164
- ```json
165
- {"mem_type":2,"buysafeno":"8000001910145799460","mem_cid":"13099407","passcode":"2B24518AA4C2536CAF7ADCBC635C0751699BB7CC", ...}
166
- ```
167
-
168
- 加密後 (Base64):
169
-
170
- ```
171
- 229d7b9b639845a7f12cc8524a3988ce77647ced3cacec907bf5432b2df9f7a68055b05204f29d8e1b0ca4c9...
172
- ```
173
-
174
- ### C# 範例 (官方)
175
-
176
- ```csharp
177
- public string Encrypt(string content)
178
- {
179
- TripleDes.IV = Encoding.UTF8.GetBytes("12345678");
180
- TripleDes.Key = Encoding.UTF8.GetBytes("123456789070828783123456");
181
- TripleDes.Mode = CipherMode.ECB;
182
- TripleDes.Padding = PaddingMode.Zeros;
183
-
184
- var data = Encoding.UTF8.GetBytes(content);
185
- var ict = TripleDes.CreateEncryptor();
186
- var enc = ict.TransformFinalBlock(data, 0, data.Length);
187
- var result = Convert.ToBase64String(enc).Replace(' ', '+');
188
-
189
- return result;
190
- }
191
- ```
192
-
193
- ### PHP 範例
194
-
195
- ```php
196
- <?php
197
-
198
- function tripleDesEncrypt(string $content, string $key, string $iv): string
199
- {
200
- // 補齊 24 bytes 並使用 ECB;OpenSSL 需手動 zero-pad
201
- $blockSize = 8;
202
- $padLen = $blockSize - (strlen($content) % $blockSize);
203
- if ($padLen !== $blockSize) {
204
- $content .= str_repeat("\0", $padLen);
205
- }
206
-
207
- $encrypted = openssl_encrypt(
208
- $content,
209
- 'des-ede3',
210
- $key,
211
- OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING
212
- );
213
-
214
- return str_replace(' ', '+', base64_encode($encrypted));
215
- }
216
-
217
- // 使用
218
- $key = '123456789070828783123456'; // 24 bytes
219
- $iv = '12345678'; // 8 bytes (ECB 模式不會用到,但 spec 仍要傳)
220
- $jsonOrder = json_encode($orderData, JSON_UNESCAPED_UNICODE);
221
- $encrypted = tripleDesEncrypt($jsonOrder, $key, $iv);
222
- $postBody = 'JsonOrder=' . urlencode($encrypted);
223
- ```
224
-
225
- ### Python 範例
226
-
227
- ```python
228
- from Crypto.Cipher import DES3
229
- import base64
230
-
231
- def triple_des_encrypt(content: str, key: str) -> str:
232
- """PayNow 物流 TripleDES/ECB/Zero Padding"""
233
- block_size = 8
234
- data = content.encode('utf-8')
235
- pad_len = block_size - (len(data) % block_size)
236
- if pad_len != block_size:
237
- data += b'\x00' * pad_len
238
-
239
- cipher = DES3.new(key.encode('utf-8'), DES3.MODE_ECB)
240
- encrypted = cipher.encrypt(data)
241
- return base64.b64encode(encrypted).decode('ascii').replace(' ', '+')
242
-
243
- # 使用
244
- key = '123456789070828783123456' # 24 bytes
245
- encrypted = triple_des_encrypt(json_str, key)
246
- ```
247
-
248
- ---
249
-
250
- ## PassCode 計算 (SHA-1)
251
-
252
- PassCode 為 PayNow 物流防偽用雜湊值,作法為:將指定欄位依序串接後計算 SHA-1,輸出 40 字元大寫十六進位字串。
253
-
254
- ### 通用組成方式
255
-
256
- | 情境 | PassCode 組成 |
257
- |------|---------------|
258
- | 建立物流訂單 | `user_account + OrderNo + TotalAmount + apicode` |
259
- | 7-11 大宗獲取出貨單號 | `user_account + apicode` |
260
- | 重新取號 | `user_account + OrderNo + TotalAmount + apicode` |
261
- | 取消訂單 | `user_account + OrderNo + TotalAmount + apicode` |
262
- | 門市更新 (關轉) | `user_account + OrderNo + TotalAmount + apicode` |
263
- | 建立退貨物流單 | `user_account + LogisticNumber + apicode` |
264
-
265
- > 串接時 **不包含 `+` 符號**,僅是數值連接 (concat)。
266
- > 例:`user_account=28229955`、`OrderNo=211210165125`、`TotalAmount=200`、`apicode=12345678` → `2822995521121016512520012345678` → SHA-1 → `4CF47FD844DF64C5D0FBF8DD134708B55ABE208B`
267
-
268
- ### C# 範例 (官方)
269
-
270
- ```csharp
271
- public string SHA1Encrypt(string data)
272
- {
273
- SHA1CryptoServiceProvider sha1 = new SHA1CryptoServiceProvider();
274
- var keyBytes = Encoding.Default.GetBytes(data);
275
- var hash = sha1.ComputeHash(keyBytes);
276
- return BitConverter.ToString(hash).Replace("-", "");
277
- }
278
- ```
279
-
280
- ### PHP 範例
281
-
282
- ```php
283
- <?php
284
-
285
- function generatePassCode(array $parts): string
286
- {
287
- return strtoupper(sha1(implode('', $parts)));
288
- }
289
-
290
- // 建立物流訂單
291
- $passCode = generatePassCode([
292
- $userAccount, // 28229955
293
- $orderNo, // 211210165125
294
- $totalAmount, // 200
295
- $apicode, // 12345678
296
- ]);
297
- // → 4CF47FD844DF64C5D0FBF8DD134708B55ABE208B
298
- ```
299
-
300
- ### Python 範例
301
-
302
- ```python
303
- import hashlib
304
-
305
- def generate_pass_code(*parts: str) -> str:
306
- raw = ''.join(parts)
307
- return hashlib.sha1(raw.encode('utf-8')).hexdigest().upper()
308
-
309
- pass_code = generate_pass_code(user_account, order_no, str(total_amount), apicode)
310
- ```
311
-
312
- ---
313
-
314
- ## 選擇物流服務 (電子地圖)
315
-
316
- ### 端點
317
-
318
- ```
319
- POST /Member/Order/Choselogistics
320
- ```
321
-
322
- ### 通用參數
323
-
324
- | 參數 | 名稱 | 型態 | 長度 | 必填 | 說明 |
325
- |------|------|------|------|------|------|
326
- | `user_account` | 商家主帳號 | string | 10 | ● | |
327
- | `orderno` | 訂單編號 | string | 27 | 否 | 帶入後將原樣回傳 |
328
- | `apicode` | 商家 API 密碼 | string | 30 | ● | 須以 TripleDES 加密 |
329
- | `Logistic_serviceID` | 物流服務 ID | string | 2 | ● | 詳見下表 |
330
- | `returnUrl` | 回傳網址 | string | 200 | ● | 使用者選擇門市後 PayNow 會 POST 至此 |
331
-
332
- ### 各物流的 Logistic_serviceID 對照
333
-
334
- | 服務 | Logistic_serviceID |
335
- |------|-------------------|
336
- | 4 大超商常溫 (依輸入導向對應地圖) | `01` / `03` / `05` / `10` |
337
- | 7-11 大宗物流 | `02` (固定) |
338
- | 7-11 大宗物流 (冷凍) | `22` |
339
- | 7-11 交貨便 (冷凍) | `21` 或 `22` |
340
- | 7-11 海外配送 (店配) | `07` (額外帶 `Country`) |
341
- | 全家大宗物流 | `04` |
342
- | 全家店到店 (冷凍) | `23` |
343
- | 全家大宗 (冷凍) | `24` (額外帶 `Length`/`Wide`/`High`/`Weight`/`StartDate`/`EndDate`) |
344
- | 黑貓店到店 | `46` |
345
-
346
- ### 海外配送專用參數 (Logistic_serviceID=07)
347
-
348
- | 參數 | 必填 | 說明 |
349
- |------|------|------|
350
- | `Country` | ● | `SG`/`MY`/`HK`/`MO`/`TH`,全部國家輸入 `ALL` |
351
-
352
- ### 全家冷凍大宗專用參數 (Logistic_serviceID=24)
353
-
354
- | 參數 | 必填 | 說明 |
355
- |------|------|------|
356
- | `Length` | ● | 長 (cm),依申請材積 S60 (長+寬+高<60) 或 S105 |
357
- | `Wide` | ● | 寬 (cm) |
358
- | `High` | ● | 高 (cm) |
359
- | `Weight` | ● | 重量 (公克),未填請填空字串 |
360
- | `StartDate` | ● | 出貨日起 `yyyy-MM-dd`,未填請填空字串 |
361
- | `EndDate` | ● | 出貨日迄 `yyyy-MM-dd` |
362
- | `Ecplateform` | ● | EC 平台代碼 |
363
-
364
- ### 回傳參數
365
-
366
- | 參數 | 說明 |
367
- |------|------|
368
- | `orderno` | 商家訂單編號 (如有帶入) |
369
- | `service` | 物流服務代碼 |
370
- | `storeid` | 店 ID |
371
- | `storename` | 店名 |
372
- | `storeaddress` | 店址 |
373
- | `ReservedNo` | 保留編號 (僅冷凍 24/23 服務回傳) |
374
- | `ShipDate` | 出貨日期 `yyyy-MM-dd` (僅冷凍 24/23 服務回傳) |
375
-
376
- ### PHP 範例 - 開啟電子地圖 (iframe)
377
-
378
- ```php
379
- <?php
380
-
381
- $apicodeEncrypted = tripleDesEncrypt('12345678', $key, $iv);
382
-
383
- $html = <<<HTML
384
- <form id="map-form" method="post"
385
- action="https://testlogistic.paynow.com.tw/Member/Order/Choselogistics"
386
- target="map-iframe">
387
- <input type="hidden" name="user_account" value="28229955">
388
- <input type="hidden" name="orderno" value="ORDER123">
389
- <input type="hidden" name="apicode" value="{$apicodeEncrypted}">
390
- <input type="hidden" name="Logistic_serviceID" value="02">
391
- <input type="hidden" name="returnUrl" value="https://your-site.com/store_callback">
392
- </form>
393
- <iframe name="map-iframe" width="100%" height="600"></iframe>
394
- <script>document.getElementById('map-form').submit();</script>
395
- HTML;
396
- ```
397
-
398
- ---
399
-
400
- ## 建立物流訂單
401
-
402
- 所有物流產品線共用同一支 API,由 `Logistic_service` 參數判斷實際服務。
403
-
404
- ### 端點
405
-
406
- ```
407
- POST /api/Orderapi/Add_Order
408
- Content-Type: application/x-www-form-urlencoded
409
- ```
410
-
411
- ### Request
412
-
413
- | 參數 | 必填 | 說明 |
414
- |------|------|------|
415
- | `JsonOrder` | ● | `JsonOrder Content` 物件 → JSON 字串 → TripleDES 加密 → URLEncode |
416
-
417
- ### JsonOrder Content (通用欄位)
418
-
419
- | 參數 | 名稱 | 型態 | 長度 | 必填 | 說明 |
420
- |------|------|------|------|------|------|
421
- | `user_account` | 商家主帳號 | string | 10 | ● | |
422
- | `apicode` | 商家 API 密碼 | string | 30 | ● | (整個 JsonOrder 會再次加密) |
423
- | `Logistic_service` | 物流服務代碼 | string | 2 | ● | 見 [物流服務代碼](#物流服務代碼) |
424
- | `OrderNo` | 商家訂單編號 | string | 27 | ● | 限英文與數字 |
425
- | `DeliverMode` | 取貨是否付款 | string | 2 | ● | `01`:取貨付款 `02`:取貨不付款 |
426
- | `TotalAmount` | 總金額 | string | 5 | ● | 正整數,超商不可大於 20,000,黑貓不可大於 100,000 |
427
- | `Remark` | 備註 | string | 200 | ● | 不帶值請填空字串 |
428
- | `Description` | 單號描述 | string | 50 | ● | 黑貓另有商品分類代碼 |
429
- | `EC` | EC 平台 | string | 50 | 否 | |
430
- | `receiver_storeid` | 取件店號 | string | 30 | ● (超商) | 宅配填空字串 |
431
- | `receiver_storename` | 取件店名 | string | 100 | ● (超商) | |
432
- | `return_storeid` | 退件店號 | string | 6 | ● | 不帶值請填空字串 |
433
- | `Receiver_Name` | 收件人姓名 | string | 10~30 | ● | 各物流長度限制不同 |
434
- | `Receiver_Phone` | 收件人手機 | string | 10 | ● | |
435
- | `Receiver_Email` | 收件人 EMAIL | string | 100 | ● | |
436
- | `Receiver_address` | 收件人地址 | string | 150 | ● | |
437
- | `Sender_Name` | 寄件人姓名 | string | 10 | ● | 大宗類型可填空字串自動帶入「立吉富」 |
438
- | `Sender_Phone` | 寄件人手機 | string | 10 | ● | 大宗類型可填空字串自動帶入「0900000000」 |
439
- | `Sender_Email` | 寄件人 EMAIL | string | 100 | ● | |
440
- | `Sender_address` | 寄件人地址 | string | 150 | ● | |
441
- | `PassCode` | 傳遞碼 | string | 40 | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
442
- | `Deadline` | 預定出貨天數 | int | | (大宗) | 1~7,預定出貨日 = 建單日 + Deadline |
443
-
444
- ### Ibon 禁用字元 (7-11 訂單)
445
-
446
- 7-11 大宗、冷凍、海外配送等系列均不可在欄位中包含以下字元:
447
-
448
- ```
449
- ' " % | & ` ^ @ !
450
- . # ( ) * _ + - ; : ,
451
- ```
452
-
453
- ### 通用 Response 欄位
454
-
455
- | 參數 | 說明 |
456
- |------|------|
457
- | `Status` | `S` 成功 / `F` 失敗 |
458
- | `LogisticNumber` | PayNow 物流單號 (主要追蹤鍵) |
459
- | `LogisticService` | 物流服務名稱 |
460
- | `LogisticServiceID` | 物流服務代碼 |
461
- | `paymentno` | 物流商貨運編號 (部分服務在此即回傳) |
462
- | `validationno` | 驗證碼 (7-11 店到店回傳,配合 paymentno 至 Ibon 列印) |
463
- | `orderno` | 商家訂單編號 |
464
- | `ErrorMsg` | 失敗時為錯誤訊息,成功為 `null` |
465
- | `ReturnMsg` | 額外回傳訊息 |
466
-
467
- ---
468
-
469
- ## 7-11 大宗物流
470
-
471
- 服務代碼:`02` / 退貨便:`12` / 文件版本:`711Bulk-API V2.4`
472
-
473
- ### 流程
474
-
475
- 1. `/Member/Order/Choselogistics` 開啟電子地圖選擇取件門市
476
- 2. `/api/Orderapi/Add_Order` 建立物流訂單,取得 `LogisticNumber`
477
- 3. `/api/Bulk711Order/ShipBulk711paymentno` 獲取出貨單號 (`paymentno` / 配送編號)
478
- 4. `/Member/Order/Print711bulkLabel` 列印物流標籤
479
- 5. 於物流標籤上的「門市進貨日 = 建單日 + Deadline」當天進倉
480
-
481
- ### 進貨日規則
482
-
483
- - `Deadline` 必須是 1~7 之間的整數
484
- - 預定出貨日 = 建立物流單日 + Deadline
485
- - 例:建單日 `2021/03/14`,`Deadline=3` → 預定出貨日 `2021/03/17`
486
- - 不可提前到貨,提前到貨會被刷退
487
- - 已超過預定出貨日:
488
- - 未列印過標籤:門市進貨日自動變更為「列印日 + 1 天」
489
- - 已列印過標籤:必須重新取號再列印新標籤
490
-
491
- ### 重新取號規則
492
-
493
- - 必須等物流驗收後且未取貨才能重新取號
494
- - 配對新出貨單號後仍要回到列印 7-11 大宗物流頁面列印新標籤
495
- - 已是貨態 `1000` (上傳中)、`1050` (上傳成功)、`8000` (已取件) 無法重取
496
-
497
- ### 獲取出貨單號
498
-
499
- ```
500
- POST /api/Bulk711Order/ShipBulk711paymentno
501
- ```
502
-
503
- JsonOrder Content:
504
-
505
- ```json
506
- {
507
- "user_account": "28229955",
508
- "apicode": "12345678",
509
- "PassCode": "625B528740B1860CA5392E2CA2B577066596A160",
510
- "ShipList": [
511
- { "LogisticNumber": "MIJA0027B22112100002", "sno": "1" }
512
- ]
513
- }
514
- ```
515
-
516
- > PassCode 此 API 採 `SHA-1(user_account + apicode)`,與一般訂單不同。
517
-
518
- Response (Object Array):
519
-
520
- ```json
521
- [
522
- {
523
- "LogisticNumber": "MIJA0027B22112100002",
524
- "sno": "1",
525
- "paymentno": "82900502030",
526
- "ErrorMsg": null
527
- }
528
- ]
529
- ```
530
-
531
- ### 列印物流單
532
-
533
- ```
534
- POST /Member/Order/Print711bulkLabel
535
- ```
536
-
537
- | 參數 | 必填 | 說明 |
538
- |------|------|------|
539
- | `LogisticNumbers` | ● | `Paynow物流單號_物流單子序號`,多筆以 `,` 分隔,例:`ABCD0017B21903001221_1,ABCD0017B21903001270_1` |
540
-
541
- ### 建立退貨物流單
542
-
543
- ```
544
- PUT /api/Orderapi/ReturnPaymentno
545
- Content-Type: application/x-www-form-urlencoded
546
- ```
547
-
548
- JsonOrder Content:
549
-
550
- ```json
551
- {
552
- "user_account": "28229955",
553
- "apicode": "12345678",
554
- "LogisticNumber": "MIJA0027B22112100002",
555
- "LogisticServiceID": "02",
556
- "PassCode": "24BCF048A550B56D74F9C342DCFA3FA01DBD2AFB"
557
- }
558
- ```
559
-
560
- > 退貨 PassCode 為 `SHA-1(user_account + LogisticNumber + apicode)`。
561
-
562
- Response:
563
-
564
- ```json
565
- {
566
- "Status": "S",
567
- "LogisticNumber": "MIJA0027R42112130001",
568
- "LogisticService": "7-11大宗退貨便",
569
- "LogisticServiceID": "12",
570
- "paymentno": "A47058871088",
571
- "ReturnMsg": "",
572
- "orderno": "MIJA0027B22112100002",
573
- "ErrorMsg": null
574
- }
575
- ```
576
-
577
- 消費者持 `paymentno` 至 Ibon 機台輸入即可列印退貨物流單。
578
-
579
- ### 更新訂單 (尚未出貨)
580
-
581
- ```
582
- PUT /api/Bulk711Order/UpdateB2C711Order
583
- ```
584
-
585
- 可改:`receiver_storeid`、`receiver_storename`、`Receiver_Name`、`Receiver_Phone`。
586
- PassCode 為 `SHA-1(user_account + Orderno + TotalAmount + apicode)`。
587
-
588
- ### 完整建立 PHP 範例
589
-
590
- ```php
591
- <?php
592
-
593
- $payload = [
594
- 'user_account' => '28229955',
595
- 'apicode' => '12345678',
596
- 'Logistic_service' => '02',
597
- 'OrderNo' => '211210165125',
598
- 'DeliverMode' => '02',
599
- 'TotalAmount' => '200',
600
- 'Remark' => '',
601
- 'Description' => 'test',
602
- 'receiver_storeid' => '126616',
603
- 'receiver_storename' => '立行門市',
604
- 'return_storeid' => '',
605
- 'Receiver_Name' => '收件測',
606
- 'Receiver_Phone' => '0912345678',
607
- 'Receiver_Email' => '123@paynow.com.tw',
608
- 'Receiver_address' => '新北市三重區力行路二段158號160號',
609
- 'Sender_Name' => '',
610
- 'Sender_Phone' => '',
611
- 'Sender_Email' => 'test@paynow.com.tw',
612
- 'Sender_address' => '',
613
- 'Deadline' => 1,
614
- ];
615
- $payload['PassCode'] = strtoupper(sha1(
616
- $payload['user_account'] . $payload['OrderNo'] .
617
- $payload['TotalAmount'] . $payload['apicode']
618
- ));
619
-
620
- $json = json_encode($payload, JSON_UNESCAPED_UNICODE);
621
- $encJson = tripleDesEncrypt($json, '123456789070828783123456', '12345678');
622
-
623
- $ch = curl_init();
624
- curl_setopt_array($ch, [
625
- CURLOPT_URL => 'https://testlogistic.paynow.com.tw/api/Orderapi/Add_Order',
626
- CURLOPT_POST => true,
627
- CURLOPT_POSTFIELDS => http_build_query(['JsonOrder' => $encJson]),
628
- CURLOPT_HTTPHEADER => ['partner_token: YOUR_PARTNER_TOKEN'],
629
- CURLOPT_RETURNTRANSFER => true,
630
- ]);
631
- $response = json_decode(curl_exec($ch), true);
632
- curl_close($ch);
633
- ```
634
-
635
- ---
636
-
637
- ## 7-11 冷凍大宗 B2C
638
-
639
- 服務代碼:`22` / 文件版本:`711FreezingBulkB2C V2.4`
640
-
641
- 流程與 7-11 常溫大宗類似,差異:
642
-
643
- - 電子地圖 `Logistic_serviceID=22`
644
- - 建單時 `Logistic_service=22`
645
- - 出貨單號 API:`POST /api/711FreezingB2C/Ship711B2Cpaymentno`
646
- - 列印標籤 API:`POST /Member/Order/Print711FreezingB2CLabel`
647
- - 列印標籤後**隔日進行出貨**,進店日由物流商分配 (不需 `Deadline`)
648
- - 更新訂單 API:`PUT /api/711FreezingB2C/Update711B2COrder`
649
-
650
- 關轉 (門市更新) 必須在收到 `4036` 貨態代碼後 `D+2 上午 10:50` 前處理,逾期則無法關轉。
651
-
652
- 範例 Response:
653
-
654
- ```json
655
- {
656
- "Status": "S",
657
- "LogisticNumber": "MIJA0027F22112140001",
658
- "LogisticService": "7-11大宗物流冷凍",
659
- "LogisticServiceID": "22",
660
- "ReturnMsg": "",
661
- "orderno": "211214141817",
662
- "ErrorMsg": null
663
- }
664
- ```
665
-
666
- ---
667
-
668
- ## 7-11 冷凍店到店 (C2C)
669
-
670
- 服務代碼:`21` / 文件版本:`711FreezingC2C V2.0`
671
-
672
- ### 流程
673
-
674
- 1. 電子地圖選店 (`Logistic_serviceID=22`,注意:建單時改用 `21`)
675
- 2. 建立物流訂單,回傳 `LogisticNumber` + `paymentno` + `validationno`
676
- 3. 列印標籤:`POST /Member/Order/Print711FreezingC2CLabel`
677
- 4. 列印後隔日出貨
678
-
679
- ### 建單範例
680
-
681
- Request:
682
-
683
- ```json
684
- {
685
- "user_account": "28229955",
686
- "apicode": "12345678",
687
- "Logistic_service": "22",
688
- "OrderNo": "211214141817",
689
- "DeliverMode": "02",
690
- "TotalAmount": "200",
691
- "Remark": "",
692
- "Description": "test",
693
- "receiver_storeid": "183413",
694
- "receiver_storename": "八仙門市",
695
- "return_storeid": "",
696
- "Receiver_Name": "收件測",
697
- "Receiver_Phone": "0912345678",
698
- "Receiver_Email": "123@paynow.com.tw",
699
- "Receiver_address": "新北市八里區中華路二段290號292號296號",
700
- "Sender_Name": "寄件測",
701
- "Sender_Phone": "0900000000",
702
- "Sender_Email": "test@paynow.com.tw",
703
- "Sender_address": "",
704
- "PassCode": "08D6038DFDA1AF0412CBA925135DC33F31C928A1"
705
- }
706
- ```
707
-
708
- Response:
709
-
710
- ```json
711
- {
712
- "Status": "S",
713
- "LogisticNumber": "MIJA0027R22203232824",
714
- "LogisticService": "7-11交貨便冷凍",
715
- "LogisticServiceID": "21",
716
- "paymentno": "D8273267",
717
- "validationno": "9066",
718
- "ReturnMsg": "",
719
- "orderno": "220323105411",
720
- "ErrorMsg": null
721
- }
722
- ```
723
-
724
- ### 列印標籤
725
-
726
- ```
727
- POST /Member/Order/Print711FreezingC2CLabel
728
- ```
729
-
730
- | 參數 | 必填 | 說明 |
731
- |------|------|------|
732
- | `orderNumberStr` | ● | PayNow 物流單號,多筆以 `,` 分隔 |
733
- | `user_account` | ● | |
734
-
735
- ### 關轉時限
736
-
737
- 收到 `7101`、`7104`、`7201`、`7204` 貨態代碼後 `D+7` 內必須打 `/api/Orderapi/Put` 進行關轉,逾期失效。
738
-
739
- ---
740
-
741
- ## 7-11 海外配送
742
-
743
- 服務代碼:`07` (店配) / `08` (宅配) / 文件版本:`711OverSea V2.7`
744
-
745
- ### 適用國家與限制
746
-
747
- | 國家 | 代碼 | 取貨天數 | 重量/材積限制 | 進口免稅額 | 當地宅配 |
748
- |------|------|----------|----------------|-------------|-----------|
749
- | 香港 | `HK` | 3 天 | 店配 30×50×30 cm 5kg;宅配 85×85×85 cm 20kg | 無關稅 | 1kg=27HKD,2-5kg=37HKD |
750
- | 新加坡 | `SG` | 2 天 | 店配 長+寬+高 80cm 5kg;宅配 85×85×85 cm 20kg | SGD 400 | 首重 7SGD/kg、續重 3SGD/kg |
751
- | 馬來西亞 | `MY` | 4 天 | 店配 40×40×40 cm 4kg;宅配 85×85×85 cm 20kg | MYR 500 | 西馬首重 9MYR/kg;東馬首重 23MYR/kg |
752
- | 澳門 | `MO` | 24 小時內 | 店配 45×31×35 cm 20kg;宅配 120×80×70 cm 20kg | — | 同區一件 10 澳幣,跨區 2kg 內 22 澳幣 |
753
- | 泰國 | `TH` | 3 天 | 店配 60×60×60 cm 5kg;宅配 85×85×85 cm 20kg | 含稅 | 首重 60 NTD/kg、續重 15 NTD/kg |
754
- | 越南 | `VN` | — | 宅配 3kg | 含稅 | — |
755
- | 美國 | `US` | — | 宅配 100×80×70 cm 20kg | USD 800 | — |
756
-
757
- 材積計算:
758
-
759
- - 港/新/馬/澳/泰/越南:`長 × 寬 × 高 / 6000`
760
- - 美國/其他國家:`長 × 寬 × 高 / 5000`
761
-
762
- > 重量與材積取較高值計價。中國目前無法配送 (運費分上海/江蘇/浙江/廣東/深圳/福建/廈門 `FeeMode=0` 與其他省 `FeeMode=1`)。
763
-
764
- ### 禁運物品 (摘錄)
765
-
766
- - 香港:活生動物、無煙菸草製品、易燃易爆物質、香水、鋰電池等
767
- - 新加坡:電子香菸、電子菸斗、電子雪茄菸
768
- - 馬來西亞:肉類、海鮮、奶製品、燕窩、菲律賓/印尼水果、鋰電池、武器等
769
-
770
- 實際規範以各國海關為準。
771
-
772
- ### 流程
773
-
774
- 1. (店配) 電子地圖 (`Logistic_serviceID=07`、`Country=ALL`/`HK`/`SG` 等) 選店
775
- 2. `/api/Orderapi/Add_Order` 建單 (`Logistic_service=07` 或 `08`)
776
- 3. `GET /api/OverSeas711Order` 列印標籤 (5 日內限制)
777
- 4. 訂單成立後 5 日內完成寄件 (含當日)
778
-
779
- ### 海外建單專用欄位
780
-
781
- | 參數 | 必填 | 說明 |
782
- |------|------|------|
783
- | `ReceiverCountry` | ● | 國家代碼 (英文),依「查詢國家代碼 API」CountryId |
784
- | `ReceiverCode` | ● | 收件人宅配郵編,香港帶 `00000`、澳門帶 `999078`,不可含特殊符號 |
785
- | `Weight` | ● | 重量 (kg),可帶小數點 |
786
- | `Length` | ● | 外箱長 (cm) |
787
- | `Width` | ● | 外箱寬 (cm) |
788
- | `Height` | ● | 外箱高 (cm) |
789
- | `Description` | ● | 包裹英文名稱 (僅英文/數字) |
790
-
791
- `Receiver_Phone` 國碼規則:
792
-
793
- - 香港:`852` + 純數字手機
794
- - 澳門:`853` + 純數字手機
795
- - 泰國店取:純 10 位數字、`0` 開頭、不含國碼
796
-
797
- `Receiver_address`:
798
-
799
- - 新馬/中港澳:可中文,長度 ≤ 150
800
- - 其他國家:必填英文,長度 ≤ 135 byte
801
-
802
- ### 列印標籤
803
-
804
- ```
805
- GET /api/OverSeas711Order?orderNumberStr=ORDER1,ORDER2,...
806
- ```
807
-
808
- | 參數 | 必填 | 說明 |
809
- |------|------|------|
810
- | `orderNumberStr` | ● | 商家訂單編號,逗號分隔,一次最多 100 筆 |
811
-
812
- 回傳格式:
813
-
814
- ```
815
- S,https://... (成功,導向列印畫面或下載 Excel)
816
- F,錯誤訊息
817
- ```
818
-
819
- > 多筆列印會下載 Excel,錯誤訂單放在 `NoShipNo` 工作表。
820
-
821
- ### 查詢國家代碼
822
-
823
- ```
824
- POST /api/OverSeas711Order/SelCountryID
825
- ```
826
-
827
- JsonOrder Content:
828
-
829
- ```json
830
- { "user_account": "28229955", "apicode": "12345678" }
831
- ```
832
-
833
- Response 範例:
834
-
835
- ```json
836
- {
837
- "Status": "S",
838
- "ErrorMsg": "",
839
- "Detail": [
840
- { "CountryId": "AD", "ChineseName": "安道爾", "EnglishName": "Andorra" },
841
- { "CountryId": "AF", "ChineseName": "阿富汗", "EnglishName": "Afghanistan" }
842
- ]
843
- }
844
- ```
845
-
846
- ### 查詢物流重量費用
847
-
848
- ```
849
- POST /api/Orderapi/SelWeightChart
850
- ```
851
-
852
- JsonOrder Content:
853
-
854
- ```json
855
- {
856
- "user_account": "28229955",
857
- "apicode": "12345678",
858
- "LogisticServiceID": "08",
859
- "LogisticServiceID2": "",
860
- "CountryID": "US"
861
- }
862
- ```
863
-
864
- Response Detail:
865
-
866
- | 欄位 | 說明 |
867
- |------|------|
868
- | `Country` | 國家代碼 |
869
- | `Weight` | 包裹重量 (kg),例:`0.5KG` |
870
- | `Cost` | 費用 (decimal(8,2)),不含 5% 營業稅 |
871
- | `FeeMode` | `0`:正常 / `1`:偏遠 |
872
- | `Pay` | `0`:一般 `1`:經濟 `2`:空運 `3`:運費到付 `4`:其他 |
873
- | `DeliveryMethod` | `0`:店配 `1`:宅配 |
874
-
875
- ### 查詢寄送包裹費用明細
876
-
877
- 兩種查法 (擇一):
878
-
879
- ```
880
- POST /api/OverSeas711Order/SelBillDetail (依訂單)
881
- POST /api/OverSeas711Order/SelBillDetailDate (依日期 yyyy-MM-dd)
882
- ```
883
-
884
- 每週四更新帳務,可查詢至上週整週帳務 (含結束日期當日)。
885
-
886
- ---
887
-
888
- ## 全家大宗物流
889
-
890
- 服務代碼:`04` / 文件版本:`FamilyBulk V2.4`
891
-
892
- 流程與 7-11 大宗類似,但全家大宗:
893
-
894
- - 建單時 `Logistic_service=04`、`Deadline` 為 1~7
895
- - `Sender_Name`、`Sender_Phone` 可填空字串自動帶入「立吉富」/「0900000000」
896
- - 列印 API:`/api/Order711` 之外另有 `/api/OrderFamiC2C` (依產品線)
897
-
898
- > 全家大宗的後續取出貨單號流程與 7-11 大宗一致,請依官方 SDK 接續。
899
-
900
- ---
901
-
902
- ## 全家冷凍大宗 B2C
903
-
904
- 服務代碼:`24` / 文件版本:`FamilyFreezingBulkB2C V2.6`
905
-
906
- ### 與其他物流關鍵差異
907
-
908
- 1. **店鋪保留機制**:選店後 PayNow 會給予 3 小時暫留,3 小時內必須打 `/api/FamiFreezingB2C/UpSpaceConfirm` 確認,否則取消
909
- 2. 訂單需在電子地圖回傳的 `ShipDate` 前一天建立完成並列印
910
- 3. 重選店鋪:原訂單若已確認過店鋪空間,需先取消才能重選
911
- 4. 電子地圖必須帶入材積 `Length`/`Wide`/`High`/`Weight` 與出貨日 `StartDate`/`EndDate`
912
-
913
- ### 店鋪空間保留 / 取消
914
-
915
- ```
916
- POST /api/FamiFreezingB2C/UpSpaceConfirm
917
- ```
918
-
919
- 使用情境:
920
-
921
- - 新增訂單前需先保留空間才可成功建單
922
- - 重選店舖若已保留過需先取消再保留新編號
923
- - 最終未出貨訂單需取消保留
924
-
925
- 電子地圖 (Logistic_serviceID=24) 將回傳 `ReservedNo` 與 `ShipDate`,後續建單必須帶入 `ReservedNo`。
926
-
927
- ### 材積申請類別
928
-
929
- | 類別 | 限制 |
930
- |------|------|
931
- | `S60` | 長+寬+高 < 60 cm |
932
- | `S105` | 長+寬+高 < 105 cm |
933
-
934
- ---
935
-
936
- ## 全家冷凍店到店 (C2C)
937
-
938
- 服務代碼:`23` / 文件版本:`FamilyFreezingC2C V2.2`
939
-
940
- ### 流程
941
-
942
- 1. 電子地圖 (`Logistic_serviceID=23`) 選店,回傳 `ReservedNo` + `ShipDate`
943
- 2. 建單帶入 `ReservedNo`、`Logistic_service=23`
944
- 3. 列印全家店到店冷凍物流單
945
- 4. 依電子地圖回傳的 `ShipDate` 進行出貨
946
- 5. 寄貨外箱須於全家購買 (My FamiPort APP 預購寄件專用紙箱)
947
-
948
- ### 建單必填差異
949
-
950
- `ReservedNo` 為必填,其他欄位與通用建單一致。回傳會包含 `paymentno`:
951
-
952
- ```json
953
- {
954
- "Status": "S",
955
- "LogisticNumber": "...",
956
- "LogisticService": "全家店到店冷凍",
957
- "LogisticServiceID": "23",
958
- "paymentno": "...",
959
- "ErrorMsg": null
960
- }
961
- ```
962
-
963
- ---
964
-
965
- ## 四大超商常溫 C2C
966
-
967
- 服務代碼:`01` (7-11 交貨便) / `03` (全家店到店) / `05` (萊爾富店到店) / `10` (OK 店到店)
968
- 文件版本:`SuperMarketC2C V2.5`
969
-
970
- ### 寄件期限
971
-
972
- | 超商 | 寄件期限 |
973
- |------|----------|
974
- | 7-11 / 全家 | 7 天 |
975
- | 萊爾富 | 5 天 |
976
- | OK | 15 天 |
977
-
978
- ### 收件人姓名長度限制
979
-
980
- | 物流服務 | 長度上限 |
981
- |----------|----------|
982
- | 7-11 交貨便 | 10 |
983
- | 全家店到店 | 30 |
984
- | 萊爾富店到店 | 20 |
985
- | OK 店到店 | 10 |
986
-
987
- ### 列印標籤端點
988
-
989
- ```
990
- GET /api/Order711 (7-11)
991
- GET /api/OrderFamiC2C (全家)
992
- GET /api/OrderHiLife (萊爾富)
993
- GET /api/OKC2C (OK)
994
- ```
995
-
996
- | 參數 | 必填 | 說明 |
997
- |------|------|------|
998
- | `orderNumberStr` | ● | 商家訂單編號 (`OrderNo`),逗號分隔,一次最多 100 筆 |
999
- | `user_account` | ● | |
1000
-
1001
- 回傳:`S,網址` 或 `F,錯誤訊息`。
1002
-
1003
- ### 重新取號特別規則
1004
-
1005
- - **萊爾富需在訂單成立 30 分鐘後才能進行重新取號**
1006
- - 7-11、全家、OK 在訂單成立後即可重取
1007
-
1008
- ### 全家 C2C 店號轉換
1009
-
1010
- ```
1011
- GET /api/OrderFamiC2C/GetFamiStoreID?storeId=017206&IDtype=1
1012
- ```
1013
-
1014
- | 參數 | 必填 | 說明 |
1015
- |------|------|------|
1016
- | `storeId` | ● | 店號 (6 碼) |
1017
- | `IDtype` | ● | `1`:轉成現行店號 / `2`:轉成原始店號 |
1018
-
1019
- Response:
1020
-
1021
- ```json
1022
- { "storeId": "017206", "IDtype": "1", "Error": "" }
1023
- ```
1024
-
1025
- ### 7-11 交貨便建單回傳範例
1026
-
1027
- ```json
1028
- {
1029
- "Status": "S",
1030
- "LogisticNumber": "MIJA0027C22112026083",
1031
- "LogisticService": "7-11交貨便",
1032
- "LogisticServiceID": "01",
1033
- "paymentno": "L9991156",
1034
- "validationno": "0497",
1035
- "ReturnMsg": "",
1036
- "orderno": "211202115804",
1037
- "ErrorMsg": null
1038
- }
1039
- ```
1040
-
1041
- `paymentno` + `validationno` 可至 7-11 Ibon 機台輸入列印。
1042
-
1043
- ---
1044
-
1045
- ## 黑貓宅配
1046
-
1047
- 服務代碼:`06` (黑貓宅急便) / `36` (黑貓宅急便 PayNow) / 文件版本:`BlackCat-Home-Delivery V2.1`
1048
-
1049
- ### 流程
1050
-
1051
- 1. 將訂單資料組成 JSON 字串 POST 到 `/api/Orderapi/Add_Order`
1052
- 2. 成功後到 `/Member/Order/PrintBlackCatLabel` 列印標籤
1053
- 3. 出貨日將商品準備好,黑貓上門取貨
1054
-
1055
- ### 黑貓宅配專用欄位
1056
-
1057
- | 參數 | 必填 | 說明 |
1058
- |------|------|------|
1059
- | `Description` | 否 | 商品類別代碼 (見下表),未填預設 `0015` |
1060
- | `DeliverMode` | ● | `01`:取貨付款 `02`:取貨不付款 (保險單須為 `02`) |
1061
- | `Logistic_service` | ● | `06`:黑貓宅急便 / `36`:黑貓宅急便 (PayNow 自動保險) |
1062
- | `TotalAmount` | ● | 不可大於 100,000 |
1063
- | `Deadline` | ● | 0~6;當日出貨帶 `0`,過 16:00 則出貨日為明日;週日/連假順延 |
1064
- | `Length` / `Wide` / `High` | ● | 長+寬+高 ≤ 150 cm |
1065
- | `Weight` | ● | 商品總重量 (kg) ≤ 20 kg |
1066
- | `Sender_Tel` | 否 | 寄件人市話 |
1067
- | `Receiver_Tel` | 否 | 收件人市話 |
1068
- | `ExpectDeliverTime` | 否 | `1`:13:00 前 / `2`:14:00-18:00 / `4`:不固定 (預設 `4`) |
1069
- | `ExpectDeliverDate` | 否 | `yyyy-MM-dd`,最大為建單日 + 6 天,未帶自動為出貨日 D+1 |
1070
- | `DeliveryType` | ● | `0001`:常溫 `0002`:冷藏 `0003`:冷凍 |
1071
- | `IsInsurance` | 否 | bool;有保險的單填 `true`,預設 `false` |
1072
-
1073
- > 服務代號 `36` 的單**無須帶入 `IsInsurance`**,總金額超過 20,000 會自動投保 (保額為商品金額)。
1074
-
1075
- ### Description 商品類別代碼 (黑貓專用)
1076
-
1077
- | 代碼 | 類別 |
1078
- |------|------|
1079
- | `0001` | 一般食品 |
1080
- | `0002` | 名特產/甜產印單 |
1081
- | `0003` | 酒/油/醋/醬 |
1082
- | `0004` | 穀物蔬果 |
1083
- | `0005` | 水產/肉品 |
1084
- | `0006` | 3C |
1085
- | `0007` | 家電 |
1086
- | `0008` | 服飾配件 |
1087
- | `0009` | 生活用品 |
1088
- | `0010` | 美容彩妝 |
1089
- | `0011` | 保健食品 |
1090
- | `0012` | 醫療相關用品 |
1091
- | `0013` | 寵物用品飼料 |
1092
- | `0014` | 印刷品 |
1093
- | `0015` | 其他 (預設) |
1094
-
1095
- ### 建單範例
1096
-
1097
- ```json
1098
- {
1099
- "DeliverMode": "01",
1100
- "Description": "0001",
1101
- "Logistic_service": "06",
1102
- "OrderNo": "123456789",
1103
- "Receiver_address": "台北市北投區承德路六段2號",
1104
- "Receiver_Email": "12345678@gmail.com",
1105
- "Receiver_Name": "王O明",
1106
- "Receiver_Phone": "0912345678",
1107
- "Remark": "備註",
1108
- "Sender_address": "台北市中山區松江路207號9樓",
1109
- "Sender_Email": "12345678@gmail.com",
1110
- "Sender_Name": "李O富",
1111
- "Sender_Phone": "0912345678",
1112
- "Sender_Tel": "0225215088",
1113
- "Receiver_Tel": "0225215088",
1114
- "apicode": "12345678",
1115
- "TotalAmount": "100",
1116
- "user_account": "28229955",
1117
- "DeliveryType": "0001",
1118
- "PassCode": "2FC3805A8BEEC525F2EDF74B75E7FCE83C980856",
1119
- "Deadline": "1",
1120
- "Length": "30",
1121
- "Wide": "30",
1122
- "High": "30",
1123
- "Weight": "5"
1124
- }
1125
- ```
1126
-
1127
- Response:
1128
-
1129
- ```json
1130
- {
1131
- "Status": "S",
1132
- "LogisticNumber": "ABCD123456",
1133
- "LogisticService": "黑貓宅急便",
1134
- "LogisticServiceID": "06",
1135
- "paymentno": "12345678",
1136
- "ReturnMsg": "",
1137
- "orderno": "12345678",
1138
- "ErrorMsg": ""
1139
- }
1140
- ```
1141
-
1142
- ### 列印黑貓宅急便標籤
1143
-
1144
- ```
1145
- POST /Member/Order/PrintBlackCatLabel
1146
- ```
1147
-
1148
- | 參數 | 必填 | 說明 |
1149
- |------|------|------|
1150
- | `LogisticNumbers` | ● | `物流單號_序號`,多筆以 `,` 分隔 |
1151
-
1152
- ---
1153
-
1154
- ## 黑貓店到店
1155
-
1156
- 服務代碼:`46` / 文件版本:`BlackCat-Home-Delivery V1.1`
1157
-
1158
- ### 流程
1159
-
1160
- 1. 選擇物流服務 (`Logistic_serviceID=46`) 取得門市資料
1161
- 2. 完善訂單資料後組成 JSON 字串 POST 到 `/api/Orderapi/Add_Order`
1162
- 3. 成功後到列印黑貓店到店標籤
1163
- 4. 將商品準備好打電話給黑貓上門取貨開始配送流程
1164
-
1165
- ### 與宅配的差異
1166
-
1167
- | 項目 | 黑貓宅配 (06/36) | 黑貓店到店 (46) |
1168
- |------|-----------------|-----------------|
1169
- | 收件方式 | 收件人地址 | 取件門市 (`receiver_storeid`/`receiver_storename`) |
1170
- | `TotalAmount` 上限 | 100,000 | 20,000 |
1171
- | 長+寬+高上限 | ≤ 150 cm | ≤ 105 cm |
1172
- | `Sender_Phone`/`Sender_Tel` | 可填空字串自動帶 `0900000000` | 需明確填值 |
1173
- | `Description` | 商品類別代碼 | 自由文字 |
1174
-
1175
- ### 必填欄位
1176
-
1177
- `Logistic_service=46`、`receiver_storeid`、`receiver_storename`、`return_storeid` (可填空字串)、`Length`/`Wide`/`High` (≤ 105 cm)、`DeliveryType` (常溫/冷藏/冷凍)。
1178
-
1179
- ---
1180
-
1181
- ## 查詢物流單
1182
-
1183
- ### 依 PayNow 物流單號
1184
-
1185
- ```
1186
- GET /api/Orderapi/Get_Order_Info?LogisticNumber=...&sno=1
1187
- ```
1188
-
1189
- ### 依商家訂單編號
1190
-
1191
- ```
1192
- GET /api/Orderapi/Get_Order_Info_orderno?orderno=...&user_account=...&sno=1
1193
- ```
1194
-
1195
- ### Response
1196
-
1197
- | 參數 | 說明 |
1198
- |------|------|
1199
- | `LogisticNumber` | PayNow 物流單號 |
1200
- | `sno` | 物流單序號 (固定 1) |
1201
- | `orderno` | 商家訂單編號 |
1202
- | `Logistic_Serviece` | 物流服務代碼 (注意官方拼字) |
1203
- | `Status` | `0`:成立中 `1`:無效訂單 |
1204
- | `Delivery_Status` | 流程狀態文字描述 |
1205
- | `PayNowLogisticCode` | 4 位數 PayNow 物流貨態代碼 |
1206
- | `Detail_Status_Description` | 貨態詳細描述 |
1207
- | `paymentno` | 物流商託運單號 |
1208
- | `validationno` | 驗證碼 (7-11 店到店類有值) |
1209
- | `ErrorMsg` | 錯誤訊息,成功為 `null` |
1210
-
1211
- ### 範例
1212
-
1213
- ```json
1214
- {
1215
- "LogisticNumber": "MIJA0027R22203232824",
1216
- "orderno": "220323105411",
1217
- "Logistic_Serviece": "21",
1218
- "Status": "0",
1219
- "Delivery_Status": "等待寄件",
1220
- "PayNowLogisticCode": "0000",
1221
- "Detail_Status_Description": "訂單已成立 等待出貨",
1222
- "sno": "1",
1223
- "ErrorMsg": null,
1224
- "paymentno": "D8273267",
1225
- "validationno": "9066"
1226
- }
1227
- ```
1228
-
1229
- ---
1230
-
1231
- ## 取消物流單
1232
-
1233
- ```
1234
- DELETE /api/Orderapi/CancelOrder
1235
- Content-Type: application/x-www-form-urlencoded
1236
- ```
1237
-
1238
- | 參數 | 必填 | 說明 |
1239
- |------|------|------|
1240
- | `LogisticNumber` | ● | PayNow 物流單號 |
1241
- | `sno` | ● | 物流單序號 (固定 1) |
1242
- | `PassCode` | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
1243
-
1244
- ### Response (純字串)
1245
-
1246
- ```
1247
- S,訂單已取消
1248
- F,訂單取消失敗 失敗原因: <原因>
1249
- ```
1250
-
1251
- ### 限制
1252
-
1253
- - 出貨中的大宗訂單無法使用此 API
1254
-
1255
- ---
1256
-
1257
- ## 重新取號
1258
-
1259
- ```
1260
- POST /api/Orderapi/ReNewOrder
1261
- Content-Type: application/x-www-form-urlencoded
1262
- ```
1263
-
1264
- JsonOrder Content:
1265
-
1266
- | 參數 | 必填 | 說明 |
1267
- |------|------|------|
1268
- | `user_account` | ● | |
1269
- | `LogisticNumber` | ● | 原 PayNow 物流單號 |
1270
- | `sno` | ● | 物流單序號 |
1271
- | `OrderNo` | ● | 商家原始訂單編號 |
1272
- | `TotalAmount` | ● | 訂單總金額 |
1273
- | `apicode` | ● | |
1274
- | `PassCode` | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
1275
-
1276
- ### Response
1277
-
1278
- ```json
1279
- {
1280
- "Status": "S",
1281
- "LogisticNumber": "MIJA0027B22112100002",
1282
- "OrderNo": "211210165125",
1283
- "paynoworderno": "211210165125",
1284
- "sno": "1",
1285
- "paymentno": "82900502031",
1286
- "validationno": "1600",
1287
- "Status": "S",
1288
- "ErrorMsg": null
1289
- }
1290
- ```
1291
-
1292
- > `paynoworderno` 為**新的訂單編號**:超過寄件期限 (7-11=5 天 / 全家=當天 / 萊爾富=5 天) 重取會產生新編號,請以 `paynoworderno` 作為後續批次列印與查詢的訂單編號。
1293
-
1294
- ### 各物流重取規則
1295
-
1296
- | 物流 | 規則 |
1297
- |------|------|
1298
- | 7-11 大宗 (`02`) | 物流驗收後且未取貨;貨態 `1000`/`1050`/`8000` 無法重取 |
1299
- | 7-11 冷凍大宗 (`22`) | 同上 |
1300
- | 萊爾富店到店 (`05`) | 訂單成立 30 分鐘後才能重取 |
1301
- | 全家店到店 (`03`) | 規定日期 = 物流單成立日 + 0 天 (即當天) |
1302
- | 7-11 海外配送 | 已獲取出貨單號且訂單成立中、買家尚未取貨 |
1303
-
1304
- ---
1305
-
1306
- ## 門市更新 (關轉)
1307
-
1308
- ```
1309
- PUT /api/Orderapi/Put
1310
- Content-Type: application/x-www-form-urlencoded
1311
- ```
1312
-
1313
- 「關轉」是指進行出貨後因各種狀況 (門市關店、轉店等) 無法將包裹配達指定門市,需請商家/消費者更換取件門市。
1314
-
1315
- ### 各物流關轉時限
1316
-
1317
- | 物流 | 觸發貨態代碼 | 關轉時限 |
1318
- |------|-------------|---------|
1319
- | 7-11 大宗 (`02`) | `4036` | D+2 上午 11:20 前 |
1320
- | 7-11 冷凍大宗 (`22`) | `4036` | D+2 上午 10:50 前 |
1321
- | 7-11 冷凍 C2C (`21`) | `7101`/`7104`/`7201`/`7204` | D+7 內 |
1322
- | 4 大超商 C2C | `7101`/`7104`/`7201`/`7204` | D+7 內 |
1323
-
1324
- ### Request
1325
-
1326
- | 參數 | 必填 | 說明 |
1327
- |------|------|------|
1328
- | `UpdateOrder` | ● | 物流單資料 (JSON 字串) |
1329
- | `LogisticNumber` | ● | PayNow 物流單號 |
1330
- | `sno` | ● | 物流單序號 (固定 1) |
1331
- | `ChangeType` | ● | `01`:取件門市更新 / `02`:退件門市更新 |
1332
- | `NewStoreId` | ● | 新門市店號 |
1333
- | `NewStoreName` | ● | 新門市名稱 |
1334
- | `PassCode` | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
1335
-
1336
- 範例:
1337
-
1338
- ```json
1339
- {
1340
- "LogisticNumber": "MIJA0027B22112100002",
1341
- "sno": "1",
1342
- "ChangeType": "01",
1343
- "NewStoreId": "863698",
1344
- "NewStoreName": "豫銘門市",
1345
- "PassCode": "4CF47FD844DF64C5D0FBF8DD134708B55ABE208B"
1346
- }
1347
- ```
1348
-
1349
- ### Response (純字串)
1350
-
1351
- ```
1352
- S,更新成功
1353
- F,失敗原因: <原因>
1354
- ```
1355
-
1356
- ---
1357
-
1358
- ## 物流貨態回傳 (Callback)
1359
-
1360
- PayNow 在物流貨態變更時,會以 HTTP POST 將最新狀態送至商家事先設定的回傳網址。
1361
-
1362
- ### Request 參數
1363
-
1364
- | 參數 | 名稱 | 型態 | 長度 | 必填 | 說明 |
1365
- |------|------|------|------|------|------|
1366
- | `orderno` | 商家自訂編號 | string | 30 | ● | 重取後可能與原始不同 |
1367
- | `OriginOrderno` | 商家原始自訂單號 | string | 27 | ● | |
1368
- | `PayNowLogisticCode` | 物流代碼 | string | 4 | ● | 4 碼,例:`5000`/`8000` |
1369
- | `Detail_Status_Description` | 物流狀態描述 | string | | ● | |
1370
- | `paymentno` | 物流商託運單號 | string | | ● | |
1371
- | `StoreDate` | 到店日期 | string | | 否 | 若代碼為 `5000`/`5001` 則填實際到店日期 |
1372
- | `StoreTime` | 到店時間 | string | | 否 | 同上 |
1373
-
1374
- ### 處理範例 (PHP)
1375
-
1376
- ```php
1377
- <?php
1378
-
1379
- // 接收 PayNow 物流回傳
1380
- $logisticCode = $_POST['PayNowLogisticCode'] ?? '';
1381
- $orderNo = $_POST['OriginOrderno'] ?? '';
1382
-
1383
- switch ($logisticCode) {
1384
- case '0000':
1385
- updateOrderStatus($orderNo, 'pending'); // 訂單已成立 等待出貨
1386
- break;
1387
- case '5000':
1388
- updateOrderStatus($orderNo, 'arrived_at_store'); // 取件門市配達
1389
- break;
1390
- case '5001':
1391
- updateOrderStatus($orderNo, 'arrived_at_return'); // 退件門市配達
1392
- break;
1393
- case '8000':
1394
- updateOrderStatus($orderNo, 'picked_up'); // 買家已取件
1395
- break;
1396
- case '8001':
1397
- updateOrderStatus($orderNo, 'returned'); // 退貨成功
1398
- break;
1399
- case '4036':
1400
- notifyMerchantStoreClosure($orderNo); // 門市關轉,需更新門市
1401
- break;
1402
- case '9411':
1403
- notifyMerchantStuck($orderNo); // 貨態停滯
1404
- break;
1405
- default:
1406
- logUnknownStatus($orderNo, $logisticCode);
1407
- }
1408
-
1409
- http_response_code(200);
1410
- echo 'OK';
1411
- ```
1412
-
1413
- > 注意:PayNow 文件未明確規範 callback 的應答格式,建議回傳 HTTP 200 + 任意文字,並由商家自行做 PassCode 比對 (官方文件未要求 callback 帶 PassCode)。
1414
-
1415
- ---
1416
-
1417
- ## 貨態代碼對照表
1418
-
1419
- PayNow 物流貨態代碼為 4 位數字,依物流商有不同涵義;以下為主要代碼匯總。
1420
-
1421
- ### 共通代碼
1422
-
1423
- | 代碼 | 說明 |
1424
- |------|------|
1425
- | `0000` | 訂單已成立 等待出貨 |
1426
- | `0001` | 訂單已成立 等待退貨 |
1427
- | `0101` | 商品已到寄件門市 |
1428
- | `0102` | 門市已更新寄件中 |
1429
- | `0103` | 門市已更新退件中 |
1430
- | `4000` | 進驗成功 |
1431
- | `5000` | 取件門市配達 |
1432
- | `5001` | 退件門市配達 |
1433
- | `8000` | 買家已取件 |
1434
- | `8001` | 退貨成功 |
1435
- | `8100` | 賣家已取件 |
1436
- | `9411` | 貨態停滯 |
1437
-
1438
- ### 7-11 大宗物流 (`02`)
1439
-
1440
- | 代碼 | 說明 |
1441
- |------|------|
1442
- | `1000` | 訂單檔案上傳中 |
1443
- | `1050` | 物流訂單上傳成功 |
1444
- | `1071`~`1075` | XML/檔案異常 (請聯繫系統商) |
1445
- | `1080` | 門市店號轉換成功 |
1446
- | `2001`~`2017` | XML 內容、出貨單號、出貨日期格式問題 |
1447
- | `2107` | 母廠商不存在 |
1448
- | `2108` | 子廠商不存在 |
1449
- | `2110` | 門市已關轉 |
1450
- | `2118` | 代收金超過上限 |
1451
- | `2120` | XML 格式不符合規定 |
1452
- | `3001` | 物流作業驗收中 |
1453
- | `3002` | 門市已更新店號 |
1454
- | `3101` | 無此門市將進行退貨 |
1455
- | `3102` | 六、日門市不配送 |
1456
- | `3103` | 門市關轉店 |
1457
- | `3104` | 門市尚未開店 |
1458
- | `3105` | 曾經重複出貨,無法出貨 |
1459
- | `4003` | 商品捆包 |
1460
- | `4004` | 商品外帶透明 |
1461
- | `4005` | 商品多標籤 |
1462
- | `4031` | 商品破損退貨中 |
1463
- | `4032` | 商品超才退貨中 |
1464
- | `4033` | 違禁品進行罰款退貨中 |
1465
- | `4034` | 同一個訂單兩包商品資料重複 |
1466
- | `4035` | 已過門市進貨日 |
1467
- | `4036` | 門市關轉請更新門市 (D+2 11:20 前關轉) |
1468
- | `4037` | 條碼規格錯誤 |
1469
- | `4038` | 條碼無法判讀 |
1470
- | `4039` | 無標籤 |
1471
- | `4060` | 物流中心理貨中 |
1472
- | `4061` | 商品遺失 |
1473
- | `4062` | 門市不配送 |
1474
- | `4063` | 包裹異常不配送 |
1475
- | `4099` | 不正常到貨,商品提早到達物流中心 |
1476
- | `5011`~`5017` | 配送異常 (作業/車輛/天候/道路/門市) |
1477
- | `5102` | 管制品取件門市配達 |
1478
- | `5201` | EC 收退 |
1479
- | `5202` | 交貨便收件 |
1480
- | `5203` | 退貨便收件 |
1481
- | `5303` | 取件遺失進行賠償作業 |
1482
- | `6001` | 第一次開退 |
1483
- | `7001` | 正常一退 |
1484
- | `7002` | 正常二退 |
1485
- | `7011`~`7022` | 退貨原因細項 (商品瑕疵/門市/廠商/消費者) |
1486
- | `8003`~`8005` | 商品異常 (捆包/外帶透明/多標籤) |
1487
- | `8011`~`8022` | 退貨成功原因細項 |
1488
- | `8031`~`8039` | 商品異常退貨 (破損/超才/違禁/重複/條碼) |
1489
- | `8099` | 不正常到貨,商品提早到達物流中心 |
1490
- | `8110` | 賣家已取件-代收金額錯誤 |
1491
-
1492
- ### 7-11 大宗退貨便 (`12`)
1493
-
1494
- | 代碼 | 說明 |
1495
- |------|------|
1496
- | `0001` | 訂單已成立 等待退貨 |
1497
- | `0101` | 商品已到寄件門市 |
1498
- | `7001` | 正常一退 |
1499
- | `8001` | 退貨成功 |
1500
-
1501
- ### 7-11 冷凍 C2C (`21`)
1502
-
1503
- | 代碼 | 說明 |
1504
- |------|------|
1505
- | `0` | 訂單已成立 等待寄件中 |
1506
- | `101` | 商品已到寄件門市 |
1507
- | `102` | 門市已更新寄件中 |
1508
- | `103` | 門市已更新退件中 |
1509
- | `4034` | 同一個訂單兩包商品資料重複 |
1510
- | `4060` | 物流中心理貨中 |
1511
- | `4063` | 包裹異常不配送 |
1512
- | `4064` | 取消寄件再次寄送 (直接轉 C 店) |
1513
- | `4065` | 提早轉 C 店 - 廠商因素 |
1514
- | `4066` | 提早轉 C 店 - 超商因素 |
1515
- | `4075` | 包裹異常進入判賠程序 |
1516
- | `4076` | 包裹已送達物流中心,即將配送至指定門市 |
1517
- | `4077` | 無退件門市資料 |
1518
- | `4078` | 包裹等待配送中 |
1519
- | `4079` | 包裹進行配送中 |
1520
- | `5018` | 寄件貨態異常協尋中 |
1521
- | `5019` | 取件包裹異常協尋中 |
1522
- | `5021` | 物流中心暫報缺 |
1523
- | `5022` | 驗收前包裹異常 |
1524
- | `5301` | 取消寄件 |
1525
- | `5302` | 寄件遺失進行賠償程序 |
1526
- | `6002` | 待退貨請盡速取件 |
1527
- | `7101` | 取件門市關轉店 |
1528
- | `7102` | 取件門市舊店號更新 |
1529
- | `7104` | 取件門市臨時關轉店 |
1530
- | `7201` | 退件門市關轉店 |
1531
- | `7202` | 退件門市舊店號更新 |
1532
- | `7203` | 退件門市無取件門市資料 |
1533
- | `7204` | 退件門市臨時關轉店 |
1534
- | `8077` | 退至 7 總倉 |
1535
- | `8305` | 已送宅配 |
1536
- | `8306` | 放 7 天後拋棄 |
1537
-
1538
- ### 7-11 海外配送 (`07`/`08`)
1539
-
1540
- | 代碼 | 說明 |
1541
- |------|------|
1542
- | `0000` | 訂單已成立 等待出貨 |
1543
- | `5000` | 門市配達 |
1544
- | `5401` | 提單成立 |
1545
- | `5402` | 已入倉 |
1546
- | `5403` | 出口作業中 |
1547
- | `5404` | 已出倉 |
1548
- | `5405` | 清關中 |
1549
- | `5406` | 派送中 |
1550
- | `5407` | 取消 |
1551
- | `5408` | 問題單 |
1552
- | `5409` | 退件包裹 |
1553
- | `5410` | 店取未取轉宅配失敗 |
1554
- | `5411` | 宅配失敗 |
1555
- | `5412` | 台灣海關檢查不通過 |
1556
- | `5413` | 標籤異常/包裝異常/訂單異常取消 |
1557
- | `5414` | 貨件遺失 |
1558
- | `5415` | 包裹異常 (件數不對/超材) |
1559
- | `8000` | 買家已取件 |
1560
-
1561
- ### 全家代碼 (差異部份)
1562
-
1563
- | 代碼 | 說明 |
1564
- |------|------|
1565
- | `4067` | 小物流遺失 |
1566
- | `4068` | 門市遺失 |
1567
- | `4069` | 包裝廠不良 (滲漏) |
1568
- | `4070` | 門市反應商品包裝不良 (滲漏) |
1569
- | `4071` | 門市關店 |
1570
- | `4072` | 條碼資料重複 |
1571
- | `4073` | 7 日內未寄件單號失效 |
1572
- | `4074` | 貨物進店後發生異常提早退貨 |
1573
- | `5200` | 商品運送中 |
1574
- | `6004` | 商品退回物流中心 |
1575
- | `8002` | 退至全家總倉 |
1576
- | `8010` | 買家已取件-代收金額錯誤 |
1577
- | `8020` | 買家已取件商品有誤 |
1578
-
1579
- ### 萊爾富代碼 (差異部份)
1580
-
1581
- | 代碼 | 說明 |
1582
- |------|------|
1583
- | `4067` | 小物流遺失 |
1584
- | `4068` | 門市遺失 |
1585
- | `4069` | 包裝廠不良 (滲漏) |
1586
- | `4070` | 門市反應商品包裝不良 (滲漏) |
1587
- | `4071` | 門市關店 |
1588
- | `4073` | 7 日內未寄件單號失效 |
1589
- | `4074` | 貨物進店後發生異常提早退貨 |
1590
- | `8079` | 退至萊爾富總倉 |
1591
-
1592
- ### OK 代碼 (差異部份)
1593
-
1594
- | 代碼 | 說明 |
1595
- |------|------|
1596
- | `4030` | 無進貨資料 |
1597
- | `4031` | 商品破損退貨中 |
1598
- | `4032` | 商品超才退貨中 |
1599
- | `4040` | 條碼資料錯誤 |
1600
- | `4069` | 包裝廠不良 (滲漏) |
1601
- | `4070` | 門市反應商品包裝不良 |
1602
- | `4074` | 貨物進店後發生異常提早退貨 |
1603
- | `8076` | 退至 OK 總倉 |
1604
-
1605
- ### 貨態流轉範例
1606
-
1607
- 7-11 大宗 - 一般出貨 (成功取件):
1608
- ```
1609
- 1000 → 1050 → 3001 → 4000 → 5000 → 8000
1610
- ```
1611
-
1612
- 7-11 大宗 - 退貨成功:
1613
- ```
1614
- 1000 → 1050 → 3001 → 4000 → 5000 → 6001 → 5201 → 7001 → 8001
1615
- ```
1616
-
1617
- 7-11 大宗 - 門市關轉 (更新後成功):
1618
- ```
1619
- 1000 → 1050 → 3101 → 4036 → 1080 → 5000 → 8000
1620
- ```
1621
-
1622
- 7-11 海外配送 (店配,成功取件):
1623
- ```
1624
- 5401 → 5402 → 5405 → 5406 → 5000 → 8000
1625
- ```
1626
-
1627
- 7-11 海外配送 (宅配,成功取件):
1628
- ```
1629
- 5401 → 5402 → 5405 → 5406 → 8000
1630
- ```
1631
-
1632
- 四大超商 C2C - 一般出貨:
1633
- ```
1634
- 0101 → 5202 → 4000 → 5000 → 8000
1635
- ```
1636
-
1637
- 四大超商 C2C - 退貨成功:
1638
- ```
1639
- 0101 → 5202 → 4000 → 5000 → 6002 → 5201 → 7001 → 5001 → 8100
1640
- ```
1641
-
1642
- 四大超商 C2C - 二次退貨 (退至總倉):
1643
- ```
1644
- 0101 → 4000 → 5000 → 6002 → 4000 → 5001 → 8079 (萊) / 8077 (7) / 8002 (家)
1645
- ```
1646
-
1647
- 7-11 冷凍 C2C - 門市關轉 (取件成功):
1648
- ```
1649
- 0101 → 7101 / 7104 → 0102 → 4000 → 5000 → 8000
1650
- ```
1651
-
1652
- 7-11 冷凍 C2C - 門市關轉 (退件成功):
1653
- ```
1654
- 0101 → 5202 → 4000 → 5000 → 7201 / 7203 / 7204 → 0103 → 4000 → 5001 → 8100
1655
- ```
1656
-
1657
- ---
1658
-
1659
- ## 官方資源
1660
-
1661
- - **官方網站**:https://www.paynow.com.tw/
1662
- - **官方文件**:https://docs.paynow.com.tw/developer/docs/apipdf/logistics/
1663
- - **API 端點**:
1664
- - 正式:`https://logistic.paynow.com.tw`
1665
- - 測試:`https://testlogistic.paynow.com.tw`
1666
- - **客服信箱**:service@paynow.com.tw
1667
-
1668
- ---
1669
-
1670
- 最後更新:2026/05/07
1
+ # PayNow Logistics API Reference
2
+
3
+ 立吉富 PayNow 物流 API 完整參考文件,涵蓋 7-11、全家、黑貓、海外配送等 11 條產品線。
4
+
5
+ ---
6
+
7
+ ## 目錄
8
+
9
+ 1. [API 端點總覽](#api-端點總覽)
10
+ 2. [測試環境與認證](#測試環境與認證)
11
+ 3. [物流服務代碼](#物流服務代碼)
12
+ 4. [TripleDES 加密](#tripledes-加密)
13
+ 5. [PassCode 計算 (SHA-1)](#passcode-計算-sha-1)
14
+ 6. [選擇物流服務 (電子地圖)](#選擇物流服務-電子地圖)
15
+ 7. [建立物流訂單](#建立物流訂單)
16
+ 8. [7-11 大宗物流](#7-11-大宗物流)
17
+ 9. [7-11 冷凍大宗 B2C](#7-11-冷凍大宗-b2c)
18
+ 10. [7-11 冷凍店到店 (C2C)](#7-11-冷凍店到店-c2c)
19
+ 11. [7-11 海外配送](#7-11-海外配送)
20
+ 12. [全家大宗物流](#全家大宗物流)
21
+ 13. [全家冷凍大宗 B2C](#全家冷凍大宗-b2c)
22
+ 14. [全家冷凍店到店 (C2C)](#全家冷凍店到店-c2c)
23
+ 15. [四大超商常溫 C2C](#四大超商常溫-c2c)
24
+ 16. [黑貓宅配](#黑貓宅配)
25
+ 17. [黑貓店到店](#黑貓店到店)
26
+ 18. [查詢物流單](#查詢物流單)
27
+ 19. [取消物流單](#取消物流單)
28
+ 20. [重新取號](#重新取號)
29
+ 21. [門市更新 (關轉)](#門市更新-關轉)
30
+ 22. [物流貨態回傳 (Callback)](#物流貨態回傳-callback)
31
+ 23. [貨態代碼對照表](#貨態代碼對照表)
32
+
33
+ ---
34
+
35
+ ## API 端點總覽
36
+
37
+ ### 基礎網址
38
+
39
+ | 環境 | 網址 |
40
+ |------|------|
41
+ | **正式環境** | `https://logistic.paynow.com.tw` |
42
+ | **測試環境** | `https://testlogistic.paynow.com.tw` |
43
+
44
+ > 注意:PayNow 物流 API 與金流共用同一網域結構,但物流走 `logistic.paynow.com.tw`,金流走 `www.paynow.com.tw/service/etopm.aspx`,兩者**不可混用**。
45
+
46
+ ### 主要 API 路徑
47
+
48
+ | 功能 | API URL | 方法 |
49
+ |------|---------|------|
50
+ | 選擇物流服務 (電子地圖) | `/Member/Order/Choselogistics` | POST |
51
+ | 建立物流訂單 | `/api/Orderapi/Add_Order` | POST |
52
+ | 7-11 大宗獲取出貨單號 | `/api/Bulk711Order/ShipBulk711paymentno` | POST |
53
+ | 7-11 冷凍大宗獲取出貨單號 | `/api/711FreezingB2C/Ship711B2Cpaymentno` | POST |
54
+ | 列印 7-11 大宗物流單 | `/Member/Order/Print711bulkLabel` | POST |
55
+ | 列印 7-11 冷凍大宗物流單 | `/Member/Order/Print711FreezingB2CLabel` | POST |
56
+ | 列印 7-11 冷凍 C2C 物流單 | `/Member/Order/Print711FreezingC2CLabel` | POST |
57
+ | 列印 7-11 海外配送物流單 | `/api/OverSeas711Order` | GET |
58
+ | 列印 7-11 交貨便物流單 | `/api/Order711` | GET |
59
+ | 列印全家 C2C 物流單 | `/api/OrderFamiC2C` | GET |
60
+ | 列印萊爾富物流單 | `/api/OrderHiLife` | GET |
61
+ | 列印 OK 物流單 | `/api/OKC2C` | GET |
62
+ | 列印黑貓宅急便標籤 | `/Member/Order/PrintBlackCatLabel` | POST |
63
+ | 查詢物流單 (PayNow 單號) | `/api/Orderapi/Get_Order_Info` | GET |
64
+ | 查詢物流單 (商家訂單編號) | `/api/Orderapi/Get_Order_Info_orderno` | GET |
65
+ | 取消物流單 | `/api/Orderapi/CancelOrder` | DELETE |
66
+ | 重新取號 | `/api/Orderapi/ReNewOrder` | POST |
67
+ | 門市更新 (關轉) | `/api/Orderapi/Put` | PUT |
68
+ | 更新物流訂單 (7-11 大宗) | `/api/Bulk711Order/UpdateB2C711Order` | PUT |
69
+ | 更新物流訂單 (7-11 冷凍 B2C) | `/api/711FreezingB2C/Update711B2COrder` | PUT |
70
+ | 建立 7-11 退貨物流單 | `/api/Orderapi/ReturnPaymentno` | PUT |
71
+ | 7-11 海外配送-國家代碼 | `/api/OverSeas711Order/SelCountryID` | POST |
72
+ | 7-11 海外配送-運費試算 | `/api/Orderapi/SelWeightChart` | POST |
73
+ | 7-11 海外配送-費用查詢 (依訂單) | `/api/OverSeas711Order/SelBillDetail` | POST |
74
+ | 7-11 海外配送-費用查詢 (依日期) | `/api/OverSeas711Order/SelBillDetailDate` | POST |
75
+ | 全家 C2C 店號轉換 | `/api/OrderFamiC2C/GetFamiStoreID` | GET |
76
+ | 全家冷凍店鋪空間保留 | `/api/FamiFreezingB2C/UpSpaceConfirm` | POST |
77
+
78
+ ---
79
+
80
+ ## 測試環境與認證
81
+
82
+ ### 認證資料
83
+
84
+ PayNow 物流 API 使用「商家主帳號 (`user_account`) + API 密碼 (`apicode`)」雙鑰機制,並透過 TripleDES 加密 + SHA-1 PassCode 雙重保護。
85
+
86
+ | 項目 | 說明 |
87
+ |------|------|
88
+ | `user_account` | 商家主帳號,10 碼 |
89
+ | `apicode` | 商家 API 密碼,30 碼,請以 TripleDES 加密後傳送 |
90
+ | `partner_token` | 合作夥伴識別碼 (HTTP Header 帶入),用於回傭計算,非必填 |
91
+
92
+ ### partner_token (合作夥伴識別)
93
+
94
+ `partner_token` 為 HTTP Header 參數,用於辨識合作夥伴身份並計算回傭:
95
+
96
+ ```http
97
+ POST /api/Orderapi/Add_Order HTTP/1.1
98
+ Host: logistic.paynow.com.tw
99
+ Content-Type: application/x-www-form-urlencoded
100
+ partner_token: YOUR_PARTNER_TOKEN
101
+ ```
102
+
103
+ 注意事項:
104
+
105
+ - `partner_token` 為合作夥伴專屬識別碼,請妥善保管,不同合作夥伴的 token 不可共用
106
+ - 如 token 遺失或洩漏,請立即聯繫 PayNow 申請更換
107
+ - 未提供 `partner_token` 或 token 錯誤時,訂單仍可正常建立,但無法正確計算回傭
108
+
109
+ ### 取得測試帳號
110
+
111
+ 請聯繫 PayNow 客服 (`service@paynow.com.tw`) 申請測試環境帳號,取得:
112
+
113
+ - 測試 `user_account`
114
+ - 測試 `apicode`
115
+ - TripleDES 公鑰 (8 bytes)
116
+ - TripleDES 私鑰 (24 bytes)
117
+
118
+ ---
119
+
120
+ ## 物流服務代碼
121
+
122
+ PayNow 物流以 `Logistic_serviceID` (對應建立訂單的 `Logistic_service` 欄位) 區分產品線:
123
+
124
+ | Service ID | 物流服務 | 類型 |
125
+ |------------|----------|------|
126
+ | `01` | 7-11 交貨便 | C2C 常溫 |
127
+ | `02` | 7-11 大宗物流 | B2C 常溫 |
128
+ | `03` | 全家店到店 | C2C 常溫 |
129
+ | `04` | 全家大宗物流 | B2C 常溫 |
130
+ | `05` | 萊爾富店到店 | C2C 常溫 |
131
+ | `06` | 黑貓宅急便 | 宅配 |
132
+ | `07` | 7-11 海外配送 (店配) | 跨境店配 |
133
+ | `08` | 7-11 海外配送 (宅配) | 跨境宅配 |
134
+ | `10` | OK 店到店 | C2C 常溫 |
135
+ | `12` | 7-11 大宗退貨便 | 退貨 |
136
+ | `21` | 7-11 交貨便 (冷凍) | C2C 冷凍 |
137
+ | `22` | 7-11 大宗物流 (冷凍) | B2C 冷凍 |
138
+ | `23` | 全家店到店物流 (冷凍) | C2C 冷凍 |
139
+ | `24` | 全家大宗物流 (冷凍) | B2C 冷凍 |
140
+ | `36` | 黑貓宅急便 (PayNow) | 宅配 (含自動保險) |
141
+ | `46` | 黑貓到店 (PayNow) | 店到店 |
142
+
143
+ ---
144
+
145
+ ## TripleDES 加密
146
+
147
+ PayNow 物流的 `JsonOrder` 與 `apicode` 都需使用 TripleDES 加密後再 URLEncode 傳送,**這是與一般 PayNow 金流動態 AES-256 不同的加密機制**,物流端固定為 3DES/ECB/Zero Padding。
148
+
149
+ ### 加密規格
150
+
151
+ | 項目 | 值 |
152
+ |------|-----|
153
+ | 演算法 | 3DES (TripleDES) |
154
+ | 模式 | ECB |
155
+ | Padding | Zero Padding |
156
+ | 公鑰 (IV) | 8 bytes (例:`12345678`) |
157
+ | 私鑰 (Key) | 24 bytes (例:`123456789070828783123456`) |
158
+ | 編碼輸出 | Base64,並把空白字元 `' '` 換成 `+` |
159
+
160
+ ### 加解密前後範例 (摘自官方附錄)
161
+
162
+ 加密前:
163
+
164
+ ```json
165
+ {"mem_type":2,"buysafeno":"8000001910145799460","mem_cid":"13099407","passcode":"2B24518AA4C2536CAF7ADCBC635C0751699BB7CC", ...}
166
+ ```
167
+
168
+ 加密後 (Base64):
169
+
170
+ ```
171
+ 229d7b9b639845a7f12cc8524a3988ce77647ced3cacec907bf5432b2df9f7a68055b05204f29d8e1b0ca4c9...
172
+ ```
173
+
174
+ ### C# 範例 (官方)
175
+
176
+ ```csharp
177
+ public string Encrypt(string content)
178
+ {
179
+ TripleDes.IV = Encoding.UTF8.GetBytes("12345678");
180
+ TripleDes.Key = Encoding.UTF8.GetBytes("123456789070828783123456");
181
+ TripleDes.Mode = CipherMode.ECB;
182
+ TripleDes.Padding = PaddingMode.Zeros;
183
+
184
+ var data = Encoding.UTF8.GetBytes(content);
185
+ var ict = TripleDes.CreateEncryptor();
186
+ var enc = ict.TransformFinalBlock(data, 0, data.Length);
187
+ var result = Convert.ToBase64String(enc).Replace(' ', '+');
188
+
189
+ return result;
190
+ }
191
+ ```
192
+
193
+ ### PHP 範例
194
+
195
+ ```php
196
+ <?php
197
+
198
+ function tripleDesEncrypt(string $content, string $key, string $iv): string
199
+ {
200
+ // 補齊 24 bytes 並使用 ECB;OpenSSL 需手動 zero-pad
201
+ $blockSize = 8;
202
+ $padLen = $blockSize - (strlen($content) % $blockSize);
203
+ if ($padLen !== $blockSize) {
204
+ $content .= str_repeat("\0", $padLen);
205
+ }
206
+
207
+ $encrypted = openssl_encrypt(
208
+ $content,
209
+ 'des-ede3',
210
+ $key,
211
+ OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING
212
+ );
213
+
214
+ return str_replace(' ', '+', base64_encode($encrypted));
215
+ }
216
+
217
+ // 使用
218
+ $key = '123456789070828783123456'; // 24 bytes
219
+ $iv = '12345678'; // 8 bytes (ECB 模式不會用到,但 spec 仍要傳)
220
+ $jsonOrder = json_encode($orderData, JSON_UNESCAPED_UNICODE);
221
+ $encrypted = tripleDesEncrypt($jsonOrder, $key, $iv);
222
+ $postBody = 'JsonOrder=' . urlencode($encrypted);
223
+ ```
224
+
225
+ ### Python 範例
226
+
227
+ ```python
228
+ from Crypto.Cipher import DES3
229
+ import base64
230
+
231
+ def triple_des_encrypt(content: str, key: str) -> str:
232
+ """PayNow 物流 TripleDES/ECB/Zero Padding"""
233
+ block_size = 8
234
+ data = content.encode('utf-8')
235
+ pad_len = block_size - (len(data) % block_size)
236
+ if pad_len != block_size:
237
+ data += b'\x00' * pad_len
238
+
239
+ cipher = DES3.new(key.encode('utf-8'), DES3.MODE_ECB)
240
+ encrypted = cipher.encrypt(data)
241
+ return base64.b64encode(encrypted).decode('ascii').replace(' ', '+')
242
+
243
+ # 使用
244
+ key = '123456789070828783123456' # 24 bytes
245
+ encrypted = triple_des_encrypt(json_str, key)
246
+ ```
247
+
248
+ ---
249
+
250
+ ## PassCode 計算 (SHA-1)
251
+
252
+ PassCode 為 PayNow 物流防偽用雜湊值,作法為:將指定欄位依序串接後計算 SHA-1,輸出 40 字元大寫十六進位字串。
253
+
254
+ ### 通用組成方式
255
+
256
+ | 情境 | PassCode 組成 |
257
+ |------|---------------|
258
+ | 建立物流訂單 | `user_account + OrderNo + TotalAmount + apicode` |
259
+ | 7-11 大宗獲取出貨單號 | `user_account + apicode` |
260
+ | 重新取號 | `user_account + OrderNo + TotalAmount + apicode` |
261
+ | 取消訂單 | `user_account + OrderNo + TotalAmount + apicode` |
262
+ | 門市更新 (關轉) | `user_account + OrderNo + TotalAmount + apicode` |
263
+ | 建立退貨物流單 | `user_account + LogisticNumber + apicode` |
264
+
265
+ > 串接時 **不包含 `+` 符號**,僅是數值連接 (concat)。
266
+ > 例:`user_account=28229955`、`OrderNo=211210165125`、`TotalAmount=200`、`apicode=12345678` → `2822995521121016512520012345678` → SHA-1 → `4CF47FD844DF64C5D0FBF8DD134708B55ABE208B`
267
+
268
+ ### C# 範例 (官方)
269
+
270
+ ```csharp
271
+ public string SHA1Encrypt(string data)
272
+ {
273
+ SHA1CryptoServiceProvider sha1 = new SHA1CryptoServiceProvider();
274
+ var keyBytes = Encoding.Default.GetBytes(data);
275
+ var hash = sha1.ComputeHash(keyBytes);
276
+ return BitConverter.ToString(hash).Replace("-", "");
277
+ }
278
+ ```
279
+
280
+ ### PHP 範例
281
+
282
+ ```php
283
+ <?php
284
+
285
+ function generatePassCode(array $parts): string
286
+ {
287
+ return strtoupper(sha1(implode('', $parts)));
288
+ }
289
+
290
+ // 建立物流訂單
291
+ $passCode = generatePassCode([
292
+ $userAccount, // 28229955
293
+ $orderNo, // 211210165125
294
+ $totalAmount, // 200
295
+ $apicode, // 12345678
296
+ ]);
297
+ // → 4CF47FD844DF64C5D0FBF8DD134708B55ABE208B
298
+ ```
299
+
300
+ ### Python 範例
301
+
302
+ ```python
303
+ import hashlib
304
+
305
+ def generate_pass_code(*parts: str) -> str:
306
+ raw = ''.join(parts)
307
+ return hashlib.sha1(raw.encode('utf-8')).hexdigest().upper()
308
+
309
+ pass_code = generate_pass_code(user_account, order_no, str(total_amount), apicode)
310
+ ```
311
+
312
+ ---
313
+
314
+ ## 選擇物流服務 (電子地圖)
315
+
316
+ ### 端點
317
+
318
+ ```
319
+ POST /Member/Order/Choselogistics
320
+ ```
321
+
322
+ ### 通用參數
323
+
324
+ | 參數 | 名稱 | 型態 | 長度 | 必填 | 說明 |
325
+ |------|------|------|------|------|------|
326
+ | `user_account` | 商家主帳號 | string | 10 | ● | |
327
+ | `orderno` | 訂單編號 | string | 27 | 否 | 帶入後將原樣回傳 |
328
+ | `apicode` | 商家 API 密碼 | string | 30 | ● | 須以 TripleDES 加密 |
329
+ | `Logistic_serviceID` | 物流服務 ID | string | 2 | ● | 詳見下表 |
330
+ | `returnUrl` | 回傳網址 | string | 200 | ● | 使用者選擇門市後 PayNow 會 POST 至此 |
331
+
332
+ ### 各物流的 Logistic_serviceID 對照
333
+
334
+ | 服務 | Logistic_serviceID |
335
+ |------|-------------------|
336
+ | 4 大超商常溫 (依輸入導向對應地圖) | `01` / `03` / `05` / `10` |
337
+ | 7-11 大宗物流 | `02` (固定) |
338
+ | 7-11 大宗物流 (冷凍) | `22` |
339
+ | 7-11 交貨便 (冷凍) | `21` 或 `22` |
340
+ | 7-11 海外配送 (店配) | `07` (額外帶 `Country`) |
341
+ | 全家大宗物流 | `04` |
342
+ | 全家店到店 (冷凍) | `23` |
343
+ | 全家大宗 (冷凍) | `24` (額外帶 `Length`/`Wide`/`High`/`Weight`/`StartDate`/`EndDate`) |
344
+ | 黑貓店到店 | `46` |
345
+
346
+ ### 海外配送專用參數 (Logistic_serviceID=07)
347
+
348
+ | 參數 | 必填 | 說明 |
349
+ |------|------|------|
350
+ | `Country` | ● | `SG`/`MY`/`HK`/`MO`/`TH`,全部國家輸入 `ALL` |
351
+
352
+ ### 全家冷凍大宗專用參數 (Logistic_serviceID=24)
353
+
354
+ | 參數 | 必填 | 說明 |
355
+ |------|------|------|
356
+ | `Length` | ● | 長 (cm),依申請材積 S60 (長+寬+高<60) 或 S105 |
357
+ | `Wide` | ● | 寬 (cm) |
358
+ | `High` | ● | 高 (cm) |
359
+ | `Weight` | ● | 重量 (公克),未填請填空字串 |
360
+ | `StartDate` | ● | 出貨日起 `yyyy-MM-dd`,未填請填空字串 |
361
+ | `EndDate` | ● | 出貨日迄 `yyyy-MM-dd` |
362
+ | `Ecplateform` | ● | EC 平台代碼 |
363
+
364
+ ### 回傳參數
365
+
366
+ | 參數 | 說明 |
367
+ |------|------|
368
+ | `orderno` | 商家訂單編號 (如有帶入) |
369
+ | `service` | 物流服務代碼 |
370
+ | `storeid` | 店 ID |
371
+ | `storename` | 店名 |
372
+ | `storeaddress` | 店址 |
373
+ | `ReservedNo` | 保留編號 (僅冷凍 24/23 服務回傳) |
374
+ | `ShipDate` | 出貨日期 `yyyy-MM-dd` (僅冷凍 24/23 服務回傳) |
375
+
376
+ ### PHP 範例 - 開啟電子地圖 (iframe)
377
+
378
+ ```php
379
+ <?php
380
+
381
+ $apicodeEncrypted = tripleDesEncrypt('12345678', $key, $iv);
382
+
383
+ $html = <<<HTML
384
+ <form id="map-form" method="post"
385
+ action="https://testlogistic.paynow.com.tw/Member/Order/Choselogistics"
386
+ target="map-iframe">
387
+ <input type="hidden" name="user_account" value="28229955">
388
+ <input type="hidden" name="orderno" value="ORDER123">
389
+ <input type="hidden" name="apicode" value="{$apicodeEncrypted}">
390
+ <input type="hidden" name="Logistic_serviceID" value="02">
391
+ <input type="hidden" name="returnUrl" value="https://your-site.com/store_callback">
392
+ </form>
393
+ <iframe name="map-iframe" width="100%" height="600"></iframe>
394
+ <script>document.getElementById('map-form').submit();</script>
395
+ HTML;
396
+ ```
397
+
398
+ ---
399
+
400
+ ## 建立物流訂單
401
+
402
+ 所有物流產品線共用同一支 API,由 `Logistic_service` 參數判斷實際服務。
403
+
404
+ ### 端點
405
+
406
+ ```
407
+ POST /api/Orderapi/Add_Order
408
+ Content-Type: application/x-www-form-urlencoded
409
+ ```
410
+
411
+ ### Request
412
+
413
+ | 參數 | 必填 | 說明 |
414
+ |------|------|------|
415
+ | `JsonOrder` | ● | `JsonOrder Content` 物件 → JSON 字串 → TripleDES 加密 → URLEncode |
416
+
417
+ ### JsonOrder Content (通用欄位)
418
+
419
+ | 參數 | 名稱 | 型態 | 長度 | 必填 | 說明 |
420
+ |------|------|------|------|------|------|
421
+ | `user_account` | 商家主帳號 | string | 10 | ● | |
422
+ | `apicode` | 商家 API 密碼 | string | 30 | ● | (整個 JsonOrder 會再次加密) |
423
+ | `Logistic_service` | 物流服務代碼 | string | 2 | ● | 見 [物流服務代碼](#物流服務代碼) |
424
+ | `OrderNo` | 商家訂單編號 | string | 27 | ● | 限英文與數字 |
425
+ | `DeliverMode` | 取貨是否付款 | string | 2 | ● | `01`:取貨付款 `02`:取貨不付款 |
426
+ | `TotalAmount` | 總金額 | string | 5 | ● | 正整數,超商不可大於 20,000,黑貓不可大於 100,000 |
427
+ | `Remark` | 備註 | string | 200 | ● | 不帶值請填空字串 |
428
+ | `Description` | 單號描述 | string | 50 | ● | 黑貓另有商品分類代碼 |
429
+ | `EC` | EC 平台 | string | 50 | 否 | |
430
+ | `receiver_storeid` | 取件店號 | string | 30 | ● (超商) | 宅配填空字串 |
431
+ | `receiver_storename` | 取件店名 | string | 100 | ● (超商) | |
432
+ | `return_storeid` | 退件店號 | string | 6 | ● | 不帶值請填空字串 |
433
+ | `Receiver_Name` | 收件人姓名 | string | 10~30 | ● | 各物流長度限制不同 |
434
+ | `Receiver_Phone` | 收件人手機 | string | 10 | ● | |
435
+ | `Receiver_Email` | 收件人 EMAIL | string | 100 | ● | |
436
+ | `Receiver_address` | 收件人地址 | string | 150 | ● | |
437
+ | `Sender_Name` | 寄件人姓名 | string | 10 | ● | 大宗類型可填空字串自動帶入「立吉富」 |
438
+ | `Sender_Phone` | 寄件人手機 | string | 10 | ● | 大宗類型可填空字串自動帶入「0900000000」 |
439
+ | `Sender_Email` | 寄件人 EMAIL | string | 100 | ● | |
440
+ | `Sender_address` | 寄件人地址 | string | 150 | ● | |
441
+ | `PassCode` | 傳遞碼 | string | 40 | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
442
+ | `Deadline` | 預定出貨天數 | int | | (大宗) | 1~7,預定出貨日 = 建單日 + Deadline |
443
+
444
+ ### Ibon 禁用字元 (7-11 訂單)
445
+
446
+ 7-11 大宗、冷凍、海外配送等系列均不可在欄位中包含以下字元:
447
+
448
+ ```
449
+ ' " % | & ` ^ @ !
450
+ . # ( ) * _ + - ; : ,
451
+ ```
452
+
453
+ ### 通用 Response 欄位
454
+
455
+ | 參數 | 說明 |
456
+ |------|------|
457
+ | `Status` | `S` 成功 / `F` 失敗 |
458
+ | `LogisticNumber` | PayNow 物流單號 (主要追蹤鍵) |
459
+ | `LogisticService` | 物流服務名稱 |
460
+ | `LogisticServiceID` | 物流服務代碼 |
461
+ | `paymentno` | 物流商貨運編號 (部分服務在此即回傳) |
462
+ | `validationno` | 驗證碼 (7-11 店到店回傳,配合 paymentno 至 Ibon 列印) |
463
+ | `orderno` | 商家訂單編號 |
464
+ | `ErrorMsg` | 失敗時為錯誤訊息,成功為 `null` |
465
+ | `ReturnMsg` | 額外回傳訊息 |
466
+
467
+ ---
468
+
469
+ ## 7-11 大宗物流
470
+
471
+ 服務代碼:`02` / 退貨便:`12` / 文件版本:`711Bulk-API V2.4`
472
+
473
+ ### 流程
474
+
475
+ 1. `/Member/Order/Choselogistics` 開啟電子地圖選擇取件門市
476
+ 2. `/api/Orderapi/Add_Order` 建立物流訂單,取得 `LogisticNumber`
477
+ 3. `/api/Bulk711Order/ShipBulk711paymentno` 獲取出貨單號 (`paymentno` / 配送編號)
478
+ 4. `/Member/Order/Print711bulkLabel` 列印物流標籤
479
+ 5. 於物流標籤上的「門市進貨日 = 建單日 + Deadline」當天進倉
480
+
481
+ ### 進貨日規則
482
+
483
+ - `Deadline` 必須是 1~7 之間的整數
484
+ - 預定出貨日 = 建立物流單日 + Deadline
485
+ - 例:建單日 `2021/03/14`,`Deadline=3` → 預定出貨日 `2021/03/17`
486
+ - 不可提前到貨,提前到貨會被刷退
487
+ - 已超過預定出貨日:
488
+ - 未列印過標籤:門市進貨日自動變更為「列印日 + 1 天」
489
+ - 已列印過標籤:必須重新取號再列印新標籤
490
+
491
+ ### 重新取號規則
492
+
493
+ - 必須等物流驗收後且未取貨才能重新取號
494
+ - 配對新出貨單號後仍要回到列印 7-11 大宗物流頁面列印新標籤
495
+ - 已是貨態 `1000` (上傳中)、`1050` (上傳成功)、`8000` (已取件) 無法重取
496
+
497
+ ### 獲取出貨單號
498
+
499
+ ```
500
+ POST /api/Bulk711Order/ShipBulk711paymentno
501
+ ```
502
+
503
+ JsonOrder Content:
504
+
505
+ ```json
506
+ {
507
+ "user_account": "28229955",
508
+ "apicode": "12345678",
509
+ "PassCode": "625B528740B1860CA5392E2CA2B577066596A160",
510
+ "ShipList": [
511
+ { "LogisticNumber": "MIJA0027B22112100002", "sno": "1" }
512
+ ]
513
+ }
514
+ ```
515
+
516
+ > PassCode 此 API 採 `SHA-1(user_account + apicode)`,與一般訂單不同。
517
+
518
+ Response (Object Array):
519
+
520
+ ```json
521
+ [
522
+ {
523
+ "LogisticNumber": "MIJA0027B22112100002",
524
+ "sno": "1",
525
+ "paymentno": "82900502030",
526
+ "ErrorMsg": null
527
+ }
528
+ ]
529
+ ```
530
+
531
+ ### 列印物流單
532
+
533
+ ```
534
+ POST /Member/Order/Print711bulkLabel
535
+ ```
536
+
537
+ | 參數 | 必填 | 說明 |
538
+ |------|------|------|
539
+ | `LogisticNumbers` | ● | `Paynow物流單號_物流單子序號`,多筆以 `,` 分隔,例:`ABCD0017B21903001221_1,ABCD0017B21903001270_1` |
540
+
541
+ ### 建立退貨物流單
542
+
543
+ ```
544
+ PUT /api/Orderapi/ReturnPaymentno
545
+ Content-Type: application/x-www-form-urlencoded
546
+ ```
547
+
548
+ JsonOrder Content:
549
+
550
+ ```json
551
+ {
552
+ "user_account": "28229955",
553
+ "apicode": "12345678",
554
+ "LogisticNumber": "MIJA0027B22112100002",
555
+ "LogisticServiceID": "02",
556
+ "PassCode": "24BCF048A550B56D74F9C342DCFA3FA01DBD2AFB"
557
+ }
558
+ ```
559
+
560
+ > 退貨 PassCode 為 `SHA-1(user_account + LogisticNumber + apicode)`。
561
+
562
+ Response:
563
+
564
+ ```json
565
+ {
566
+ "Status": "S",
567
+ "LogisticNumber": "MIJA0027R42112130001",
568
+ "LogisticService": "7-11大宗退貨便",
569
+ "LogisticServiceID": "12",
570
+ "paymentno": "A47058871088",
571
+ "ReturnMsg": "",
572
+ "orderno": "MIJA0027B22112100002",
573
+ "ErrorMsg": null
574
+ }
575
+ ```
576
+
577
+ 消費者持 `paymentno` 至 Ibon 機台輸入即可列印退貨物流單。
578
+
579
+ ### 更新訂單 (尚未出貨)
580
+
581
+ ```
582
+ PUT /api/Bulk711Order/UpdateB2C711Order
583
+ ```
584
+
585
+ 可改:`receiver_storeid`、`receiver_storename`、`Receiver_Name`、`Receiver_Phone`。
586
+ PassCode 為 `SHA-1(user_account + Orderno + TotalAmount + apicode)`。
587
+
588
+ ### 完整建立 PHP 範例
589
+
590
+ ```php
591
+ <?php
592
+
593
+ $payload = [
594
+ 'user_account' => '28229955',
595
+ 'apicode' => '12345678',
596
+ 'Logistic_service' => '02',
597
+ 'OrderNo' => '211210165125',
598
+ 'DeliverMode' => '02',
599
+ 'TotalAmount' => '200',
600
+ 'Remark' => '',
601
+ 'Description' => 'test',
602
+ 'receiver_storeid' => '126616',
603
+ 'receiver_storename' => '立行門市',
604
+ 'return_storeid' => '',
605
+ 'Receiver_Name' => '收件測',
606
+ 'Receiver_Phone' => '0912345678',
607
+ 'Receiver_Email' => '123@paynow.com.tw',
608
+ 'Receiver_address' => '新北市三重區力行路二段158號160號',
609
+ 'Sender_Name' => '',
610
+ 'Sender_Phone' => '',
611
+ 'Sender_Email' => 'test@paynow.com.tw',
612
+ 'Sender_address' => '',
613
+ 'Deadline' => 1,
614
+ ];
615
+ $payload['PassCode'] = strtoupper(sha1(
616
+ $payload['user_account'] . $payload['OrderNo'] .
617
+ $payload['TotalAmount'] . $payload['apicode']
618
+ ));
619
+
620
+ $json = json_encode($payload, JSON_UNESCAPED_UNICODE);
621
+ $encJson = tripleDesEncrypt($json, '123456789070828783123456', '12345678');
622
+
623
+ $ch = curl_init();
624
+ curl_setopt_array($ch, [
625
+ CURLOPT_URL => 'https://testlogistic.paynow.com.tw/api/Orderapi/Add_Order',
626
+ CURLOPT_POST => true,
627
+ CURLOPT_POSTFIELDS => http_build_query(['JsonOrder' => $encJson]),
628
+ CURLOPT_HTTPHEADER => ['partner_token: YOUR_PARTNER_TOKEN'],
629
+ CURLOPT_RETURNTRANSFER => true,
630
+ ]);
631
+ $response = json_decode(curl_exec($ch), true);
632
+ curl_close($ch);
633
+ ```
634
+
635
+ ---
636
+
637
+ ## 7-11 冷凍大宗 B2C
638
+
639
+ 服務代碼:`22` / 文件版本:`711FreezingBulkB2C V2.4`
640
+
641
+ 流程與 7-11 常溫大宗類似,差異:
642
+
643
+ - 電子地圖 `Logistic_serviceID=22`
644
+ - 建單時 `Logistic_service=22`
645
+ - 出貨單號 API:`POST /api/711FreezingB2C/Ship711B2Cpaymentno`
646
+ - 列印標籤 API:`POST /Member/Order/Print711FreezingB2CLabel`
647
+ - 列印標籤後**隔日進行出貨**,進店日由物流商分配 (不需 `Deadline`)
648
+ - 更新訂單 API:`PUT /api/711FreezingB2C/Update711B2COrder`
649
+
650
+ 關轉 (門市更新) 必須在收到 `4036` 貨態代碼後 `D+2 上午 10:50` 前處理,逾期則無法關轉。
651
+
652
+ 範例 Response:
653
+
654
+ ```json
655
+ {
656
+ "Status": "S",
657
+ "LogisticNumber": "MIJA0027F22112140001",
658
+ "LogisticService": "7-11大宗物流冷凍",
659
+ "LogisticServiceID": "22",
660
+ "ReturnMsg": "",
661
+ "orderno": "211214141817",
662
+ "ErrorMsg": null
663
+ }
664
+ ```
665
+
666
+ ---
667
+
668
+ ## 7-11 冷凍店到店 (C2C)
669
+
670
+ 服務代碼:`21` / 文件版本:`711FreezingC2C V2.0`
671
+
672
+ ### 流程
673
+
674
+ 1. 電子地圖選店 (`Logistic_serviceID=22`,注意:建單時改用 `21`)
675
+ 2. 建立物流訂單,回傳 `LogisticNumber` + `paymentno` + `validationno`
676
+ 3. 列印標籤:`POST /Member/Order/Print711FreezingC2CLabel`
677
+ 4. 列印後隔日出貨
678
+
679
+ ### 建單範例
680
+
681
+ Request:
682
+
683
+ ```json
684
+ {
685
+ "user_account": "28229955",
686
+ "apicode": "12345678",
687
+ "Logistic_service": "22",
688
+ "OrderNo": "211214141817",
689
+ "DeliverMode": "02",
690
+ "TotalAmount": "200",
691
+ "Remark": "",
692
+ "Description": "test",
693
+ "receiver_storeid": "183413",
694
+ "receiver_storename": "八仙門市",
695
+ "return_storeid": "",
696
+ "Receiver_Name": "收件測",
697
+ "Receiver_Phone": "0912345678",
698
+ "Receiver_Email": "123@paynow.com.tw",
699
+ "Receiver_address": "新北市八里區中華路二段290號292號296號",
700
+ "Sender_Name": "寄件測",
701
+ "Sender_Phone": "0900000000",
702
+ "Sender_Email": "test@paynow.com.tw",
703
+ "Sender_address": "",
704
+ "PassCode": "08D6038DFDA1AF0412CBA925135DC33F31C928A1"
705
+ }
706
+ ```
707
+
708
+ Response:
709
+
710
+ ```json
711
+ {
712
+ "Status": "S",
713
+ "LogisticNumber": "MIJA0027R22203232824",
714
+ "LogisticService": "7-11交貨便冷凍",
715
+ "LogisticServiceID": "21",
716
+ "paymentno": "D8273267",
717
+ "validationno": "9066",
718
+ "ReturnMsg": "",
719
+ "orderno": "220323105411",
720
+ "ErrorMsg": null
721
+ }
722
+ ```
723
+
724
+ ### 列印標籤
725
+
726
+ ```
727
+ POST /Member/Order/Print711FreezingC2CLabel
728
+ ```
729
+
730
+ | 參數 | 必填 | 說明 |
731
+ |------|------|------|
732
+ | `orderNumberStr` | ● | PayNow 物流單號,多筆以 `,` 分隔 |
733
+ | `user_account` | ● | |
734
+
735
+ ### 關轉時限
736
+
737
+ 收到 `7101`、`7104`、`7201`、`7204` 貨態代碼後 `D+7` 內必須打 `/api/Orderapi/Put` 進行關轉,逾期失效。
738
+
739
+ ---
740
+
741
+ ## 7-11 海外配送
742
+
743
+ 服務代碼:`07` (店配) / `08` (宅配) / 文件版本:`711OverSea V2.7`
744
+
745
+ ### 適用國家與限制
746
+
747
+ | 國家 | 代碼 | 取貨天數 | 重量/材積限制 | 進口免稅額 | 當地宅配 |
748
+ |------|------|----------|----------------|-------------|-----------|
749
+ | 香港 | `HK` | 3 天 | 店配 30×50×30 cm 5kg;宅配 85×85×85 cm 20kg | 無關稅 | 1kg=27HKD,2-5kg=37HKD |
750
+ | 新加坡 | `SG` | 2 天 | 店配 長+寬+高 80cm 5kg;宅配 85×85×85 cm 20kg | SGD 400 | 首重 7SGD/kg、續重 3SGD/kg |
751
+ | 馬來西亞 | `MY` | 4 天 | 店配 40×40×40 cm 4kg;宅配 85×85×85 cm 20kg | MYR 500 | 西馬首重 9MYR/kg;東馬首重 23MYR/kg |
752
+ | 澳門 | `MO` | 24 小時內 | 店配 45×31×35 cm 20kg;宅配 120×80×70 cm 20kg | — | 同區一件 10 澳幣,跨區 2kg 內 22 澳幣 |
753
+ | 泰國 | `TH` | 3 天 | 店配 60×60×60 cm 5kg;宅配 85×85×85 cm 20kg | 含稅 | 首重 60 NTD/kg、續重 15 NTD/kg |
754
+ | 越南 | `VN` | — | 宅配 3kg | 含稅 | — |
755
+ | 美國 | `US` | — | 宅配 100×80×70 cm 20kg | USD 800 | — |
756
+
757
+ 材積計算:
758
+
759
+ - 港/新/馬/澳/泰/越南:`長 × 寬 × 高 / 6000`
760
+ - 美國/其他國家:`長 × 寬 × 高 / 5000`
761
+
762
+ > 重量與材積取較高值計價。中國目前無法配送 (運費分上海/江蘇/浙江/廣東/深圳/福建/廈門 `FeeMode=0` 與其他省 `FeeMode=1`)。
763
+
764
+ ### 禁運物品 (摘錄)
765
+
766
+ - 香港:活生動物、無煙菸草製品、易燃易爆物質、香水、鋰電池等
767
+ - 新加坡:電子香菸、電子菸斗、電子雪茄菸
768
+ - 馬來西亞:肉類、海鮮、奶製品、燕窩、菲律賓/印尼水果、鋰電池、武器等
769
+
770
+ 實際規範以各國海關為準。
771
+
772
+ ### 流程
773
+
774
+ 1. (店配) 電子地圖 (`Logistic_serviceID=07`、`Country=ALL`/`HK`/`SG` 等) 選店
775
+ 2. `/api/Orderapi/Add_Order` 建單 (`Logistic_service=07` 或 `08`)
776
+ 3. `GET /api/OverSeas711Order` 列印標籤 (5 日內限制)
777
+ 4. 訂單成立後 5 日內完成寄件 (含當日)
778
+
779
+ ### 海外建單專用欄位
780
+
781
+ | 參數 | 必填 | 說明 |
782
+ |------|------|------|
783
+ | `ReceiverCountry` | ● | 國家代碼 (英文),依「查詢國家代碼 API」CountryId |
784
+ | `ReceiverCode` | ● | 收件人宅配郵編,香港帶 `00000`、澳門帶 `999078`,不可含特殊符號 |
785
+ | `Weight` | ● | 重量 (kg),可帶小數點 |
786
+ | `Length` | ● | 外箱長 (cm) |
787
+ | `Width` | ● | 外箱寬 (cm) |
788
+ | `Height` | ● | 外箱高 (cm) |
789
+ | `Description` | ● | 包裹英文名稱 (僅英文/數字) |
790
+
791
+ `Receiver_Phone` 國碼規則:
792
+
793
+ - 香港:`852` + 純數字手機
794
+ - 澳門:`853` + 純數字手機
795
+ - 泰國店取:純 10 位數字、`0` 開頭、不含國碼
796
+
797
+ `Receiver_address`:
798
+
799
+ - 新馬/中港澳:可中文,長度 ≤ 150
800
+ - 其他國家:必填英文,長度 ≤ 135 byte
801
+
802
+ ### 列印標籤
803
+
804
+ ```
805
+ GET /api/OverSeas711Order?orderNumberStr=ORDER1,ORDER2,...
806
+ ```
807
+
808
+ | 參數 | 必填 | 說明 |
809
+ |------|------|------|
810
+ | `orderNumberStr` | ● | 商家訂單編號,逗號分隔,一次最多 100 筆 |
811
+
812
+ 回傳格式:
813
+
814
+ ```
815
+ S,https://... (成功,導向列印畫面或下載 Excel)
816
+ F,錯誤訊息
817
+ ```
818
+
819
+ > 多筆列印會下載 Excel,錯誤訂單放在 `NoShipNo` 工作表。
820
+
821
+ ### 查詢國家代碼
822
+
823
+ ```
824
+ POST /api/OverSeas711Order/SelCountryID
825
+ ```
826
+
827
+ JsonOrder Content:
828
+
829
+ ```json
830
+ { "user_account": "28229955", "apicode": "12345678" }
831
+ ```
832
+
833
+ Response 範例:
834
+
835
+ ```json
836
+ {
837
+ "Status": "S",
838
+ "ErrorMsg": "",
839
+ "Detail": [
840
+ { "CountryId": "AD", "ChineseName": "安道爾", "EnglishName": "Andorra" },
841
+ { "CountryId": "AF", "ChineseName": "阿富汗", "EnglishName": "Afghanistan" }
842
+ ]
843
+ }
844
+ ```
845
+
846
+ ### 查詢物流重量費用
847
+
848
+ ```
849
+ POST /api/Orderapi/SelWeightChart
850
+ ```
851
+
852
+ JsonOrder Content:
853
+
854
+ ```json
855
+ {
856
+ "user_account": "28229955",
857
+ "apicode": "12345678",
858
+ "LogisticServiceID": "08",
859
+ "LogisticServiceID2": "",
860
+ "CountryID": "US"
861
+ }
862
+ ```
863
+
864
+ Response Detail:
865
+
866
+ | 欄位 | 說明 |
867
+ |------|------|
868
+ | `Country` | 國家代碼 |
869
+ | `Weight` | 包裹重量 (kg),例:`0.5KG` |
870
+ | `Cost` | 費用 (decimal(8,2)),不含 5% 營業稅 |
871
+ | `FeeMode` | `0`:正常 / `1`:偏遠 |
872
+ | `Pay` | `0`:一般 `1`:經濟 `2`:空運 `3`:運費到付 `4`:其他 |
873
+ | `DeliveryMethod` | `0`:店配 `1`:宅配 |
874
+
875
+ ### 查詢寄送包裹費用明細
876
+
877
+ 兩種查法 (擇一):
878
+
879
+ ```
880
+ POST /api/OverSeas711Order/SelBillDetail (依訂單)
881
+ POST /api/OverSeas711Order/SelBillDetailDate (依日期 yyyy-MM-dd)
882
+ ```
883
+
884
+ 每週四更新帳務,可查詢至上週整週帳務 (含結束日期當日)。
885
+
886
+ ---
887
+
888
+ ## 全家大宗物流
889
+
890
+ 服務代碼:`04` / 文件版本:`FamilyBulk V2.4`
891
+
892
+ 流程與 7-11 大宗類似,但全家大宗:
893
+
894
+ - 建單時 `Logistic_service=04`、`Deadline` 為 1~7
895
+ - `Sender_Name`、`Sender_Phone` 可填空字串自動帶入「立吉富」/「0900000000」
896
+ - 列印 API:`/api/Order711` 之外另有 `/api/OrderFamiC2C` (依產品線)
897
+
898
+ > 全家大宗的後續取出貨單號流程與 7-11 大宗一致,請依官方 SDK 接續。
899
+
900
+ ---
901
+
902
+ ## 全家冷凍大宗 B2C
903
+
904
+ 服務代碼:`24` / 文件版本:`FamilyFreezingBulkB2C V2.6`
905
+
906
+ ### 與其他物流關鍵差異
907
+
908
+ 1. **店鋪保留機制**:選店後 PayNow 會給予 3 小時暫留,3 小時內必須打 `/api/FamiFreezingB2C/UpSpaceConfirm` 確認,否則取消
909
+ 2. 訂單需在電子地圖回傳的 `ShipDate` 前一天建立完成並列印
910
+ 3. 重選店鋪:原訂單若已確認過店鋪空間,需先取消才能重選
911
+ 4. 電子地圖必須帶入材積 `Length`/`Wide`/`High`/`Weight` 與出貨日 `StartDate`/`EndDate`
912
+
913
+ ### 店鋪空間保留 / 取消
914
+
915
+ ```
916
+ POST /api/FamiFreezingB2C/UpSpaceConfirm
917
+ ```
918
+
919
+ 使用情境:
920
+
921
+ - 新增訂單前需先保留空間才可成功建單
922
+ - 重選店舖若已保留過需先取消再保留新編號
923
+ - 最終未出貨訂單需取消保留
924
+
925
+ 電子地圖 (Logistic_serviceID=24) 將回傳 `ReservedNo` 與 `ShipDate`,後續建單必須帶入 `ReservedNo`。
926
+
927
+ ### 材積申請類別
928
+
929
+ | 類別 | 限制 |
930
+ |------|------|
931
+ | `S60` | 長+寬+高 < 60 cm |
932
+ | `S105` | 長+寬+高 < 105 cm |
933
+
934
+ ---
935
+
936
+ ## 全家冷凍店到店 (C2C)
937
+
938
+ 服務代碼:`23` / 文件版本:`FamilyFreezingC2C V2.2`
939
+
940
+ ### 流程
941
+
942
+ 1. 電子地圖 (`Logistic_serviceID=23`) 選店,回傳 `ReservedNo` + `ShipDate`
943
+ 2. 建單帶入 `ReservedNo`、`Logistic_service=23`
944
+ 3. 列印全家店到店冷凍物流單
945
+ 4. 依電子地圖回傳的 `ShipDate` 進行出貨
946
+ 5. 寄貨外箱須於全家購買 (My FamiPort APP 預購寄件專用紙箱)
947
+
948
+ ### 建單必填差異
949
+
950
+ `ReservedNo` 為必填,其他欄位與通用建單一致。回傳會包含 `paymentno`:
951
+
952
+ ```json
953
+ {
954
+ "Status": "S",
955
+ "LogisticNumber": "...",
956
+ "LogisticService": "全家店到店冷凍",
957
+ "LogisticServiceID": "23",
958
+ "paymentno": "...",
959
+ "ErrorMsg": null
960
+ }
961
+ ```
962
+
963
+ ---
964
+
965
+ ## 四大超商常溫 C2C
966
+
967
+ 服務代碼:`01` (7-11 交貨便) / `03` (全家店到店) / `05` (萊爾富店到店) / `10` (OK 店到店)
968
+ 文件版本:`SuperMarketC2C V2.5`
969
+
970
+ ### 寄件期限
971
+
972
+ | 超商 | 寄件期限 |
973
+ |------|----------|
974
+ | 7-11 / 全家 | 7 天 |
975
+ | 萊爾富 | 5 天 |
976
+ | OK | 15 天 |
977
+
978
+ ### 收件人姓名長度限制
979
+
980
+ | 物流服務 | 長度上限 |
981
+ |----------|----------|
982
+ | 7-11 交貨便 | 10 |
983
+ | 全家店到店 | 30 |
984
+ | 萊爾富店到店 | 20 |
985
+ | OK 店到店 | 10 |
986
+
987
+ ### 列印標籤端點
988
+
989
+ ```
990
+ GET /api/Order711 (7-11)
991
+ GET /api/OrderFamiC2C (全家)
992
+ GET /api/OrderHiLife (萊爾富)
993
+ GET /api/OKC2C (OK)
994
+ ```
995
+
996
+ | 參數 | 必填 | 說明 |
997
+ |------|------|------|
998
+ | `orderNumberStr` | ● | 商家訂單編號 (`OrderNo`),逗號分隔,一次最多 100 筆 |
999
+ | `user_account` | ● | |
1000
+
1001
+ 回傳:`S,網址` 或 `F,錯誤訊息`。
1002
+
1003
+ ### 重新取號特別規則
1004
+
1005
+ - **萊爾富需在訂單成立 30 分鐘後才能進行重新取號**
1006
+ - 7-11、全家、OK 在訂單成立後即可重取
1007
+
1008
+ ### 全家 C2C 店號轉換
1009
+
1010
+ ```
1011
+ GET /api/OrderFamiC2C/GetFamiStoreID?storeId=017206&IDtype=1
1012
+ ```
1013
+
1014
+ | 參數 | 必填 | 說明 |
1015
+ |------|------|------|
1016
+ | `storeId` | ● | 店號 (6 碼) |
1017
+ | `IDtype` | ● | `1`:轉成現行店號 / `2`:轉成原始店號 |
1018
+
1019
+ Response:
1020
+
1021
+ ```json
1022
+ { "storeId": "017206", "IDtype": "1", "Error": "" }
1023
+ ```
1024
+
1025
+ ### 7-11 交貨便建單回傳範例
1026
+
1027
+ ```json
1028
+ {
1029
+ "Status": "S",
1030
+ "LogisticNumber": "MIJA0027C22112026083",
1031
+ "LogisticService": "7-11交貨便",
1032
+ "LogisticServiceID": "01",
1033
+ "paymentno": "L9991156",
1034
+ "validationno": "0497",
1035
+ "ReturnMsg": "",
1036
+ "orderno": "211202115804",
1037
+ "ErrorMsg": null
1038
+ }
1039
+ ```
1040
+
1041
+ `paymentno` + `validationno` 可至 7-11 Ibon 機台輸入列印。
1042
+
1043
+ ---
1044
+
1045
+ ## 黑貓宅配
1046
+
1047
+ 服務代碼:`06` (黑貓宅急便) / `36` (黑貓宅急便 PayNow) / 文件版本:`BlackCat-Home-Delivery V2.1`
1048
+
1049
+ ### 流程
1050
+
1051
+ 1. 將訂單資料組成 JSON 字串 POST 到 `/api/Orderapi/Add_Order`
1052
+ 2. 成功後到 `/Member/Order/PrintBlackCatLabel` 列印標籤
1053
+ 3. 出貨日將商品準備好,黑貓上門取貨
1054
+
1055
+ ### 黑貓宅配專用欄位
1056
+
1057
+ | 參數 | 必填 | 說明 |
1058
+ |------|------|------|
1059
+ | `Description` | 否 | 商品類別代碼 (見下表),未填預設 `0015` |
1060
+ | `DeliverMode` | ● | `01`:取貨付款 `02`:取貨不付款 (保險單須為 `02`) |
1061
+ | `Logistic_service` | ● | `06`:黑貓宅急便 / `36`:黑貓宅急便 (PayNow 自動保險) |
1062
+ | `TotalAmount` | ● | 不可大於 100,000 |
1063
+ | `Deadline` | ● | 0~6;當日出貨帶 `0`,過 16:00 則出貨日為明日;週日/連假順延 |
1064
+ | `Length` / `Wide` / `High` | ● | 長+寬+高 ≤ 150 cm |
1065
+ | `Weight` | ● | 商品總重量 (kg) ≤ 20 kg |
1066
+ | `Sender_Tel` | 否 | 寄件人市話 |
1067
+ | `Receiver_Tel` | 否 | 收件人市話 |
1068
+ | `ExpectDeliverTime` | 否 | `1`:13:00 前 / `2`:14:00-18:00 / `4`:不固定 (預設 `4`) |
1069
+ | `ExpectDeliverDate` | 否 | `yyyy-MM-dd`,最大為建單日 + 6 天,未帶自動為出貨日 D+1 |
1070
+ | `DeliveryType` | ● | `0001`:常溫 `0002`:冷藏 `0003`:冷凍 |
1071
+ | `IsInsurance` | 否 | bool;有保險的單填 `true`,預設 `false` |
1072
+
1073
+ > 服務代號 `36` 的單**無須帶入 `IsInsurance`**,總金額超過 20,000 會自動投保 (保額為商品金額)。
1074
+
1075
+ ### Description 商品類別代碼 (黑貓專用)
1076
+
1077
+ | 代碼 | 類別 |
1078
+ |------|------|
1079
+ | `0001` | 一般食品 |
1080
+ | `0002` | 名特產/甜產印單 |
1081
+ | `0003` | 酒/油/醋/醬 |
1082
+ | `0004` | 穀物蔬果 |
1083
+ | `0005` | 水產/肉品 |
1084
+ | `0006` | 3C |
1085
+ | `0007` | 家電 |
1086
+ | `0008` | 服飾配件 |
1087
+ | `0009` | 生活用品 |
1088
+ | `0010` | 美容彩妝 |
1089
+ | `0011` | 保健食品 |
1090
+ | `0012` | 醫療相關用品 |
1091
+ | `0013` | 寵物用品飼料 |
1092
+ | `0014` | 印刷品 |
1093
+ | `0015` | 其他 (預設) |
1094
+
1095
+ ### 建單範例
1096
+
1097
+ ```json
1098
+ {
1099
+ "DeliverMode": "01",
1100
+ "Description": "0001",
1101
+ "Logistic_service": "06",
1102
+ "OrderNo": "123456789",
1103
+ "Receiver_address": "台北市北投區承德路六段2號",
1104
+ "Receiver_Email": "12345678@gmail.com",
1105
+ "Receiver_Name": "王O明",
1106
+ "Receiver_Phone": "0912345678",
1107
+ "Remark": "備註",
1108
+ "Sender_address": "台北市中山區松江路207號9樓",
1109
+ "Sender_Email": "12345678@gmail.com",
1110
+ "Sender_Name": "李O富",
1111
+ "Sender_Phone": "0912345678",
1112
+ "Sender_Tel": "0225215088",
1113
+ "Receiver_Tel": "0225215088",
1114
+ "apicode": "12345678",
1115
+ "TotalAmount": "100",
1116
+ "user_account": "28229955",
1117
+ "DeliveryType": "0001",
1118
+ "PassCode": "2FC3805A8BEEC525F2EDF74B75E7FCE83C980856",
1119
+ "Deadline": "1",
1120
+ "Length": "30",
1121
+ "Wide": "30",
1122
+ "High": "30",
1123
+ "Weight": "5"
1124
+ }
1125
+ ```
1126
+
1127
+ Response:
1128
+
1129
+ ```json
1130
+ {
1131
+ "Status": "S",
1132
+ "LogisticNumber": "ABCD123456",
1133
+ "LogisticService": "黑貓宅急便",
1134
+ "LogisticServiceID": "06",
1135
+ "paymentno": "12345678",
1136
+ "ReturnMsg": "",
1137
+ "orderno": "12345678",
1138
+ "ErrorMsg": ""
1139
+ }
1140
+ ```
1141
+
1142
+ ### 列印黑貓宅急便標籤
1143
+
1144
+ ```
1145
+ POST /Member/Order/PrintBlackCatLabel
1146
+ ```
1147
+
1148
+ | 參數 | 必填 | 說明 |
1149
+ |------|------|------|
1150
+ | `LogisticNumbers` | ● | `物流單號_序號`,多筆以 `,` 分隔 |
1151
+
1152
+ ---
1153
+
1154
+ ## 黑貓店到店
1155
+
1156
+ 服務代碼:`46` / 文件版本:`BlackCat-Home-Delivery V1.1`
1157
+
1158
+ ### 流程
1159
+
1160
+ 1. 選擇物流服務 (`Logistic_serviceID=46`) 取得門市資料
1161
+ 2. 完善訂單資料後組成 JSON 字串 POST 到 `/api/Orderapi/Add_Order`
1162
+ 3. 成功後到列印黑貓店到店標籤
1163
+ 4. 將商品準備好打電話給黑貓上門取貨開始配送流程
1164
+
1165
+ ### 與宅配的差異
1166
+
1167
+ | 項目 | 黑貓宅配 (06/36) | 黑貓店到店 (46) |
1168
+ |------|-----------------|-----------------|
1169
+ | 收件方式 | 收件人地址 | 取件門市 (`receiver_storeid`/`receiver_storename`) |
1170
+ | `TotalAmount` 上限 | 100,000 | 20,000 |
1171
+ | 長+寬+高上限 | ≤ 150 cm | ≤ 105 cm |
1172
+ | `Sender_Phone`/`Sender_Tel` | 可填空字串自動帶 `0900000000` | 需明確填值 |
1173
+ | `Description` | 商品類別代碼 | 自由文字 |
1174
+
1175
+ ### 必填欄位
1176
+
1177
+ `Logistic_service=46`、`receiver_storeid`、`receiver_storename`、`return_storeid` (可填空字串)、`Length`/`Wide`/`High` (≤ 105 cm)、`DeliveryType` (常溫/冷藏/冷凍)。
1178
+
1179
+ ---
1180
+
1181
+ ## 查詢物流單
1182
+
1183
+ ### 依 PayNow 物流單號
1184
+
1185
+ ```
1186
+ GET /api/Orderapi/Get_Order_Info?LogisticNumber=...&sno=1
1187
+ ```
1188
+
1189
+ ### 依商家訂單編號
1190
+
1191
+ ```
1192
+ GET /api/Orderapi/Get_Order_Info_orderno?orderno=...&user_account=...&sno=1
1193
+ ```
1194
+
1195
+ ### Response
1196
+
1197
+ | 參數 | 說明 |
1198
+ |------|------|
1199
+ | `LogisticNumber` | PayNow 物流單號 |
1200
+ | `sno` | 物流單序號 (固定 1) |
1201
+ | `orderno` | 商家訂單編號 |
1202
+ | `Logistic_Serviece` | 物流服務代碼 (注意官方拼字) |
1203
+ | `Status` | `0`:成立中 `1`:無效訂單 |
1204
+ | `Delivery_Status` | 流程狀態文字描述 |
1205
+ | `PayNowLogisticCode` | 4 位數 PayNow 物流貨態代碼 |
1206
+ | `Detail_Status_Description` | 貨態詳細描述 |
1207
+ | `paymentno` | 物流商託運單號 |
1208
+ | `validationno` | 驗證碼 (7-11 店到店類有值) |
1209
+ | `ErrorMsg` | 錯誤訊息,成功為 `null` |
1210
+
1211
+ ### 範例
1212
+
1213
+ ```json
1214
+ {
1215
+ "LogisticNumber": "MIJA0027R22203232824",
1216
+ "orderno": "220323105411",
1217
+ "Logistic_Serviece": "21",
1218
+ "Status": "0",
1219
+ "Delivery_Status": "等待寄件",
1220
+ "PayNowLogisticCode": "0000",
1221
+ "Detail_Status_Description": "訂單已成立 等待出貨",
1222
+ "sno": "1",
1223
+ "ErrorMsg": null,
1224
+ "paymentno": "D8273267",
1225
+ "validationno": "9066"
1226
+ }
1227
+ ```
1228
+
1229
+ ---
1230
+
1231
+ ## 取消物流單
1232
+
1233
+ ```
1234
+ DELETE /api/Orderapi/CancelOrder
1235
+ Content-Type: application/x-www-form-urlencoded
1236
+ ```
1237
+
1238
+ | 參數 | 必填 | 說明 |
1239
+ |------|------|------|
1240
+ | `LogisticNumber` | ● | PayNow 物流單號 |
1241
+ | `sno` | ● | 物流單序號 (固定 1) |
1242
+ | `PassCode` | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
1243
+
1244
+ ### Response (純字串)
1245
+
1246
+ ```
1247
+ S,訂單已取消
1248
+ F,訂單取消失敗 失敗原因: <原因>
1249
+ ```
1250
+
1251
+ ### 限制
1252
+
1253
+ - 出貨中的大宗訂單無法使用此 API
1254
+
1255
+ ---
1256
+
1257
+ ## 重新取號
1258
+
1259
+ ```
1260
+ POST /api/Orderapi/ReNewOrder
1261
+ Content-Type: application/x-www-form-urlencoded
1262
+ ```
1263
+
1264
+ JsonOrder Content:
1265
+
1266
+ | 參數 | 必填 | 說明 |
1267
+ |------|------|------|
1268
+ | `user_account` | ● | |
1269
+ | `LogisticNumber` | ● | 原 PayNow 物流單號 |
1270
+ | `sno` | ● | 物流單序號 |
1271
+ | `OrderNo` | ● | 商家原始訂單編號 |
1272
+ | `TotalAmount` | ● | 訂單總金額 |
1273
+ | `apicode` | ● | |
1274
+ | `PassCode` | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
1275
+
1276
+ ### Response
1277
+
1278
+ ```json
1279
+ {
1280
+ "Status": "S",
1281
+ "LogisticNumber": "MIJA0027B22112100002",
1282
+ "OrderNo": "211210165125",
1283
+ "paynoworderno": "211210165125",
1284
+ "sno": "1",
1285
+ "paymentno": "82900502031",
1286
+ "validationno": "1600",
1287
+ "Status": "S",
1288
+ "ErrorMsg": null
1289
+ }
1290
+ ```
1291
+
1292
+ > `paynoworderno` 為**新的訂單編號**:超過寄件期限 (7-11=5 天 / 全家=當天 / 萊爾富=5 天) 重取會產生新編號,請以 `paynoworderno` 作為後續批次列印與查詢的訂單編號。
1293
+
1294
+ ### 各物流重取規則
1295
+
1296
+ | 物流 | 規則 |
1297
+ |------|------|
1298
+ | 7-11 大宗 (`02`) | 物流驗收後且未取貨;貨態 `1000`/`1050`/`8000` 無法重取 |
1299
+ | 7-11 冷凍大宗 (`22`) | 同上 |
1300
+ | 萊爾富店到店 (`05`) | 訂單成立 30 分鐘後才能重取 |
1301
+ | 全家店到店 (`03`) | 規定日期 = 物流單成立日 + 0 天 (即當天) |
1302
+ | 7-11 海外配送 | 已獲取出貨單號且訂單成立中、買家尚未取貨 |
1303
+
1304
+ ---
1305
+
1306
+ ## 門市更新 (關轉)
1307
+
1308
+ ```
1309
+ PUT /api/Orderapi/Put
1310
+ Content-Type: application/x-www-form-urlencoded
1311
+ ```
1312
+
1313
+ 「關轉」是指進行出貨後因各種狀況 (門市關店、轉店等) 無法將包裹配達指定門市,需請商家/消費者更換取件門市。
1314
+
1315
+ ### 各物流關轉時限
1316
+
1317
+ | 物流 | 觸發貨態代碼 | 關轉時限 |
1318
+ |------|-------------|---------|
1319
+ | 7-11 大宗 (`02`) | `4036` | D+2 上午 11:20 前 |
1320
+ | 7-11 冷凍大宗 (`22`) | `4036` | D+2 上午 10:50 前 |
1321
+ | 7-11 冷凍 C2C (`21`) | `7101`/`7104`/`7201`/`7204` | D+7 內 |
1322
+ | 4 大超商 C2C | `7101`/`7104`/`7201`/`7204` | D+7 內 |
1323
+
1324
+ ### Request
1325
+
1326
+ | 參數 | 必填 | 說明 |
1327
+ |------|------|------|
1328
+ | `UpdateOrder` | ● | 物流單資料 (JSON 字串) |
1329
+ | `LogisticNumber` | ● | PayNow 物流單號 |
1330
+ | `sno` | ● | 物流單序號 (固定 1) |
1331
+ | `ChangeType` | ● | `01`:取件門市更新 / `02`:退件門市更新 |
1332
+ | `NewStoreId` | ● | 新門市店號 |
1333
+ | `NewStoreName` | ● | 新門市名稱 |
1334
+ | `PassCode` | ● | SHA-1(`user_account + OrderNo + TotalAmount + apicode`) |
1335
+
1336
+ 範例:
1337
+
1338
+ ```json
1339
+ {
1340
+ "LogisticNumber": "MIJA0027B22112100002",
1341
+ "sno": "1",
1342
+ "ChangeType": "01",
1343
+ "NewStoreId": "863698",
1344
+ "NewStoreName": "豫銘門市",
1345
+ "PassCode": "4CF47FD844DF64C5D0FBF8DD134708B55ABE208B"
1346
+ }
1347
+ ```
1348
+
1349
+ ### Response (純字串)
1350
+
1351
+ ```
1352
+ S,更新成功
1353
+ F,失敗原因: <原因>
1354
+ ```
1355
+
1356
+ ---
1357
+
1358
+ ## 物流貨態回傳 (Callback)
1359
+
1360
+ PayNow 在物流貨態變更時,會以 HTTP POST 將最新狀態送至商家事先設定的回傳網址。
1361
+
1362
+ ### Request 參數
1363
+
1364
+ | 參數 | 名稱 | 型態 | 長度 | 必填 | 說明 |
1365
+ |------|------|------|------|------|------|
1366
+ | `orderno` | 商家自訂編號 | string | 30 | ● | 重取後可能與原始不同 |
1367
+ | `OriginOrderno` | 商家原始自訂單號 | string | 27 | ● | |
1368
+ | `PayNowLogisticCode` | 物流代碼 | string | 4 | ● | 4 碼,例:`5000`/`8000` |
1369
+ | `Detail_Status_Description` | 物流狀態描述 | string | | ● | |
1370
+ | `paymentno` | 物流商託運單號 | string | | ● | |
1371
+ | `StoreDate` | 到店日期 | string | | 否 | 若代碼為 `5000`/`5001` 則填實際到店日期 |
1372
+ | `StoreTime` | 到店時間 | string | | 否 | 同上 |
1373
+
1374
+ ### 處理範例 (PHP)
1375
+
1376
+ ```php
1377
+ <?php
1378
+
1379
+ // 接收 PayNow 物流回傳
1380
+ $logisticCode = $_POST['PayNowLogisticCode'] ?? '';
1381
+ $orderNo = $_POST['OriginOrderno'] ?? '';
1382
+
1383
+ switch ($logisticCode) {
1384
+ case '0000':
1385
+ updateOrderStatus($orderNo, 'pending'); // 訂單已成立 等待出貨
1386
+ break;
1387
+ case '5000':
1388
+ updateOrderStatus($orderNo, 'arrived_at_store'); // 取件門市配達
1389
+ break;
1390
+ case '5001':
1391
+ updateOrderStatus($orderNo, 'arrived_at_return'); // 退件門市配達
1392
+ break;
1393
+ case '8000':
1394
+ updateOrderStatus($orderNo, 'picked_up'); // 買家已取件
1395
+ break;
1396
+ case '8001':
1397
+ updateOrderStatus($orderNo, 'returned'); // 退貨成功
1398
+ break;
1399
+ case '4036':
1400
+ notifyMerchantStoreClosure($orderNo); // 門市關轉,需更新門市
1401
+ break;
1402
+ case '9411':
1403
+ notifyMerchantStuck($orderNo); // 貨態停滯
1404
+ break;
1405
+ default:
1406
+ logUnknownStatus($orderNo, $logisticCode);
1407
+ }
1408
+
1409
+ http_response_code(200);
1410
+ echo 'OK';
1411
+ ```
1412
+
1413
+ > 注意:PayNow 文件未明確規範 callback 的應答格式,建議回傳 HTTP 200 + 任意文字,並由商家自行做 PassCode 比對 (官方文件未要求 callback 帶 PassCode)。
1414
+
1415
+ ---
1416
+
1417
+ ## 貨態代碼對照表
1418
+
1419
+ PayNow 物流貨態代碼為 4 位數字,依物流商有不同涵義;以下為主要代碼匯總。
1420
+
1421
+ ### 共通代碼
1422
+
1423
+ | 代碼 | 說明 |
1424
+ |------|------|
1425
+ | `0000` | 訂單已成立 等待出貨 |
1426
+ | `0001` | 訂單已成立 等待退貨 |
1427
+ | `0101` | 商品已到寄件門市 |
1428
+ | `0102` | 門市已更新寄件中 |
1429
+ | `0103` | 門市已更新退件中 |
1430
+ | `4000` | 進驗成功 |
1431
+ | `5000` | 取件門市配達 |
1432
+ | `5001` | 退件門市配達 |
1433
+ | `8000` | 買家已取件 |
1434
+ | `8001` | 退貨成功 |
1435
+ | `8100` | 賣家已取件 |
1436
+ | `9411` | 貨態停滯 |
1437
+
1438
+ ### 7-11 大宗物流 (`02`)
1439
+
1440
+ | 代碼 | 說明 |
1441
+ |------|------|
1442
+ | `1000` | 訂單檔案上傳中 |
1443
+ | `1050` | 物流訂單上傳成功 |
1444
+ | `1071`~`1075` | XML/檔案異常 (請聯繫系統商) |
1445
+ | `1080` | 門市店號轉換成功 |
1446
+ | `2001`~`2017` | XML 內容、出貨單號、出貨日期格式問題 |
1447
+ | `2107` | 母廠商不存在 |
1448
+ | `2108` | 子廠商不存在 |
1449
+ | `2110` | 門市已關轉 |
1450
+ | `2118` | 代收金超過上限 |
1451
+ | `2120` | XML 格式不符合規定 |
1452
+ | `3001` | 物流作業驗收中 |
1453
+ | `3002` | 門市已更新店號 |
1454
+ | `3101` | 無此門市將進行退貨 |
1455
+ | `3102` | 六、日門市不配送 |
1456
+ | `3103` | 門市關轉店 |
1457
+ | `3104` | 門市尚未開店 |
1458
+ | `3105` | 曾經重複出貨,無法出貨 |
1459
+ | `4003` | 商品捆包 |
1460
+ | `4004` | 商品外帶透明 |
1461
+ | `4005` | 商品多標籤 |
1462
+ | `4031` | 商品破損退貨中 |
1463
+ | `4032` | 商品超才退貨中 |
1464
+ | `4033` | 違禁品進行罰款退貨中 |
1465
+ | `4034` | 同一個訂單兩包商品資料重複 |
1466
+ | `4035` | 已過門市進貨日 |
1467
+ | `4036` | 門市關轉請更新門市 (D+2 11:20 前關轉) |
1468
+ | `4037` | 條碼規格錯誤 |
1469
+ | `4038` | 條碼無法判讀 |
1470
+ | `4039` | 無標籤 |
1471
+ | `4060` | 物流中心理貨中 |
1472
+ | `4061` | 商品遺失 |
1473
+ | `4062` | 門市不配送 |
1474
+ | `4063` | 包裹異常不配送 |
1475
+ | `4099` | 不正常到貨,商品提早到達物流中心 |
1476
+ | `5011`~`5017` | 配送異常 (作業/車輛/天候/道路/門市) |
1477
+ | `5102` | 管制品取件門市配達 |
1478
+ | `5201` | EC 收退 |
1479
+ | `5202` | 交貨便收件 |
1480
+ | `5203` | 退貨便收件 |
1481
+ | `5303` | 取件遺失進行賠償作業 |
1482
+ | `6001` | 第一次開退 |
1483
+ | `7001` | 正常一退 |
1484
+ | `7002` | 正常二退 |
1485
+ | `7011`~`7022` | 退貨原因細項 (商品瑕疵/門市/廠商/消費者) |
1486
+ | `8003`~`8005` | 商品異常 (捆包/外帶透明/多標籤) |
1487
+ | `8011`~`8022` | 退貨成功原因細項 |
1488
+ | `8031`~`8039` | 商品異常退貨 (破損/超才/違禁/重複/條碼) |
1489
+ | `8099` | 不正常到貨,商品提早到達物流中心 |
1490
+ | `8110` | 賣家已取件-代收金額錯誤 |
1491
+
1492
+ ### 7-11 大宗退貨便 (`12`)
1493
+
1494
+ | 代碼 | 說明 |
1495
+ |------|------|
1496
+ | `0001` | 訂單已成立 等待退貨 |
1497
+ | `0101` | 商品已到寄件門市 |
1498
+ | `7001` | 正常一退 |
1499
+ | `8001` | 退貨成功 |
1500
+
1501
+ ### 7-11 冷凍 C2C (`21`)
1502
+
1503
+ | 代碼 | 說明 |
1504
+ |------|------|
1505
+ | `0` | 訂單已成立 等待寄件中 |
1506
+ | `101` | 商品已到寄件門市 |
1507
+ | `102` | 門市已更新寄件中 |
1508
+ | `103` | 門市已更新退件中 |
1509
+ | `4034` | 同一個訂單兩包商品資料重複 |
1510
+ | `4060` | 物流中心理貨中 |
1511
+ | `4063` | 包裹異常不配送 |
1512
+ | `4064` | 取消寄件再次寄送 (直接轉 C 店) |
1513
+ | `4065` | 提早轉 C 店 - 廠商因素 |
1514
+ | `4066` | 提早轉 C 店 - 超商因素 |
1515
+ | `4075` | 包裹異常進入判賠程序 |
1516
+ | `4076` | 包裹已送達物流中心,即將配送至指定門市 |
1517
+ | `4077` | 無退件門市資料 |
1518
+ | `4078` | 包裹等待配送中 |
1519
+ | `4079` | 包裹進行配送中 |
1520
+ | `5018` | 寄件貨態異常協尋中 |
1521
+ | `5019` | 取件包裹異常協尋中 |
1522
+ | `5021` | 物流中心暫報缺 |
1523
+ | `5022` | 驗收前包裹異常 |
1524
+ | `5301` | 取消寄件 |
1525
+ | `5302` | 寄件遺失進行賠償程序 |
1526
+ | `6002` | 待退貨請盡速取件 |
1527
+ | `7101` | 取件門市關轉店 |
1528
+ | `7102` | 取件門市舊店號更新 |
1529
+ | `7104` | 取件門市臨時關轉店 |
1530
+ | `7201` | 退件門市關轉店 |
1531
+ | `7202` | 退件門市舊店號更新 |
1532
+ | `7203` | 退件門市無取件門市資料 |
1533
+ | `7204` | 退件門市臨時關轉店 |
1534
+ | `8077` | 退至 7 總倉 |
1535
+ | `8305` | 已送宅配 |
1536
+ | `8306` | 放 7 天後拋棄 |
1537
+
1538
+ ### 7-11 海外配送 (`07`/`08`)
1539
+
1540
+ | 代碼 | 說明 |
1541
+ |------|------|
1542
+ | `0000` | 訂單已成立 等待出貨 |
1543
+ | `5000` | 門市配達 |
1544
+ | `5401` | 提單成立 |
1545
+ | `5402` | 已入倉 |
1546
+ | `5403` | 出口作業中 |
1547
+ | `5404` | 已出倉 |
1548
+ | `5405` | 清關中 |
1549
+ | `5406` | 派送中 |
1550
+ | `5407` | 取消 |
1551
+ | `5408` | 問題單 |
1552
+ | `5409` | 退件包裹 |
1553
+ | `5410` | 店取未取轉宅配失敗 |
1554
+ | `5411` | 宅配失敗 |
1555
+ | `5412` | 台灣海關檢查不通過 |
1556
+ | `5413` | 標籤異常/包裝異常/訂單異常取消 |
1557
+ | `5414` | 貨件遺失 |
1558
+ | `5415` | 包裹異常 (件數不對/超材) |
1559
+ | `8000` | 買家已取件 |
1560
+
1561
+ ### 全家代碼 (差異部份)
1562
+
1563
+ | 代碼 | 說明 |
1564
+ |------|------|
1565
+ | `4067` | 小物流遺失 |
1566
+ | `4068` | 門市遺失 |
1567
+ | `4069` | 包裝廠不良 (滲漏) |
1568
+ | `4070` | 門市反應商品包裝不良 (滲漏) |
1569
+ | `4071` | 門市關店 |
1570
+ | `4072` | 條碼資料重複 |
1571
+ | `4073` | 7 日內未寄件單號失效 |
1572
+ | `4074` | 貨物進店後發生異常提早退貨 |
1573
+ | `5200` | 商品運送中 |
1574
+ | `6004` | 商品退回物流中心 |
1575
+ | `8002` | 退至全家總倉 |
1576
+ | `8010` | 買家已取件-代收金額錯誤 |
1577
+ | `8020` | 買家已取件商品有誤 |
1578
+
1579
+ ### 萊爾富代碼 (差異部份)
1580
+
1581
+ | 代碼 | 說明 |
1582
+ |------|------|
1583
+ | `4067` | 小物流遺失 |
1584
+ | `4068` | 門市遺失 |
1585
+ | `4069` | 包裝廠不良 (滲漏) |
1586
+ | `4070` | 門市反應商品包裝不良 (滲漏) |
1587
+ | `4071` | 門市關店 |
1588
+ | `4073` | 7 日內未寄件單號失效 |
1589
+ | `4074` | 貨物進店後發生異常提早退貨 |
1590
+ | `8079` | 退至萊爾富總倉 |
1591
+
1592
+ ### OK 代碼 (差異部份)
1593
+
1594
+ | 代碼 | 說明 |
1595
+ |------|------|
1596
+ | `4030` | 無進貨資料 |
1597
+ | `4031` | 商品破損退貨中 |
1598
+ | `4032` | 商品超才退貨中 |
1599
+ | `4040` | 條碼資料錯誤 |
1600
+ | `4069` | 包裝廠不良 (滲漏) |
1601
+ | `4070` | 門市反應商品包裝不良 |
1602
+ | `4074` | 貨物進店後發生異常提早退貨 |
1603
+ | `8076` | 退至 OK 總倉 |
1604
+
1605
+ ### 貨態流轉範例
1606
+
1607
+ 7-11 大宗 - 一般出貨 (成功取件):
1608
+ ```
1609
+ 1000 → 1050 → 3001 → 4000 → 5000 → 8000
1610
+ ```
1611
+
1612
+ 7-11 大宗 - 退貨成功:
1613
+ ```
1614
+ 1000 → 1050 → 3001 → 4000 → 5000 → 6001 → 5201 → 7001 → 8001
1615
+ ```
1616
+
1617
+ 7-11 大宗 - 門市關轉 (更新後成功):
1618
+ ```
1619
+ 1000 → 1050 → 3101 → 4036 → 1080 → 5000 → 8000
1620
+ ```
1621
+
1622
+ 7-11 海外配送 (店配,成功取件):
1623
+ ```
1624
+ 5401 → 5402 → 5405 → 5406 → 5000 → 8000
1625
+ ```
1626
+
1627
+ 7-11 海外配送 (宅配,成功取件):
1628
+ ```
1629
+ 5401 → 5402 → 5405 → 5406 → 8000
1630
+ ```
1631
+
1632
+ 四大超商 C2C - 一般出貨:
1633
+ ```
1634
+ 0101 → 5202 → 4000 → 5000 → 8000
1635
+ ```
1636
+
1637
+ 四大超商 C2C - 退貨成功:
1638
+ ```
1639
+ 0101 → 5202 → 4000 → 5000 → 6002 → 5201 → 7001 → 5001 → 8100
1640
+ ```
1641
+
1642
+ 四大超商 C2C - 二次退貨 (退至總倉):
1643
+ ```
1644
+ 0101 → 4000 → 5000 → 6002 → 4000 → 5001 → 8079 (萊) / 8077 (7) / 8002 (家)
1645
+ ```
1646
+
1647
+ 7-11 冷凍 C2C - 門市關轉 (取件成功):
1648
+ ```
1649
+ 0101 → 7101 / 7104 → 0102 → 4000 → 5000 → 8000
1650
+ ```
1651
+
1652
+ 7-11 冷凍 C2C - 門市關轉 (退件成功):
1653
+ ```
1654
+ 0101 → 5202 → 4000 → 5000 → 7201 / 7203 / 7204 → 0103 → 4000 → 5001 → 8100
1655
+ ```
1656
+
1657
+ ---
1658
+
1659
+ ## 官方資源
1660
+
1661
+ - **官方網站**:https://www.paynow.com.tw/
1662
+ - **官方文件**:https://docs.paynow.com.tw/developer/docs/apipdf/logistics/
1663
+ - **API 端點**:
1664
+ - 正式:`https://logistic.paynow.com.tw`
1665
+ - 測試:`https://testlogistic.paynow.com.tw`
1666
+ - **客服信箱**:service@paynow.com.tw
1667
+
1668
+ ---
1669
+
1670
+ 最後更新:2026/05/07