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,1154 +1,1154 @@
1
- # PChomePay Logistics API Reference
2
-
3
- 拍錢包 (PChomePay) 物流 API 完整參考文件。
4
-
5
- ---
6
-
7
- ## 目錄
8
-
9
- 1. [基本說明](#基本說明)
10
- 2. [環境資訊](#環境資訊)
11
- 3. [認證方式](#認證方式)
12
- 4. [API 端點總覽](#api-端點總覽)
13
- 5. [物流類型分類](#物流類型分類)
14
- 6. [取號列印交寄單](#取號列印交寄單)
15
- 7. [查詢物流歷程](#查詢物流歷程)
16
- 8. [物流歷程查詢頁](#物流歷程查詢頁)
17
- 9. [未出貨/未取貨查詢](#未出貨未取貨查詢)
18
- 10. [物流手續費對帳](#物流手續費對帳)
19
- 11. [賠款查詢](#賠款查詢)
20
- 12. [物流狀態通知](#物流狀態通知)
21
- 13. [錯誤代碼](#錯誤代碼)
22
- 14. [常見問題排解](#常見問題排解)
23
-
24
- ---
25
-
26
- ## 基本說明
27
-
28
- ### PChomePay 物流定位
29
-
30
- 拍錢包 (PChomePay) 與 ECPay、PayUni 等純物流串接平台不同,主打**金流 + 物流二合一**的整合服務:
31
-
32
- - **金流為主軸**:所有物流訂單均由 PChomePay 金流訂單派生,需先以 `pay_type` 為超商取貨類型 (`IPL7` / `IPLFM` / `IPLHL`) 建立金流訂單
33
- - **超商取貨付款**:核心場景為 7-11 / 全家 / 萊爾富之 C2C 店到店服務,買家在付款頁面選擇取件門市
34
- - **無獨立物流單建立 API**:`POST /v1/payment` 建立金流訂單後,物流訂單會自動產生;商家只需呼叫「取號列印交寄單」即可完成取號
35
- - **與信用卡 / ATM 等其他付款方式可共用同套金流流程**:但僅超商取貨類型訂單會觸發物流相關 API
36
-
37
- ### 物流流程概覽
38
-
39
- ```
40
- 1. 建立金流訂單 (pay_type = IPL7/IPLFM/IPLHL)
41
- └─ 用戶在付款頁面選擇超商取件門市
42
- 2. 取得用戶選擇門市資訊 (notify: payment_info_set)
43
- 3. 取號列印交寄單 (POST /v1/logistic/batch)
44
- 4. 將商品交寄至超商
45
- 5. 透過通知 / 查詢 API 監控物流狀態
46
- 6. 用戶取貨完成 → 款項撥付
47
- ```
48
-
49
- ### 交寄期限規定
50
-
51
- 超商取貨訂單須在 **30 天內**完成取號交寄單列印。完成取號列印後(當日為 T),各超商有不同的交寄截止日:
52
-
53
- | 超商 | 交寄期限 | 範例(6/10 取號) |
54
- |------|----------|------------------|
55
- | 7-11 (統一超商) | T + 10 日 | 須在 6/20 23:59 前交寄 |
56
- | 全家 (FamilyMart) | T + 6 日 | 須在 6/16 23:59 前交寄 |
57
- | 萊爾富 (Hi-Life) | T + 7 日 | 須在 6/17 23:59 前交寄 |
58
-
59
- > ⚠ 一旦逾期未交寄,該訂單之物流單將自動失效,需重新處理。
60
-
61
- ---
62
-
63
- ## 環境資訊
64
-
65
- ### Domain Name
66
-
67
- | 環境 | Base URL |
68
- |------|----------|
69
- | **正式環境 (Production)** | `https://api.pchomepay.com.tw` |
70
- | **測試環境 (Sandbox)** | `https://sandbox-api.pchomepay.com.tw` |
71
-
72
- ### 來源 IP 白名單
73
-
74
- 正式與測試環境會透過以下 IP 發送 API Notify:
75
-
76
- ```
77
- 113.196.231.190
78
- ```
79
-
80
- > 商家若有防火牆設定,請將此 IP 加入白名單,否則無法接收物流狀態通知。
81
-
82
- ### Sandbox 測試規則(超商取貨)
83
-
84
- Sandbox 測試環境會根據訂單金額尾數模擬不同物流狀態:
85
-
86
- | 金額尾數 | 模擬狀態 |
87
- |---------|---------|
88
- | 0 / 6 / 7 / 8 / 9 | 已建立 |
89
- | 1 | 已交寄 |
90
- | 2 | 配送中 |
91
- | 3 | 已到店 |
92
- | 4 | 已收款 |
93
- | 5 | 已退件 |
94
-
95
- ### Sandbox 測試門市
96
-
97
- ```
98
- 7-11 測試門市:桃園市桃園區中埔六街 36 號 1 樓 維瀚門市
99
- ```
100
-
101
- ---
102
-
103
- ## 認證方式
104
-
105
- PChomePay 物流 API 與金流 API 共用同一套認證機制。
106
-
107
- ### 認證流程
108
-
109
- ```
110
- [1] APP_ID + SECRET (Basic Auth)
111
- ↓
112
- [2] POST /v1/token → 取得 pcpay-token
113
- ↓
114
- [3] 呼叫物流 API (header: pcpay-token)
115
- ↓
116
- [4] token 8 小時失效 → 重新取得
117
- ```
118
-
119
- ### 步驟 1: 取得 Token
120
-
121
- **端點**
122
-
123
- ```
124
- POST https://api.pchomepay.com.tw/v1/token
125
- ```
126
-
127
- **請求 Header**
128
-
129
- | 欄位 | 必填 | 說明 |
130
- |------|------|------|
131
- | `Authorization` | ● | `Basic base64({APP_ID}:{SECRET})` |
132
- | `Content-Type` | ● | `application/json` |
133
-
134
- **請求 Body**
135
-
136
- 無
137
-
138
- **回應欄位**
139
-
140
- | 欄位 | 必填 | 型態 | 說明 |
141
- |------|------|------|------|
142
- | `token` | ● | String(50) | 取得之 token,後續需放在 header `pcpay-token` |
143
- | `expired_in` | ● | Int | token 失效秒數,預設 28,800 秒 (8 小時) |
144
- | `expired_timestamp` | ● | Int | token 失效之 unix timestamp |
145
-
146
- ### cURL 範例
147
-
148
- ```bash
149
- curl --location --request POST 'https://api.pchomepay.com.tw/v1/token' \
150
- --header 'Authorization: Basic RTIzNjc5QkY2NEFFNDU0RjRDQjY3MTFGQUMzNjp4UGdWTmdXb2I4YkdnRVQyZUJSc25pX3lYRW10cXV0bHhVa19VVXVo' \
151
- --header 'Content-Type: application/json'
152
- ```
153
-
154
- ### PHP 範例
155
-
156
- ```php
157
- <?php
158
-
159
- function getPcpayToken(string $appId, string $secret): array
160
- {
161
- $auth = base64_encode("{$appId}:{$secret}");
162
-
163
- $ch = curl_init();
164
- curl_setopt_array($ch, [
165
- CURLOPT_URL => 'https://api.pchomepay.com.tw/v1/token',
166
- CURLOPT_POST => true,
167
- CURLOPT_POSTFIELDS => '',
168
- CURLOPT_RETURNTRANSFER => true,
169
- CURLOPT_HTTPHEADER => [
170
- "Authorization: Basic {$auth}",
171
- 'Content-Type: application/json',
172
- ],
173
- ]);
174
-
175
- $response = curl_exec($ch);
176
- curl_close($ch);
177
-
178
- return json_decode($response, true);
179
- }
180
-
181
- // 範例回應
182
- // {
183
- // "token": "zHm67sQRuPSO__eiuy2h_lEgtPlS12aVqrcVz3Kc",
184
- // "expired_in": 28800,
185
- // "expired_timestamp": 1474470110
186
- // }
187
- ```
188
-
189
- ### Python 範例
190
-
191
- ```python
192
- import base64
193
- import requests
194
-
195
- def get_pcpay_token(app_id: str, secret: str) -> dict:
196
- credentials = base64.b64encode(f"{app_id}:{secret}".encode()).decode()
197
- headers = {
198
- "Authorization": f"Basic {credentials}",
199
- "Content-Type": "application/json",
200
- }
201
- response = requests.post(
202
- "https://api.pchomepay.com.tw/v1/token",
203
- headers=headers,
204
- )
205
- response.raise_for_status()
206
- return response.json()
207
- ```
208
-
209
- ### Token 使用注意事項
210
-
211
- 1. **不要每次請求都呼叫 `/v1/token`**:請暫存 token 到 8 小時失效再重新取得
212
- 2. **失效時間判斷**:`expired_timestamp - 60` 秒前重新取得(預留緩衝)
213
- 3. **Token 在所有請求 header 帶 `pcpay-token`**,不再使用 Basic Auth
214
-
215
- ---
216
-
217
- ## API 端點總覽
218
-
219
- ### 物流相關 API
220
-
221
- | 功能 | Method | 端點 | 說明 |
222
- |------|--------|------|------|
223
- | 取號列印交寄單 | POST | `/v1/logistic/batch` | 批次為超商取貨訂單取號並產生交寄單 |
224
- | 查詢物流歷程 | GET | `/v1/logistic/query/{order_id}/history` | 取得指定訂單之物流狀態歷程 (JSON) |
225
- | 物流歷程查詢頁 | GET | `/v1/logistic/query/{order_id}/history-page` | 取得物流歷程查詢頁 URL (HTML 頁面) |
226
- | 查詢未出貨訂單 | GET | `/v1/logistic/yet` | 列出尚未交寄之超商取貨訂單 |
227
- | 查詢未取貨訂單 | GET | `/v1/logistic/store_return/{date}` | 查詢買家未至超商取貨之物流編號 |
228
- | 物流手續費對帳 | GET | `/v1/logistic/accounting/{date}` | 指定日期之物流手續費對帳資料 |
229
- | 賠款入帳查詢 | GET | `/v1/logistic/compensation/{date}` | 指定月份貨物寄丟之賠款入帳資料 |
230
-
231
- ### 共用 Headers
232
-
233
- 所有物流 API 均需以下 header:
234
-
235
- | Header | 必填 | 說明 |
236
- |--------|------|------|
237
- | `Content-Type` | ● | `application/json` |
238
- | `pcpay-token` | ● | 由 `/v1/token` 取得之 token |
239
-
240
- ---
241
-
242
- ## 物流類型分類
243
-
244
- ### 付款方式 (pay_type) 對照
245
-
246
- PChomePay 物流訂單由金流訂單之 `pay_type` 決定。在 `POST /v1/payment` 建立訂單時填入:
247
-
248
- | pay_type | 物流類型 | 說明 |
249
- |----------|---------|------|
250
- | `IPL7` | 7-11 超商取貨付款 | 統一超商交貨便 (C2C) |
251
- | `IPLFM` | 全家超商取貨付款 | 全家便利商店 (C2C) |
252
- | `IPLHL` | 萊爾富超商取貨付款 | 萊爾富 (C2C) |
253
-
254
- > ⚠ PChomePay 目前不提供宅配 / 黑貓 / OK 超商等物流類型;OK (PLOK) 僅出現在對帳資料中作為歷史延續。
255
-
256
- ### 訂單金額限制
257
-
258
- 超商取貨付款訂單之金額限制:
259
-
260
- ```
261
- 65 ≦ amount ≦ 20,000 (新台幣)
262
- ```
263
-
264
- ### logistic_type (對帳資料用)
265
-
266
- 對帳 / 賠款 API 回傳之 `logistic_type` 對應如下:
267
-
268
- | logistic_type | 物流類型 |
269
- |--------------|---------|
270
- | `PL711` | 7-11 統一超商 |
271
- | `PLFMI` | 全家 (FamilyMart) |
272
- | `PLHIL` | 萊爾富 (Hi-Life) |
273
- | `PLOK` | OK 超商 |
274
-
275
- ### logistic_status (Notify 通知用)
276
-
277
- 物流狀態通知中之 `logistic_status` 對應如下:
278
-
279
- | logistic_status | 說明 |
280
- |----------------|------|
281
- | `SSND` | 商品已至「寄件門店」 |
282
- | `SATB` | 商品已至「取件門店」 |
283
- | `RATC` | 商品已至「退件門店」 |
284
-
285
- ### 未出貨狀態 (status)
286
-
287
- `/v1/logistic/yet` 回傳之狀態:
288
-
289
- | status | 說明 |
290
- |--------|------|
291
- | `LINT` | 訂單建立 (尚未取號) |
292
- | `LGNO` | 已取號 (尚未交寄) |
293
-
294
- ---
295
-
296
- ## 取號列印交寄單
297
-
298
- 為超商取貨訂單批次取號並產生交寄單列印頁面 URL。
299
-
300
- ### 端點
301
-
302
- ```
303
- POST https://api.pchomepay.com.tw/v1/logistic/batch
304
- ```
305
-
306
- ### 請求欄位
307
-
308
- | 欄位 | 必填 | 型態 | 說明 |
309
- |------|------|------|------|
310
- | `order_id` | ● | Array | 欲列印交寄單之訂單編號陣列 |
311
-
312
- ### cURL 範例
313
-
314
- ```bash
315
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/batch' \
316
- --header 'Content-Type: application/json' \
317
- --header 'pcpay-token: __kJw1OMKTkwwssWPsAnGNtIzMYFIZ5ymmkq8nCd' \
318
- --data '{
319
- "order_id": ["B2C1702640091"]
320
- }'
321
- ```
322
-
323
- ### 回應欄位
324
-
325
- | 欄位 | 必填 | 型態 | 說明 |
326
- |------|------|------|------|
327
- | `print_no` | ● | String | 取號成功之交貨便服務代碼 |
328
- | `error_order_id` | ● | String | 取號失敗之訂單編號 (成功時為 `null`) |
329
- | `print_url` | ● | String | 交寄單頁面連結 |
330
-
331
- ### 回應範例
332
-
333
- ```json
334
- {
335
- "print_no": "N63399396760",
336
- "error_order_id": null,
337
- "print_url": "https://pay.pchomepay.com.tw/apipay/ppwf?_pwfkey_=TnR3Z3AzY20xbk1wZFE0cGEsdU00aFNGcGNwNjVzcVkzVEwxZ1JPeGR3YUc5QWkwMk5yakEwSFlvdk5ZWHFoaQ=="
338
- }
339
- ```
340
-
341
- ### PHP 範例
342
-
343
- ```php
344
- <?php
345
-
346
- function batchPrintShippingLabel(string $token, array $orderIds): array
347
- {
348
- $body = json_encode(['order_id' => $orderIds]);
349
-
350
- $ch = curl_init();
351
- curl_setopt_array($ch, [
352
- CURLOPT_URL => 'https://api.pchomepay.com.tw/v1/logistic/batch',
353
- CURLOPT_POST => true,
354
- CURLOPT_POSTFIELDS => $body,
355
- CURLOPT_RETURNTRANSFER => true,
356
- CURLOPT_HTTPHEADER => [
357
- 'Content-Type: application/json',
358
- "pcpay-token: {$token}",
359
- ],
360
- ]);
361
-
362
- $response = curl_exec($ch);
363
- curl_close($ch);
364
-
365
- return json_decode($response, true);
366
- }
367
-
368
- // 使用範例
369
- $result = batchPrintShippingLabel($token, [
370
- 'B2C1702640091',
371
- 'B2C1702640092',
372
- ]);
373
-
374
- if ($result['error_order_id']) {
375
- error_log("取號失敗:{$result['error_order_id']}");
376
- } else {
377
- // 將 print_url 開啟以列印交寄單
378
- header("Location: {$result['print_url']}");
379
- }
380
- ```
381
-
382
- ### Python 範例
383
-
384
- ```python
385
- import requests
386
-
387
- def batch_print_shipping_label(token: str, order_ids: list) -> dict:
388
- headers = {
389
- "Content-Type": "application/json",
390
- "pcpay-token": token,
391
- }
392
- payload = {"order_id": order_ids}
393
- response = requests.post(
394
- "https://api.pchomepay.com.tw/v1/logistic/batch",
395
- headers=headers,
396
- json=payload,
397
- )
398
- response.raise_for_status()
399
- return response.json()
400
-
401
-
402
- # 使用範例
403
- result = batch_print_shipping_label(token, ["B2C1702640091"])
404
- if result.get("error_order_id"):
405
- print(f"取號失敗:{result['error_order_id']}")
406
- else:
407
- print(f"交寄單 URL:{result['print_url']}")
408
- ```
409
-
410
- ### 注意事項
411
-
412
- 1. **必須在 30 天內完成取號**:超過則訂單失效
413
- 2. **批次取號**:`order_id` 為陣列可一次處理多筆,但若任一筆失敗會回傳於 `error_order_id`
414
- 3. **`print_url` 開啟即可列印**:頁面為 HTML,內含適合熱感印表機的格式
415
- 4. **同訂單重複取號**:會回傳同一個 `print_no`,不會重複扣費
416
-
417
- ---
418
-
419
- ## 查詢物流歷程
420
-
421
- 查詢指定訂單之物流狀態歷程 (JSON 格式)。
422
-
423
- ### 端點
424
-
425
- ```
426
- GET https://api.pchomepay.com.tw/v1/logistic/query/{order_id}/history
427
- ```
428
-
429
- ### 路徑參數
430
-
431
- | 參數 | 必填 | 型態 | 說明 |
432
- |------|------|------|------|
433
- | `order_id` | ● | String(50) | 合作方訂單編號 |
434
-
435
- ### cURL 範例
436
-
437
- ```bash
438
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/query/B2C1723815435/history' \
439
- --header 'Content-Type: application/json' \
440
- --header 'pcpay-token: 0BZyFozlvqFtlwJoL5HQstTbNW_gNrNmsPQ4upc7'
441
- ```
442
-
443
- ### 回應欄位
444
-
445
- | 欄位 | 必填 | 型態 | 說明 |
446
- |------|------|------|------|
447
- | `order_id` | ● | String(50) | 合作方訂單編號 |
448
- | `history` | ● | Array | 歷程紀錄陣列 |
449
-
450
- ### history 物件
451
-
452
- | 欄位 | 必填 | 型態 | 說明 |
453
- |------|------|------|------|
454
- | `logistic_id` | ● | String(50) | 超商物流代號 |
455
- | `status` | ● | String(50) | 訂單與物流狀態(中文) |
456
- | `status_date` | ● | String | 該狀態日期 (YYYY/MM/DD) |
457
- | `status_time` | ● | String | 該狀態時間 (HH:MM:SS) |
458
-
459
- ### status 狀態值
460
-
461
- | status (中文) | 說明 |
462
- |--------------|------|
463
- | `訂單建立` | 訂單已成功建立但尚未取號 |
464
- | `已交寄` | 商家已將商品交寄至物流 |
465
- | `配送中` | 商品於物流配送中 |
466
- | `已到店` | 商品已送達取件門市 |
467
- | `已付款` | 用戶已至門市完成付款取貨 |
468
- | `已撥付` | 款項已轉至商家可提領餘額 |
469
-
470
- ### 回應範例
471
-
472
- ```json
473
- {
474
- "order_id": "B2C1723815435",
475
- "history": [
476
- {
477
- "logistic_id": "L24081201043969",
478
- "status": "訂單建立",
479
- "status_date": "2024/08/16",
480
- "status_time": "21:37:15"
481
- },
482
- {
483
- "logistic_id": "L24081201043969",
484
- "status": "已交寄",
485
- "status_date": "2024/08/16",
486
- "status_time": "21:39:02"
487
- }
488
- ]
489
- }
490
- ```
491
-
492
- ### Python 範例
493
-
494
- ```python
495
- import requests
496
-
497
- def query_logistic_history(token: str, order_id: str) -> dict:
498
- url = f"https://api.pchomepay.com.tw/v1/logistic/query/{order_id}/history"
499
- headers = {
500
- "Content-Type": "application/json",
501
- "pcpay-token": token,
502
- }
503
- response = requests.get(url, headers=headers)
504
- response.raise_for_status()
505
- return response.json()
506
-
507
-
508
- # 取出最新狀態
509
- history = query_logistic_history(token, "B2C1723815435")
510
- latest = history["history"][-1] if history["history"] else None
511
- if latest:
512
- print(f"目前狀態:{latest['status']} ({latest['status_date']} {latest['status_time']})")
513
- ```
514
-
515
- ---
516
-
517
- ## 物流歷程查詢頁
518
-
519
- 取得可直接呈現給用戶的物流歷程查詢頁 URL(HTML 頁面)。
520
-
521
- ### 端點
522
-
523
- ```
524
- GET https://api.pchomepay.com.tw/v1/logistic/query/{order_id}/history-page
525
- ```
526
-
527
- ### 路徑參數
528
-
529
- | 參數 | 必填 | 型態 | 說明 |
530
- |------|------|------|------|
531
- | `order_id` | ● | String(50) | 合作方訂單編號 |
532
-
533
- ### cURL 範例
534
-
535
- ```bash
536
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/query/B2C1723815435/history-page' \
537
- --header 'Content-Type: application/json' \
538
- --header 'pcpay-token: e0A_XRsPMDgCKvRnrikpdMTfEJzvIGuveJsn_695'
539
- ```
540
-
541
- ### 回應欄位
542
-
543
- | 欄位 | 必填 | 型態 | 說明 |
544
- |------|------|------|------|
545
- | `order_id` | ● | String(50) | 合作方訂單編號 |
546
- | `history_url` | ● | String | 物流歷程查詢頁 URL |
547
-
548
- ### 回應範例
549
-
550
- ```json
551
- {
552
- "logistic_id": "L24041201043748",
553
- "history_url": "https://pchomepay.com.tw/apipay/ppwf?_pwfkey_=UjdkdVlreEV5cjlKRlRZeHdlUSxRUVVkVk0ta09uZGlINCxoRSxicEs2ZVB0UnhkcDBkY0RkZE84R0dSU3hFcA=="
554
- }
555
- ```
556
-
557
- ### 應用情境
558
-
559
- 1. **顧客自助查詢**:將 `history_url` 嵌入訂單頁面,顧客點擊即可查看完整物流歷程
560
- 2. **客服 / 後台**:直接連結至 PChomePay 提供之 UI 頁面,省去自行渲染歷程的成本
561
- 3. **與 `/history` 差異**:`/history` 回傳 JSON 由商家自行渲染;`/history-page` 直接提供完整 UI 頁面
562
-
563
- ---
564
-
565
- ## 未出貨/未取貨查詢
566
-
567
- ### 查詢未出貨訂單
568
-
569
- 列出已建立但尚未交寄至物流之超商取貨訂單。
570
-
571
- #### 端點
572
-
573
- ```
574
- GET https://api.pchomepay.com.tw/v1/logistic/yet
575
- ```
576
-
577
- #### 請求欄位
578
-
579
- 無
580
-
581
- #### cURL 範例
582
-
583
- ```bash
584
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/yet' \
585
- --header 'Content-Type: application/json' \
586
- --header 'pcpay-token: F6uG0pXXTPTHDMRkIj_HGnzrWJvom_m_HhPxf296'
587
- ```
588
-
589
- #### 回應欄位 (Array)
590
-
591
- | 欄位 | 必填 | 型態 | 說明 |
592
- |------|------|------|------|
593
- | `order_id` | ● | String(50) | 合作方訂單編號 |
594
- | `status` | ● | String | 商品目前物流狀態 |
595
-
596
- #### status 值
597
-
598
- | status | 說明 |
599
- |--------|------|
600
- | `LINT` | 訂單建立 (尚未取號) |
601
- | `LGNO` | 已取號 (尚未交寄) |
602
-
603
- #### 回應範例
604
-
605
- ```json
606
- [
607
- {
608
- "order_id": "B2C1744189821",
609
- "status": "LGNO"
610
- },
611
- {
612
- "order_id": "B2C1744189822",
613
- "status": "LINT"
614
- }
615
- ]
616
- ```
617
-
618
- #### 應用情境
619
-
620
- - **每日交寄提醒**:每天透過此 API 撈出 `LGNO` 訂單,發送 reminder 給倉管人員
621
- - **截止日警示**:搭配建單日期計算 T + N 天,於即將逾期時優先處理
622
-
623
- ---
624
-
625
- ### 查詢未取貨訂單
626
-
627
- 查詢買家未至超商取貨之物流編號(指定日期已到店但尚未取貨)。
628
-
629
- #### 端點
630
-
631
- ```
632
- GET https://api.pchomepay.com.tw/v1/logistic/store_return/{date}
633
- ```
634
-
635
- #### 路徑參數
636
-
637
- | 參數 | 必填 | 型態 | 說明 |
638
- |------|------|------|------|
639
- | `date` | ● | String(8) | 欲查詢日期,格式 `YYYYMMDD` |
640
-
641
- #### cURL 範例
642
-
643
- ```bash
644
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/store_return/20250409' \
645
- --header 'pcpay-token: F6uG0pXXTPTHDMRkIj_HGnzrWJvom_m_HhPxf296'
646
- ```
647
-
648
- #### 回應欄位 (Array)
649
-
650
- | 欄位 | 必填 | 型態 | 說明 |
651
- |------|------|------|------|
652
- | `order_id` | ● | String(50) | 合作方訂單編號 |
653
- | `logistic_id` | ● | String(50) | 訂單物流編號 |
654
- | `status` | ● | String | 商品目前物流狀態 (僅 `SATB`) |
655
-
656
- #### 回應範例
657
-
658
- ```json
659
- [
660
- {
661
- "order_id": "B2C1744192674",
662
- "logistic_id": "L25041201044206",
663
- "status": "SATB"
664
- }
665
- ]
666
- ```
667
-
668
- > 此 API 僅回傳狀態為 `SATB` (商品已到取件門市) 但用戶尚未取走的訂單。
669
-
670
- #### 應用情境
671
-
672
- - **退件預警**:到店未取超過超商保留期限將自動退件(產生退件物流費)
673
- - **客戶提醒**:撈出此清單,主動以 SMS / Email 提醒買家取貨
674
-
675
- ---
676
-
677
- ## 物流手續費對帳
678
-
679
- 查詢指定日期之物流手續費對帳資料。
680
-
681
- ### 端點
682
-
683
- ```
684
- GET https://api.pchomepay.com.tw/v1/logistic/accounting/{date}
685
- ```
686
-
687
- ### 路徑參數
688
-
689
- | 參數 | 必填 | 型態 | 說明 |
690
- |------|------|------|------|
691
- | `date` | ● | String(8) | 對帳日期,格式 `YYYYMMDD`,僅能查詢 30 天前資料 |
692
-
693
- ### cURL 範例
694
-
695
- ```bash
696
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/accounting/20240816' \
697
- --header 'pcpay-token: fGVWZrMrYEVLHbj1joxn7CpdjsygFYYN8vLaygGM'
698
- ```
699
-
700
- ### 回應格式
701
-
702
- > ⚠ 此 API 為**特規 JSON 串接格式**:第一行為摘要 JSON,後續每筆訂單為獨立 JSON object(換行分隔,非標準 JSON Array)。
703
-
704
- #### 第一行 (摘要)
705
-
706
- | 欄位 | 必填 | 型態 | 說明 |
707
- |------|------|------|------|
708
- | `total_recs` | ● | String(5) | 該日對帳資料筆數 |
709
-
710
- #### 明細欄位 (每行一筆)
711
-
712
- | 欄位 | 必填 | 型態 | 說明 |
713
- |------|------|------|------|
714
- | `order_id` | ● | String(50) | 合作方訂單編號 |
715
- | `logistic_type` | ● | String | 物流類型 (`PL711` / `PLFMI` / `PLHIL` / `PLOK`) |
716
- | `logistic_amount` | ● | Int | 物流手續費 (新台幣) |
717
- | `accounting_date` | ● | String(14) | 帳務日期,格式 `YYYYMMDDhh24MiSS` |
718
-
719
- ### 回應範例
720
-
721
- ```
722
- {"total_recs": 1}
723
- {"order_id": "B2C1723809155", "logistic_type": "PL711", "logistic_amount": 65, "accounting_date": "20240816195407"}
724
- {"order_id": "B2C1723808237", "logistic_type": "PLFMI", "logistic_amount": 65, "accounting_date": "20240818201412"}
725
- ```
726
-
727
- ### Python 解析範例
728
-
729
- ```python
730
- import requests
731
- import json
732
-
733
- def fetch_logistic_accounting(token: str, date: str) -> dict:
734
- url = f"https://api.pchomepay.com.tw/v1/logistic/accounting/{date}"
735
- headers = {"pcpay-token": token}
736
- response = requests.get(url, headers=headers)
737
- response.raise_for_status()
738
-
739
- # 特規 JSON:以換行分隔每行為一個 JSON
740
- lines = response.text.strip().splitlines()
741
- summary = json.loads(lines[0])
742
- records = [json.loads(line) for line in lines[1:] if line.strip()]
743
- return {"summary": summary, "records": records}
744
-
745
-
746
- result = fetch_logistic_accounting(token, "20240816")
747
- print(f"共 {result['summary']['total_recs']} 筆")
748
- for rec in result["records"]:
749
- print(f"{rec['order_id']} - {rec['logistic_type']} - NT${rec['logistic_amount']}")
750
- ```
751
-
752
- ### 物流手續費注意事項
753
-
754
- 1. **無論是否取貨成功,皆會收取物流手續費**:商品從交寄起就計算手續費
755
- 2. **手續費為內扣**:訂單清算時自動從訂單金額中扣除,不另外請款
756
- 3. **PChomePay 後台**:可至會員中心 > 對帳資料下載完整對帳檔
757
- 4. **30 天保留期**:超過 30 天則無法查詢,請定期下載備份
758
-
759
- ---
760
-
761
- ## 賠款查詢
762
-
763
- 查詢指定月份貨物寄丟之賠款入帳資料。
764
-
765
- ### 端點
766
-
767
- ```
768
- GET https://api.pchomepay.com.tw/v1/logistic/compensation/{date}
769
- ```
770
-
771
- ### 路徑參數
772
-
773
- | 參數 | 必填 | 型態 | 說明 |
774
- |------|------|------|------|
775
- | `date` | ● | String(6) | 入帳年月,格式 `YYYYMM` |
776
-
777
- ### cURL 範例
778
-
779
- ```bash
780
- curl --location 'https://api.pchomepay.com.tw/v1/logistic/compensation/202408' \
781
- --header 'pcpay-token: fGVWZrMrYEVLHbj1joxn7CpdjsygFYYN8vLaygGM'
782
- ```
783
-
784
- ### 回應格式
785
-
786
- 與「物流手續費對帳」相同採特規 JSON:
787
-
788
- #### 第一行 (摘要)
789
-
790
- | 欄位 | 必填 | 型態 | 說明 |
791
- |------|------|------|------|
792
- | `total_recs` | ● | String(5) | 該月賠款筆數 |
793
-
794
- #### 明細欄位
795
-
796
- | 欄位 | 必填 | 型態 | 說明 |
797
- |------|------|------|------|
798
- | `order_id` | ● | String(50) | 合作方訂單編號 |
799
- | `logistic_type` | ● | String | 物流類型 (`PL711` / `PLFMI` / `PLHIL` / `PLOK`) |
800
- | `logistic_amount` | ● | Int | 賠款金額 (新台幣) |
801
- | `accounting_date` | ● | String(14) | 帳務日期,格式 `YYYYMMDDhh24MiSS` |
802
-
803
- ### 回應範例
804
-
805
- ```
806
- {"total_recs": 1}
807
- {"order_id": "B2C1723809155", "logistic_type": "PL711", "logistic_amount": 200, "accounting_date": "20240816195407"}
808
- {"order_id": "B2C1723808237", "logistic_type": "PLFMI", "logistic_amount": 565, "accounting_date": "20240818201412"}
809
- ```
810
-
811
- ### 賠款說明
812
-
813
- 1. **觸發條件**:商品於物流運送過程中遺失或損毀,由超商物流方核定後賠付
814
- 2. **賠款金額**:依物流商賠付規範決定(通常為訂單金額之一定比例,最高有上限)
815
- 3. **入帳方式**:直接撥付至 PChomePay 商家餘額
816
- 4. **查詢範圍**:以月份為單位 (`YYYYMM`),可累積查詢
817
-
818
- ---
819
-
820
- ## 物流狀態通知
821
-
822
- PChomePay 會在物流狀態變更時透過 `notify_url` 主動推送通知。
823
-
824
- ### 通知格式
825
-
826
- ```
827
- Method: POST
828
- Content-Type: application/x-www-form-urlencoded
829
- ```
830
-
831
- ### 通用參數
832
-
833
- | 參數 | 說明 |
834
- |------|------|
835
- | `notify_type` | 通知類型 (`seller_dispatched` / `pickup_shipped` / `return_shipped`) |
836
- | `notify_message` | JSON 格式之通知內容 (字串) |
837
-
838
- ### notify_message 結構
839
-
840
- | 欄位 | 必填 | 型態 | 說明 |
841
- |------|------|------|------|
842
- | `order_id` | ● | String(50) | 合作方訂單編號 |
843
- | `pay_type` | ● | String(5) | 付款方式 (`IPL7` / `IPLFM` / `IPLHL`) |
844
- | `logistic_info` | ● | Object | 物流資訊(見下) |
845
-
846
- ### logistic_info 物件
847
-
848
- | 欄位 | 必填 | 型態 | 說明 |
849
- |------|------|------|------|
850
- | `logistic_id` | ● | String(11) | 超商物流代號 |
851
- | `logistic_status` | ● | String | 物流狀態 (`SSND` / `SATB` / `RATC`) |
852
- | `logistic_type` | ● | String | 物流類型 (`C2C` 店到店, `B2C` 大宗寄倉,目前未提供) |
853
- | `status_date` | ● | String(14) | 該狀態日期 (`YYYYMMDDhh24MiSS`) |
854
-
855
- ### 通知類型
856
-
857
- #### seller_dispatched (商品已至寄件門店)
858
-
859
- 當商家將商品交寄至超商寄件門市時觸發。
860
-
861
- ```bash
862
- curl --location 'https://your-site.com/notify' \
863
- --header 'Content-Type: application/x-www-form-urlencoded' \
864
- --data-urlencode 'notify_type=seller_dispatched' \
865
- --data-urlencode 'notify_message={
866
- "order_id":"B2C_Uni_1769857427",
867
- "pay_type":"IPL7",
868
- "logistic_info":{
869
- "logistic_id":"M22216559430",
870
- "logistic_status":"SSND",
871
- "logistic_type":"C2C",
872
- "status_date":"20250924183250"
873
- }
874
- }'
875
- ```
876
-
877
- #### pickup_shipped (商品已至取件門店)
878
-
879
- 當商品送達買家指定的取件門市時觸發 → 商家可發送通知請買家前往取貨。
880
-
881
- ```bash
882
- curl --location 'https://your-site.com/notify' \
883
- --header 'Content-Type: application/x-www-form-urlencoded' \
884
- --data-urlencode 'notify_type=pickup_shipped' \
885
- --data-urlencode 'notify_message={
886
- "order_id":"B2C_Uni_1769850289",
887
- "pay_type":"IPL7",
888
- "logistic_info":{
889
- "logistic_id":"M22216568132",
890
- "logistic_status":"SATB",
891
- "logistic_type":"C2C",
892
- "status_date":"20250925212043"
893
- }
894
- }'
895
- ```
896
-
897
- #### return_shipped (商品已至退件門店)
898
-
899
- 當買家未取貨或主動退貨,商品送達退件門市時觸發。
900
-
901
- ```bash
902
- curl --location 'https://your-site.com/notify' \
903
- --header 'Content-Type: application/x-www-form-urlencoded' \
904
- --data-urlencode 'notify_type=return_shipped' \
905
- --data-urlencode 'notify_message={
906
- "order_id":"B2C_Uni_1769853160",
907
- "pay_type":"IPL7",
908
- "logistic_info":{
909
- "logistic_id":"M22216577821",
910
- "logistic_status":"RATC",
911
- "logistic_type":"C2C",
912
- "status_date":"20250927090822"
913
- }
914
- }'
915
- ```
916
-
917
- ### PHP 接收範例
918
-
919
- ```php
920
- <?php
921
-
922
- // 接收 PChomePay 物流狀態通知
923
- $notifyType = $_POST['notify_type'] ?? '';
924
- $notifyMessage = json_decode($_POST['notify_message'] ?? '{}', true);
925
-
926
- if (!$notifyMessage) {
927
- http_response_code(400);
928
- exit('invalid notify_message');
929
- }
930
-
931
- $orderId = $notifyMessage['order_id'];
932
- $status = $notifyMessage['logistic_info']['logistic_status'];
933
-
934
- switch ($notifyType) {
935
- case 'seller_dispatched':
936
- // 商品已交寄
937
- updateOrderStatus($orderId, 'shipped');
938
- break;
939
- case 'pickup_shipped':
940
- // 商品已到店,可發送取貨通知
941
- updateOrderStatus($orderId, 'arrived_at_store');
942
- sendPickupReminder($orderId);
943
- break;
944
- case 'return_shipped':
945
- // 商品退件
946
- updateOrderStatus($orderId, 'returned');
947
- break;
948
- }
949
-
950
- // PChomePay 不要求特定回應,回 200 即可
951
- http_response_code(200);
952
- echo 'OK';
953
- ```
954
-
955
- ### Python 接收範例 (Flask)
956
-
957
- ```python
958
- import json
959
- from flask import Flask, request
960
-
961
- app = Flask(__name__)
962
-
963
- @app.route('/pchomepay-notify', methods=['POST'])
964
- def pchomepay_notify():
965
- notify_type = request.form.get('notify_type')
966
- notify_message = request.form.get('notify_message', '{}')
967
-
968
- try:
969
- message = json.loads(notify_message)
970
- except json.JSONDecodeError:
971
- return 'invalid notify_message', 400
972
-
973
- order_id = message['order_id']
974
- logistic_status = message['logistic_info']['logistic_status']
975
-
976
- if notify_type == 'seller_dispatched':
977
- update_order(order_id, 'shipped')
978
- elif notify_type == 'pickup_shipped':
979
- update_order(order_id, 'arrived_at_store')
980
- elif notify_type == 'return_shipped':
981
- update_order(order_id, 'returned')
982
-
983
- return 'OK', 200
984
- ```
985
-
986
- ### 通知處理注意事項
987
-
988
- 1. **重試機制**:PChomePay 若收到非 200 回應,會自動重試多次
989
- 2. **驗證來源 IP**:建議白名單檢查 `113.196.231.190` 為唯一允許來源
990
- 3. **冪等處理**:同一狀態變更可能收到多次通知,需以 `order_id + logistic_status + status_date` 去重
991
- 4. **非阻塞處理**:建議以 queue / async 處理通知內容,避免回應延遲
992
-
993
- ---
994
-
995
- ## 錯誤代碼
996
-
997
- ### 物流相關錯誤代碼
998
-
999
- | 代碼 | 英文描述 | 中文描述 |
1000
- |------|---------|---------|
1001
- | `90001` | invalid status | 物流狀態錯誤 |
1002
- | `90002` | logistic status history not found | 物流狀態歷程不存在 |
1003
- | `90004` | Print delivery note fail. | 列印交寄單失敗 |
1004
-
1005
- ### 認證 / 通用錯誤代碼
1006
-
1007
- | 代碼 | 英文描述 | 中文描述 |
1008
- |------|---------|---------|
1009
- | `10001` | invalid user password | APPID 和 Secret 錯誤 |
1010
- | `10002` | Server IP not allow | 不被允許的 IP 位址 |
1011
- | `10003` | invalid token | token 錯誤 |
1012
- | `10004` | token expired | token 逾期 |
1013
- | `10006` | api client has not set notifyURL or returnURL yet | 未設定 notifyURL 或 returnURL |
1014
- | `10007` | function unavailable | 會員帳號暫時無法使用功能服務 |
1015
-
1016
- ### 訂單相關錯誤代碼
1017
-
1018
- | 代碼 | 英文描述 | 中文描述 |
1019
- |------|---------|---------|
1020
- | `20001` | order id duplicate | 訂單編號不可重複 |
1021
- | `20002` | order not exists | 訂單不存在 |
1022
- | `20003` | pay type not support | 付款類別錯誤 |
1023
- | `20005` | params is not valid | 參數錯誤 |
1024
- | `20007` | It not allow to check today's data | 目前無法查詢當日資料 |
1025
- | `20009` | Request data is not a json structure data | 請求格式不是 JSON |
1026
- | `20014` | cvs setting error. | 未設定超商退貨門市 |
1027
-
1028
- ### 錯誤回應格式
1029
-
1030
- ```json
1031
- {
1032
- "error_type": "invalid_request_error",
1033
- "code": 90004,
1034
- "message": "Print delivery note fail."
1035
- }
1036
- ```
1037
-
1038
- ---
1039
-
1040
- ## 常見問題排解
1041
-
1042
- ### Q1: 取號失敗 (90004) 該如何處理?
1043
-
1044
- **可能原因**:
1045
-
1046
- 1. 訂單付款方式不是超商取貨 (`IPL7` / `IPLFM` / `IPLHL`)
1047
- 2. 用戶尚未在付款頁面選擇取件門市
1048
- 3. 訂單已超過 30 天取號期限
1049
- 4. 訂單狀態異常 (失敗 / 退款)
1050
-
1051
- **處理方式**:
1052
-
1053
- - 先呼叫 `GET /v1/payment/{order_id}` 查詢訂單狀態
1054
- - 確認 `payment_info.store_id` 是否已存在 (代表用戶已選門市)
1055
- - 若超過 30 天,需請用戶重新下單
1056
-
1057
- ### Q2: 為何收不到物流通知?
1058
-
1059
- **檢查清單**:
1060
-
1061
- 1. **`notify_url` 設定**:在 PChomePay 後台 > 環境設定 > Notify URL 是否設定正確
1062
- 2. **IP 白名單**:是否將 `113.196.231.190` 加入防火牆白名單
1063
- 3. **HTTPS 憑證**:notify URL 須為有效的 HTTPS 端點 (建議使用 Let's Encrypt 等正式憑證)
1064
- 4. **回應狀態碼**:notify 接收端需回應 200,否則 PChomePay 會持續重試
1065
- 5. **建立訂單時 `notify_url`**:可於 `POST /v1/payment` 個別覆蓋預設值
1066
-
1067
- ### Q3: 物流訂單可以重新取號嗎?
1068
-
1069
- **答**:
1070
-
1071
- - **同一筆訂單可重複呼叫 `/v1/logistic/batch`**:會回傳同一個 `print_no`,不會重複扣費
1072
- - **若要更換門市**:無法透過 API,需請買家重新下單
1073
-
1074
- ### Q4: 如何處理「已到店但用戶未取貨」?
1075
-
1076
- **SOP**:
1077
-
1078
- ```
1079
- 1. 透過 GET /v1/logistic/store_return/{date} 撈出 SATB 但未付款訂單
1080
- 2. 主動以 SMS / Email 通知買家取貨
1081
- 3. 超過 7 天後(超商保留期限),商品會自動退件
1082
- 4. 收到 return_shipped 通知後,自動標記訂單為「退件」狀態
1083
- 5. 商家從退件門市領回商品
1084
- ```
1085
-
1086
- ### Q5: 物流手續費何時收取?
1087
-
1088
- **答**:
1089
-
1090
- - **時機**:商品從寄件門店交寄起即收取
1091
- - **金額**:依各超商之合約價(一般 7-11 / 全家為 NT$65 / 件,實際以後台公告為準)
1092
- - **無論取貨成敗皆收取**:包括買家未取貨退件
1093
- - **退款不退手續費**:退款時手續費不會退還,且會額外收取 NT$15 退款手續費
1094
-
1095
- ### Q6: 是否支援自有物流?
1096
-
1097
- **答**:
1098
-
1099
- - PChomePay **僅支援自家整合的超商取貨服務**
1100
- - 若需使用其他物流(黑貓、新竹貨運、自取等),需自行另外串接 ECPay / PayUni / 物流商 API
1101
- - PChomePay 會專注於「金流 + 超商取貨」一站式服務的整合
1102
-
1103
- ### Q7: 與 ECPay / PayUni 物流的差異?
1104
-
1105
- | 比較項目 | PChomePay | ECPay | PayUni |
1106
- |---------|-----------|-------|--------|
1107
- | 物流獨立串接 | ❌ 必須先建金流訂單 | ✅ 物流可獨立串接 | ✅ 物流可獨立串接 |
1108
- | 支援超商 | 7-11 / 全家 / 萊爾富 | 4 大超商 + 黑貓 + 宅配通 | 7-11 + 黑貓 |
1109
- | 認證方式 | OAuth-like (Basic Auth → token) | CheckMacValue (MD5) | AES-256-GCM + HMAC |
1110
- | 物流類型 | C2C 店到店 | C2C / B2C | C2C |
1111
- | Notify 格式 | x-www-form-urlencoded + JSON | x-www-form-urlencoded | JSON / 加密 |
1112
-
1113
- ### Q8: 如何測試 Sandbox 環境?
1114
-
1115
- **測試步驟**:
1116
-
1117
- 1. 申請正式及測試 APP_ID / SECRET(聯絡 PChomePay 業務)
1118
- 2. 使用 sandbox URL:`https://sandbox-api.pchomepay.com.tw`
1119
- 3. 建立超商取貨訂單,金額尾數依[測試規則](#sandbox-測試規則超商取貨)模擬不同狀態
1120
- 4. 在 sandbox 後台查看訂單與物流狀態
1121
-
1122
- ### Q9: 訂單狀態 WD 是什麼意思?
1123
-
1124
- **答**:
1125
-
1126
- - `WD` = **超商取貨等待商品交寄**
1127
- - 此狀態出現在 `GET /v1/payment/{order_id}` 之 `status_code`
1128
- - 代表用戶已成功下單並選擇門市,但商家尚未取號交寄
1129
- - 此時應呼叫 `POST /v1/logistic/batch` 取號 → 列印交寄單 → 交寄
1130
-
1131
- ### Q10: 對帳 / 賠款 API 為何回應不是標準 JSON?
1132
-
1133
- **答**:
1134
-
1135
- - 文件明確說明:「API 除對帳為特規 JSON 外,其他所有請求以及回應都以 JSON 做為標準請求或回傳格式」
1136
- - 對帳 / 賠款 API 採**逐行 JSON (NDJSON / JSONL) 格式**:
1137
- - 第一行:摘要(`total_recs`)
1138
- - 後續每行:一筆訂單之 JSON object
1139
- - 不可使用 `json.loads(response.text)` 直接解析,需逐行解析([參考解析範例](#python-解析範例))
1140
-
1141
- ---
1142
-
1143
- ## 官方資源
1144
-
1145
- - **官方網站**: https://www.pchomepay.com.tw/
1146
- - **API 文件**: https://docs.google.com/document/d/1dPIPJc4xfyjkJ1i2yxaja4OP0G-iGFRXM08NDMuttZE/
1147
- - **後台管理**: https://web.pchomepay.com.tw/
1148
- - **WooCommerce 模組**: [PChomePay WooCommerce User Guide](https://docs.google.com/document/d/1ItCUQvY0A4VeVAlOdAMbt48lKB-xlNVZCu7E6L9d0Mg/)
1149
- - **舊版購物車模組**: https://github.com/PChomePayPlugin
1150
- - **技術服務信箱**: tech_support@pchomepay.com.tw
1151
-
1152
- ---
1153
-
1154
- 最後更新:2026/05/07
1
+ # PChomePay Logistics API Reference
2
+
3
+ 拍錢包 (PChomePay) 物流 API 完整參考文件。
4
+
5
+ ---
6
+
7
+ ## 目錄
8
+
9
+ 1. [基本說明](#基本說明)
10
+ 2. [環境資訊](#環境資訊)
11
+ 3. [認證方式](#認證方式)
12
+ 4. [API 端點總覽](#api-端點總覽)
13
+ 5. [物流類型分類](#物流類型分類)
14
+ 6. [取號列印交寄單](#取號列印交寄單)
15
+ 7. [查詢物流歷程](#查詢物流歷程)
16
+ 8. [物流歷程查詢頁](#物流歷程查詢頁)
17
+ 9. [未出貨/未取貨查詢](#未出貨未取貨查詢)
18
+ 10. [物流手續費對帳](#物流手續費對帳)
19
+ 11. [賠款查詢](#賠款查詢)
20
+ 12. [物流狀態通知](#物流狀態通知)
21
+ 13. [錯誤代碼](#錯誤代碼)
22
+ 14. [常見問題排解](#常見問題排解)
23
+
24
+ ---
25
+
26
+ ## 基本說明
27
+
28
+ ### PChomePay 物流定位
29
+
30
+ 拍錢包 (PChomePay) 與 ECPay、PayUni 等純物流串接平台不同,主打**金流 + 物流二合一**的整合服務:
31
+
32
+ - **金流為主軸**:所有物流訂單均由 PChomePay 金流訂單派生,需先以 `pay_type` 為超商取貨類型 (`IPL7` / `IPLFM` / `IPLHL`) 建立金流訂單
33
+ - **超商取貨付款**:核心場景為 7-11 / 全家 / 萊爾富之 C2C 店到店服務,買家在付款頁面選擇取件門市
34
+ - **無獨立物流單建立 API**:`POST /v1/payment` 建立金流訂單後,物流訂單會自動產生;商家只需呼叫「取號列印交寄單」即可完成取號
35
+ - **與信用卡 / ATM 等其他付款方式可共用同套金流流程**:但僅超商取貨類型訂單會觸發物流相關 API
36
+
37
+ ### 物流流程概覽
38
+
39
+ ```
40
+ 1. 建立金流訂單 (pay_type = IPL7/IPLFM/IPLHL)
41
+ └─ 用戶在付款頁面選擇超商取件門市
42
+ 2. 取得用戶選擇門市資訊 (notify: payment_info_set)
43
+ 3. 取號列印交寄單 (POST /v1/logistic/batch)
44
+ 4. 將商品交寄至超商
45
+ 5. 透過通知 / 查詢 API 監控物流狀態
46
+ 6. 用戶取貨完成 → 款項撥付
47
+ ```
48
+
49
+ ### 交寄期限規定
50
+
51
+ 超商取貨訂單須在 **30 天內**完成取號交寄單列印。完成取號列印後(當日為 T),各超商有不同的交寄截止日:
52
+
53
+ | 超商 | 交寄期限 | 範例(6/10 取號) |
54
+ |------|----------|------------------|
55
+ | 7-11 (統一超商) | T + 10 日 | 須在 6/20 23:59 前交寄 |
56
+ | 全家 (FamilyMart) | T + 6 日 | 須在 6/16 23:59 前交寄 |
57
+ | 萊爾富 (Hi-Life) | T + 7 日 | 須在 6/17 23:59 前交寄 |
58
+
59
+ > ⚠ 一旦逾期未交寄,該訂單之物流單將自動失效,需重新處理。
60
+
61
+ ---
62
+
63
+ ## 環境資訊
64
+
65
+ ### Domain Name
66
+
67
+ | 環境 | Base URL |
68
+ |------|----------|
69
+ | **正式環境 (Production)** | `https://api.pchomepay.com.tw` |
70
+ | **測試環境 (Sandbox)** | `https://sandbox-api.pchomepay.com.tw` |
71
+
72
+ ### 來源 IP 白名單
73
+
74
+ 正式與測試環境會透過以下 IP 發送 API Notify:
75
+
76
+ ```
77
+ 113.196.231.190
78
+ ```
79
+
80
+ > 商家若有防火牆設定,請將此 IP 加入白名單,否則無法接收物流狀態通知。
81
+
82
+ ### Sandbox 測試規則(超商取貨)
83
+
84
+ Sandbox 測試環境會根據訂單金額尾數模擬不同物流狀態:
85
+
86
+ | 金額尾數 | 模擬狀態 |
87
+ |---------|---------|
88
+ | 0 / 6 / 7 / 8 / 9 | 已建立 |
89
+ | 1 | 已交寄 |
90
+ | 2 | 配送中 |
91
+ | 3 | 已到店 |
92
+ | 4 | 已收款 |
93
+ | 5 | 已退件 |
94
+
95
+ ### Sandbox 測試門市
96
+
97
+ ```
98
+ 7-11 測試門市:桃園市桃園區中埔六街 36 號 1 樓 維瀚門市
99
+ ```
100
+
101
+ ---
102
+
103
+ ## 認證方式
104
+
105
+ PChomePay 物流 API 與金流 API 共用同一套認證機制。
106
+
107
+ ### 認證流程
108
+
109
+ ```
110
+ [1] APP_ID + SECRET (Basic Auth)
111
+ ↓
112
+ [2] POST /v1/token → 取得 pcpay-token
113
+ ↓
114
+ [3] 呼叫物流 API (header: pcpay-token)
115
+ ↓
116
+ [4] token 8 小時失效 → 重新取得
117
+ ```
118
+
119
+ ### 步驟 1: 取得 Token
120
+
121
+ **端點**
122
+
123
+ ```
124
+ POST https://api.pchomepay.com.tw/v1/token
125
+ ```
126
+
127
+ **請求 Header**
128
+
129
+ | 欄位 | 必填 | 說明 |
130
+ |------|------|------|
131
+ | `Authorization` | ● | `Basic base64({APP_ID}:{SECRET})` |
132
+ | `Content-Type` | ● | `application/json` |
133
+
134
+ **請求 Body**
135
+
136
+ 無
137
+
138
+ **回應欄位**
139
+
140
+ | 欄位 | 必填 | 型態 | 說明 |
141
+ |------|------|------|------|
142
+ | `token` | ● | String(50) | 取得之 token,後續需放在 header `pcpay-token` |
143
+ | `expired_in` | ● | Int | token 失效秒數,預設 28,800 秒 (8 小時) |
144
+ | `expired_timestamp` | ● | Int | token 失效之 unix timestamp |
145
+
146
+ ### cURL 範例
147
+
148
+ ```bash
149
+ curl --location --request POST 'https://api.pchomepay.com.tw/v1/token' \
150
+ --header 'Authorization: Basic RTIzNjc5QkY2NEFFNDU0RjRDQjY3MTFGQUMzNjp4UGdWTmdXb2I4YkdnRVQyZUJSc25pX3lYRW10cXV0bHhVa19VVXVo' \
151
+ --header 'Content-Type: application/json'
152
+ ```
153
+
154
+ ### PHP 範例
155
+
156
+ ```php
157
+ <?php
158
+
159
+ function getPcpayToken(string $appId, string $secret): array
160
+ {
161
+ $auth = base64_encode("{$appId}:{$secret}");
162
+
163
+ $ch = curl_init();
164
+ curl_setopt_array($ch, [
165
+ CURLOPT_URL => 'https://api.pchomepay.com.tw/v1/token',
166
+ CURLOPT_POST => true,
167
+ CURLOPT_POSTFIELDS => '',
168
+ CURLOPT_RETURNTRANSFER => true,
169
+ CURLOPT_HTTPHEADER => [
170
+ "Authorization: Basic {$auth}",
171
+ 'Content-Type: application/json',
172
+ ],
173
+ ]);
174
+
175
+ $response = curl_exec($ch);
176
+ curl_close($ch);
177
+
178
+ return json_decode($response, true);
179
+ }
180
+
181
+ // 範例回應
182
+ // {
183
+ // "token": "zHm67sQRuPSO__eiuy2h_lEgtPlS12aVqrcVz3Kc",
184
+ // "expired_in": 28800,
185
+ // "expired_timestamp": 1474470110
186
+ // }
187
+ ```
188
+
189
+ ### Python 範例
190
+
191
+ ```python
192
+ import base64
193
+ import requests
194
+
195
+ def get_pcpay_token(app_id: str, secret: str) -> dict:
196
+ credentials = base64.b64encode(f"{app_id}:{secret}".encode()).decode()
197
+ headers = {
198
+ "Authorization": f"Basic {credentials}",
199
+ "Content-Type": "application/json",
200
+ }
201
+ response = requests.post(
202
+ "https://api.pchomepay.com.tw/v1/token",
203
+ headers=headers,
204
+ )
205
+ response.raise_for_status()
206
+ return response.json()
207
+ ```
208
+
209
+ ### Token 使用注意事項
210
+
211
+ 1. **不要每次請求都呼叫 `/v1/token`**:請暫存 token 到 8 小時失效再重新取得
212
+ 2. **失效時間判斷**:`expired_timestamp - 60` 秒前重新取得(預留緩衝)
213
+ 3. **Token 在所有請求 header 帶 `pcpay-token`**,不再使用 Basic Auth
214
+
215
+ ---
216
+
217
+ ## API 端點總覽
218
+
219
+ ### 物流相關 API
220
+
221
+ | 功能 | Method | 端點 | 說明 |
222
+ |------|--------|------|------|
223
+ | 取號列印交寄單 | POST | `/v1/logistic/batch` | 批次為超商取貨訂單取號並產生交寄單 |
224
+ | 查詢物流歷程 | GET | `/v1/logistic/query/{order_id}/history` | 取得指定訂單之物流狀態歷程 (JSON) |
225
+ | 物流歷程查詢頁 | GET | `/v1/logistic/query/{order_id}/history-page` | 取得物流歷程查詢頁 URL (HTML 頁面) |
226
+ | 查詢未出貨訂單 | GET | `/v1/logistic/yet` | 列出尚未交寄之超商取貨訂單 |
227
+ | 查詢未取貨訂單 | GET | `/v1/logistic/store_return/{date}` | 查詢買家未至超商取貨之物流編號 |
228
+ | 物流手續費對帳 | GET | `/v1/logistic/accounting/{date}` | 指定日期之物流手續費對帳資料 |
229
+ | 賠款入帳查詢 | GET | `/v1/logistic/compensation/{date}` | 指定月份貨物寄丟之賠款入帳資料 |
230
+
231
+ ### 共用 Headers
232
+
233
+ 所有物流 API 均需以下 header:
234
+
235
+ | Header | 必填 | 說明 |
236
+ |--------|------|------|
237
+ | `Content-Type` | ● | `application/json` |
238
+ | `pcpay-token` | ● | 由 `/v1/token` 取得之 token |
239
+
240
+ ---
241
+
242
+ ## 物流類型分類
243
+
244
+ ### 付款方式 (pay_type) 對照
245
+
246
+ PChomePay 物流訂單由金流訂單之 `pay_type` 決定。在 `POST /v1/payment` 建立訂單時填入:
247
+
248
+ | pay_type | 物流類型 | 說明 |
249
+ |----------|---------|------|
250
+ | `IPL7` | 7-11 超商取貨付款 | 統一超商交貨便 (C2C) |
251
+ | `IPLFM` | 全家超商取貨付款 | 全家便利商店 (C2C) |
252
+ | `IPLHL` | 萊爾富超商取貨付款 | 萊爾富 (C2C) |
253
+
254
+ > ⚠ PChomePay 目前不提供宅配 / 黑貓 / OK 超商等物流類型;OK (PLOK) 僅出現在對帳資料中作為歷史延續。
255
+
256
+ ### 訂單金額限制
257
+
258
+ 超商取貨付款訂單之金額限制:
259
+
260
+ ```
261
+ 65 ≦ amount ≦ 20,000 (新台幣)
262
+ ```
263
+
264
+ ### logistic_type (對帳資料用)
265
+
266
+ 對帳 / 賠款 API 回傳之 `logistic_type` 對應如下:
267
+
268
+ | logistic_type | 物流類型 |
269
+ |--------------|---------|
270
+ | `PL711` | 7-11 統一超商 |
271
+ | `PLFMI` | 全家 (FamilyMart) |
272
+ | `PLHIL` | 萊爾富 (Hi-Life) |
273
+ | `PLOK` | OK 超商 |
274
+
275
+ ### logistic_status (Notify 通知用)
276
+
277
+ 物流狀態通知中之 `logistic_status` 對應如下:
278
+
279
+ | logistic_status | 說明 |
280
+ |----------------|------|
281
+ | `SSND` | 商品已至「寄件門店」 |
282
+ | `SATB` | 商品已至「取件門店」 |
283
+ | `RATC` | 商品已至「退件門店」 |
284
+
285
+ ### 未出貨狀態 (status)
286
+
287
+ `/v1/logistic/yet` 回傳之狀態:
288
+
289
+ | status | 說明 |
290
+ |--------|------|
291
+ | `LINT` | 訂單建立 (尚未取號) |
292
+ | `LGNO` | 已取號 (尚未交寄) |
293
+
294
+ ---
295
+
296
+ ## 取號列印交寄單
297
+
298
+ 為超商取貨訂單批次取號並產生交寄單列印頁面 URL。
299
+
300
+ ### 端點
301
+
302
+ ```
303
+ POST https://api.pchomepay.com.tw/v1/logistic/batch
304
+ ```
305
+
306
+ ### 請求欄位
307
+
308
+ | 欄位 | 必填 | 型態 | 說明 |
309
+ |------|------|------|------|
310
+ | `order_id` | ● | Array | 欲列印交寄單之訂單編號陣列 |
311
+
312
+ ### cURL 範例
313
+
314
+ ```bash
315
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/batch' \
316
+ --header 'Content-Type: application/json' \
317
+ --header 'pcpay-token: __kJw1OMKTkwwssWPsAnGNtIzMYFIZ5ymmkq8nCd' \
318
+ --data '{
319
+ "order_id": ["B2C1702640091"]
320
+ }'
321
+ ```
322
+
323
+ ### 回應欄位
324
+
325
+ | 欄位 | 必填 | 型態 | 說明 |
326
+ |------|------|------|------|
327
+ | `print_no` | ● | String | 取號成功之交貨便服務代碼 |
328
+ | `error_order_id` | ● | String | 取號失敗之訂單編號 (成功時為 `null`) |
329
+ | `print_url` | ● | String | 交寄單頁面連結 |
330
+
331
+ ### 回應範例
332
+
333
+ ```json
334
+ {
335
+ "print_no": "N63399396760",
336
+ "error_order_id": null,
337
+ "print_url": "https://pay.pchomepay.com.tw/apipay/ppwf?_pwfkey_=TnR3Z3AzY20xbk1wZFE0cGEsdU00aFNGcGNwNjVzcVkzVEwxZ1JPeGR3YUc5QWkwMk5yakEwSFlvdk5ZWHFoaQ=="
338
+ }
339
+ ```
340
+
341
+ ### PHP 範例
342
+
343
+ ```php
344
+ <?php
345
+
346
+ function batchPrintShippingLabel(string $token, array $orderIds): array
347
+ {
348
+ $body = json_encode(['order_id' => $orderIds]);
349
+
350
+ $ch = curl_init();
351
+ curl_setopt_array($ch, [
352
+ CURLOPT_URL => 'https://api.pchomepay.com.tw/v1/logistic/batch',
353
+ CURLOPT_POST => true,
354
+ CURLOPT_POSTFIELDS => $body,
355
+ CURLOPT_RETURNTRANSFER => true,
356
+ CURLOPT_HTTPHEADER => [
357
+ 'Content-Type: application/json',
358
+ "pcpay-token: {$token}",
359
+ ],
360
+ ]);
361
+
362
+ $response = curl_exec($ch);
363
+ curl_close($ch);
364
+
365
+ return json_decode($response, true);
366
+ }
367
+
368
+ // 使用範例
369
+ $result = batchPrintShippingLabel($token, [
370
+ 'B2C1702640091',
371
+ 'B2C1702640092',
372
+ ]);
373
+
374
+ if ($result['error_order_id']) {
375
+ error_log("取號失敗:{$result['error_order_id']}");
376
+ } else {
377
+ // 將 print_url 開啟以列印交寄單
378
+ header("Location: {$result['print_url']}");
379
+ }
380
+ ```
381
+
382
+ ### Python 範例
383
+
384
+ ```python
385
+ import requests
386
+
387
+ def batch_print_shipping_label(token: str, order_ids: list) -> dict:
388
+ headers = {
389
+ "Content-Type": "application/json",
390
+ "pcpay-token": token,
391
+ }
392
+ payload = {"order_id": order_ids}
393
+ response = requests.post(
394
+ "https://api.pchomepay.com.tw/v1/logistic/batch",
395
+ headers=headers,
396
+ json=payload,
397
+ )
398
+ response.raise_for_status()
399
+ return response.json()
400
+
401
+
402
+ # 使用範例
403
+ result = batch_print_shipping_label(token, ["B2C1702640091"])
404
+ if result.get("error_order_id"):
405
+ print(f"取號失敗:{result['error_order_id']}")
406
+ else:
407
+ print(f"交寄單 URL:{result['print_url']}")
408
+ ```
409
+
410
+ ### 注意事項
411
+
412
+ 1. **必須在 30 天內完成取號**:超過則訂單失效
413
+ 2. **批次取號**:`order_id` 為陣列可一次處理多筆,但若任一筆失敗會回傳於 `error_order_id`
414
+ 3. **`print_url` 開啟即可列印**:頁面為 HTML,內含適合熱感印表機的格式
415
+ 4. **同訂單重複取號**:會回傳同一個 `print_no`,不會重複扣費
416
+
417
+ ---
418
+
419
+ ## 查詢物流歷程
420
+
421
+ 查詢指定訂單之物流狀態歷程 (JSON 格式)。
422
+
423
+ ### 端點
424
+
425
+ ```
426
+ GET https://api.pchomepay.com.tw/v1/logistic/query/{order_id}/history
427
+ ```
428
+
429
+ ### 路徑參數
430
+
431
+ | 參數 | 必填 | 型態 | 說明 |
432
+ |------|------|------|------|
433
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
434
+
435
+ ### cURL 範例
436
+
437
+ ```bash
438
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/query/B2C1723815435/history' \
439
+ --header 'Content-Type: application/json' \
440
+ --header 'pcpay-token: 0BZyFozlvqFtlwJoL5HQstTbNW_gNrNmsPQ4upc7'
441
+ ```
442
+
443
+ ### 回應欄位
444
+
445
+ | 欄位 | 必填 | 型態 | 說明 |
446
+ |------|------|------|------|
447
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
448
+ | `history` | ● | Array | 歷程紀錄陣列 |
449
+
450
+ ### history 物件
451
+
452
+ | 欄位 | 必填 | 型態 | 說明 |
453
+ |------|------|------|------|
454
+ | `logistic_id` | ● | String(50) | 超商物流代號 |
455
+ | `status` | ● | String(50) | 訂單與物流狀態(中文) |
456
+ | `status_date` | ● | String | 該狀態日期 (YYYY/MM/DD) |
457
+ | `status_time` | ● | String | 該狀態時間 (HH:MM:SS) |
458
+
459
+ ### status 狀態值
460
+
461
+ | status (中文) | 說明 |
462
+ |--------------|------|
463
+ | `訂單建立` | 訂單已成功建立但尚未取號 |
464
+ | `已交寄` | 商家已將商品交寄至物流 |
465
+ | `配送中` | 商品於物流配送中 |
466
+ | `已到店` | 商品已送達取件門市 |
467
+ | `已付款` | 用戶已至門市完成付款取貨 |
468
+ | `已撥付` | 款項已轉至商家可提領餘額 |
469
+
470
+ ### 回應範例
471
+
472
+ ```json
473
+ {
474
+ "order_id": "B2C1723815435",
475
+ "history": [
476
+ {
477
+ "logistic_id": "L24081201043969",
478
+ "status": "訂單建立",
479
+ "status_date": "2024/08/16",
480
+ "status_time": "21:37:15"
481
+ },
482
+ {
483
+ "logistic_id": "L24081201043969",
484
+ "status": "已交寄",
485
+ "status_date": "2024/08/16",
486
+ "status_time": "21:39:02"
487
+ }
488
+ ]
489
+ }
490
+ ```
491
+
492
+ ### Python 範例
493
+
494
+ ```python
495
+ import requests
496
+
497
+ def query_logistic_history(token: str, order_id: str) -> dict:
498
+ url = f"https://api.pchomepay.com.tw/v1/logistic/query/{order_id}/history"
499
+ headers = {
500
+ "Content-Type": "application/json",
501
+ "pcpay-token": token,
502
+ }
503
+ response = requests.get(url, headers=headers)
504
+ response.raise_for_status()
505
+ return response.json()
506
+
507
+
508
+ # 取出最新狀態
509
+ history = query_logistic_history(token, "B2C1723815435")
510
+ latest = history["history"][-1] if history["history"] else None
511
+ if latest:
512
+ print(f"目前狀態:{latest['status']} ({latest['status_date']} {latest['status_time']})")
513
+ ```
514
+
515
+ ---
516
+
517
+ ## 物流歷程查詢頁
518
+
519
+ 取得可直接呈現給用戶的物流歷程查詢頁 URL(HTML 頁面)。
520
+
521
+ ### 端點
522
+
523
+ ```
524
+ GET https://api.pchomepay.com.tw/v1/logistic/query/{order_id}/history-page
525
+ ```
526
+
527
+ ### 路徑參數
528
+
529
+ | 參數 | 必填 | 型態 | 說明 |
530
+ |------|------|------|------|
531
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
532
+
533
+ ### cURL 範例
534
+
535
+ ```bash
536
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/query/B2C1723815435/history-page' \
537
+ --header 'Content-Type: application/json' \
538
+ --header 'pcpay-token: e0A_XRsPMDgCKvRnrikpdMTfEJzvIGuveJsn_695'
539
+ ```
540
+
541
+ ### 回應欄位
542
+
543
+ | 欄位 | 必填 | 型態 | 說明 |
544
+ |------|------|------|------|
545
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
546
+ | `history_url` | ● | String | 物流歷程查詢頁 URL |
547
+
548
+ ### 回應範例
549
+
550
+ ```json
551
+ {
552
+ "logistic_id": "L24041201043748",
553
+ "history_url": "https://pchomepay.com.tw/apipay/ppwf?_pwfkey_=UjdkdVlreEV5cjlKRlRZeHdlUSxRUVVkVk0ta09uZGlINCxoRSxicEs2ZVB0UnhkcDBkY0RkZE84R0dSU3hFcA=="
554
+ }
555
+ ```
556
+
557
+ ### 應用情境
558
+
559
+ 1. **顧客自助查詢**:將 `history_url` 嵌入訂單頁面,顧客點擊即可查看完整物流歷程
560
+ 2. **客服 / 後台**:直接連結至 PChomePay 提供之 UI 頁面,省去自行渲染歷程的成本
561
+ 3. **與 `/history` 差異**:`/history` 回傳 JSON 由商家自行渲染;`/history-page` 直接提供完整 UI 頁面
562
+
563
+ ---
564
+
565
+ ## 未出貨/未取貨查詢
566
+
567
+ ### 查詢未出貨訂單
568
+
569
+ 列出已建立但尚未交寄至物流之超商取貨訂單。
570
+
571
+ #### 端點
572
+
573
+ ```
574
+ GET https://api.pchomepay.com.tw/v1/logistic/yet
575
+ ```
576
+
577
+ #### 請求欄位
578
+
579
+ 無
580
+
581
+ #### cURL 範例
582
+
583
+ ```bash
584
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/yet' \
585
+ --header 'Content-Type: application/json' \
586
+ --header 'pcpay-token: F6uG0pXXTPTHDMRkIj_HGnzrWJvom_m_HhPxf296'
587
+ ```
588
+
589
+ #### 回應欄位 (Array)
590
+
591
+ | 欄位 | 必填 | 型態 | 說明 |
592
+ |------|------|------|------|
593
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
594
+ | `status` | ● | String | 商品目前物流狀態 |
595
+
596
+ #### status 值
597
+
598
+ | status | 說明 |
599
+ |--------|------|
600
+ | `LINT` | 訂單建立 (尚未取號) |
601
+ | `LGNO` | 已取號 (尚未交寄) |
602
+
603
+ #### 回應範例
604
+
605
+ ```json
606
+ [
607
+ {
608
+ "order_id": "B2C1744189821",
609
+ "status": "LGNO"
610
+ },
611
+ {
612
+ "order_id": "B2C1744189822",
613
+ "status": "LINT"
614
+ }
615
+ ]
616
+ ```
617
+
618
+ #### 應用情境
619
+
620
+ - **每日交寄提醒**:每天透過此 API 撈出 `LGNO` 訂單,發送 reminder 給倉管人員
621
+ - **截止日警示**:搭配建單日期計算 T + N 天,於即將逾期時優先處理
622
+
623
+ ---
624
+
625
+ ### 查詢未取貨訂單
626
+
627
+ 查詢買家未至超商取貨之物流編號(指定日期已到店但尚未取貨)。
628
+
629
+ #### 端點
630
+
631
+ ```
632
+ GET https://api.pchomepay.com.tw/v1/logistic/store_return/{date}
633
+ ```
634
+
635
+ #### 路徑參數
636
+
637
+ | 參數 | 必填 | 型態 | 說明 |
638
+ |------|------|------|------|
639
+ | `date` | ● | String(8) | 欲查詢日期,格式 `YYYYMMDD` |
640
+
641
+ #### cURL 範例
642
+
643
+ ```bash
644
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/store_return/20250409' \
645
+ --header 'pcpay-token: F6uG0pXXTPTHDMRkIj_HGnzrWJvom_m_HhPxf296'
646
+ ```
647
+
648
+ #### 回應欄位 (Array)
649
+
650
+ | 欄位 | 必填 | 型態 | 說明 |
651
+ |------|------|------|------|
652
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
653
+ | `logistic_id` | ● | String(50) | 訂單物流編號 |
654
+ | `status` | ● | String | 商品目前物流狀態 (僅 `SATB`) |
655
+
656
+ #### 回應範例
657
+
658
+ ```json
659
+ [
660
+ {
661
+ "order_id": "B2C1744192674",
662
+ "logistic_id": "L25041201044206",
663
+ "status": "SATB"
664
+ }
665
+ ]
666
+ ```
667
+
668
+ > 此 API 僅回傳狀態為 `SATB` (商品已到取件門市) 但用戶尚未取走的訂單。
669
+
670
+ #### 應用情境
671
+
672
+ - **退件預警**:到店未取超過超商保留期限將自動退件(產生退件物流費)
673
+ - **客戶提醒**:撈出此清單,主動以 SMS / Email 提醒買家取貨
674
+
675
+ ---
676
+
677
+ ## 物流手續費對帳
678
+
679
+ 查詢指定日期之物流手續費對帳資料。
680
+
681
+ ### 端點
682
+
683
+ ```
684
+ GET https://api.pchomepay.com.tw/v1/logistic/accounting/{date}
685
+ ```
686
+
687
+ ### 路徑參數
688
+
689
+ | 參數 | 必填 | 型態 | 說明 |
690
+ |------|------|------|------|
691
+ | `date` | ● | String(8) | 對帳日期,格式 `YYYYMMDD`,僅能查詢 30 天前資料 |
692
+
693
+ ### cURL 範例
694
+
695
+ ```bash
696
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/accounting/20240816' \
697
+ --header 'pcpay-token: fGVWZrMrYEVLHbj1joxn7CpdjsygFYYN8vLaygGM'
698
+ ```
699
+
700
+ ### 回應格式
701
+
702
+ > ⚠ 此 API 為**特規 JSON 串接格式**:第一行為摘要 JSON,後續每筆訂單為獨立 JSON object(換行分隔,非標準 JSON Array)。
703
+
704
+ #### 第一行 (摘要)
705
+
706
+ | 欄位 | 必填 | 型態 | 說明 |
707
+ |------|------|------|------|
708
+ | `total_recs` | ● | String(5) | 該日對帳資料筆數 |
709
+
710
+ #### 明細欄位 (每行一筆)
711
+
712
+ | 欄位 | 必填 | 型態 | 說明 |
713
+ |------|------|------|------|
714
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
715
+ | `logistic_type` | ● | String | 物流類型 (`PL711` / `PLFMI` / `PLHIL` / `PLOK`) |
716
+ | `logistic_amount` | ● | Int | 物流手續費 (新台幣) |
717
+ | `accounting_date` | ● | String(14) | 帳務日期,格式 `YYYYMMDDhh24MiSS` |
718
+
719
+ ### 回應範例
720
+
721
+ ```
722
+ {"total_recs": 1}
723
+ {"order_id": "B2C1723809155", "logistic_type": "PL711", "logistic_amount": 65, "accounting_date": "20240816195407"}
724
+ {"order_id": "B2C1723808237", "logistic_type": "PLFMI", "logistic_amount": 65, "accounting_date": "20240818201412"}
725
+ ```
726
+
727
+ ### Python 解析範例
728
+
729
+ ```python
730
+ import requests
731
+ import json
732
+
733
+ def fetch_logistic_accounting(token: str, date: str) -> dict:
734
+ url = f"https://api.pchomepay.com.tw/v1/logistic/accounting/{date}"
735
+ headers = {"pcpay-token": token}
736
+ response = requests.get(url, headers=headers)
737
+ response.raise_for_status()
738
+
739
+ # 特規 JSON:以換行分隔每行為一個 JSON
740
+ lines = response.text.strip().splitlines()
741
+ summary = json.loads(lines[0])
742
+ records = [json.loads(line) for line in lines[1:] if line.strip()]
743
+ return {"summary": summary, "records": records}
744
+
745
+
746
+ result = fetch_logistic_accounting(token, "20240816")
747
+ print(f"共 {result['summary']['total_recs']} 筆")
748
+ for rec in result["records"]:
749
+ print(f"{rec['order_id']} - {rec['logistic_type']} - NT${rec['logistic_amount']}")
750
+ ```
751
+
752
+ ### 物流手續費注意事項
753
+
754
+ 1. **無論是否取貨成功,皆會收取物流手續費**:商品從交寄起就計算手續費
755
+ 2. **手續費為內扣**:訂單清算時自動從訂單金額中扣除,不另外請款
756
+ 3. **PChomePay 後台**:可至會員中心 > 對帳資料下載完整對帳檔
757
+ 4. **30 天保留期**:超過 30 天則無法查詢,請定期下載備份
758
+
759
+ ---
760
+
761
+ ## 賠款查詢
762
+
763
+ 查詢指定月份貨物寄丟之賠款入帳資料。
764
+
765
+ ### 端點
766
+
767
+ ```
768
+ GET https://api.pchomepay.com.tw/v1/logistic/compensation/{date}
769
+ ```
770
+
771
+ ### 路徑參數
772
+
773
+ | 參數 | 必填 | 型態 | 說明 |
774
+ |------|------|------|------|
775
+ | `date` | ● | String(6) | 入帳年月,格式 `YYYYMM` |
776
+
777
+ ### cURL 範例
778
+
779
+ ```bash
780
+ curl --location 'https://api.pchomepay.com.tw/v1/logistic/compensation/202408' \
781
+ --header 'pcpay-token: fGVWZrMrYEVLHbj1joxn7CpdjsygFYYN8vLaygGM'
782
+ ```
783
+
784
+ ### 回應格式
785
+
786
+ 與「物流手續費對帳」相同採特規 JSON:
787
+
788
+ #### 第一行 (摘要)
789
+
790
+ | 欄位 | 必填 | 型態 | 說明 |
791
+ |------|------|------|------|
792
+ | `total_recs` | ● | String(5) | 該月賠款筆數 |
793
+
794
+ #### 明細欄位
795
+
796
+ | 欄位 | 必填 | 型態 | 說明 |
797
+ |------|------|------|------|
798
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
799
+ | `logistic_type` | ● | String | 物流類型 (`PL711` / `PLFMI` / `PLHIL` / `PLOK`) |
800
+ | `logistic_amount` | ● | Int | 賠款金額 (新台幣) |
801
+ | `accounting_date` | ● | String(14) | 帳務日期,格式 `YYYYMMDDhh24MiSS` |
802
+
803
+ ### 回應範例
804
+
805
+ ```
806
+ {"total_recs": 1}
807
+ {"order_id": "B2C1723809155", "logistic_type": "PL711", "logistic_amount": 200, "accounting_date": "20240816195407"}
808
+ {"order_id": "B2C1723808237", "logistic_type": "PLFMI", "logistic_amount": 565, "accounting_date": "20240818201412"}
809
+ ```
810
+
811
+ ### 賠款說明
812
+
813
+ 1. **觸發條件**:商品於物流運送過程中遺失或損毀,由超商物流方核定後賠付
814
+ 2. **賠款金額**:依物流商賠付規範決定(通常為訂單金額之一定比例,最高有上限)
815
+ 3. **入帳方式**:直接撥付至 PChomePay 商家餘額
816
+ 4. **查詢範圍**:以月份為單位 (`YYYYMM`),可累積查詢
817
+
818
+ ---
819
+
820
+ ## 物流狀態通知
821
+
822
+ PChomePay 會在物流狀態變更時透過 `notify_url` 主動推送通知。
823
+
824
+ ### 通知格式
825
+
826
+ ```
827
+ Method: POST
828
+ Content-Type: application/x-www-form-urlencoded
829
+ ```
830
+
831
+ ### 通用參數
832
+
833
+ | 參數 | 說明 |
834
+ |------|------|
835
+ | `notify_type` | 通知類型 (`seller_dispatched` / `pickup_shipped` / `return_shipped`) |
836
+ | `notify_message` | JSON 格式之通知內容 (字串) |
837
+
838
+ ### notify_message 結構
839
+
840
+ | 欄位 | 必填 | 型態 | 說明 |
841
+ |------|------|------|------|
842
+ | `order_id` | ● | String(50) | 合作方訂單編號 |
843
+ | `pay_type` | ● | String(5) | 付款方式 (`IPL7` / `IPLFM` / `IPLHL`) |
844
+ | `logistic_info` | ● | Object | 物流資訊(見下) |
845
+
846
+ ### logistic_info 物件
847
+
848
+ | 欄位 | 必填 | 型態 | 說明 |
849
+ |------|------|------|------|
850
+ | `logistic_id` | ● | String(11) | 超商物流代號 |
851
+ | `logistic_status` | ● | String | 物流狀態 (`SSND` / `SATB` / `RATC`) |
852
+ | `logistic_type` | ● | String | 物流類型 (`C2C` 店到店, `B2C` 大宗寄倉,目前未提供) |
853
+ | `status_date` | ● | String(14) | 該狀態日期 (`YYYYMMDDhh24MiSS`) |
854
+
855
+ ### 通知類型
856
+
857
+ #### seller_dispatched (商品已至寄件門店)
858
+
859
+ 當商家將商品交寄至超商寄件門市時觸發。
860
+
861
+ ```bash
862
+ curl --location 'https://your-site.com/notify' \
863
+ --header 'Content-Type: application/x-www-form-urlencoded' \
864
+ --data-urlencode 'notify_type=seller_dispatched' \
865
+ --data-urlencode 'notify_message={
866
+ "order_id":"B2C_Uni_1769857427",
867
+ "pay_type":"IPL7",
868
+ "logistic_info":{
869
+ "logistic_id":"M22216559430",
870
+ "logistic_status":"SSND",
871
+ "logistic_type":"C2C",
872
+ "status_date":"20250924183250"
873
+ }
874
+ }'
875
+ ```
876
+
877
+ #### pickup_shipped (商品已至取件門店)
878
+
879
+ 當商品送達買家指定的取件門市時觸發 → 商家可發送通知請買家前往取貨。
880
+
881
+ ```bash
882
+ curl --location 'https://your-site.com/notify' \
883
+ --header 'Content-Type: application/x-www-form-urlencoded' \
884
+ --data-urlencode 'notify_type=pickup_shipped' \
885
+ --data-urlencode 'notify_message={
886
+ "order_id":"B2C_Uni_1769850289",
887
+ "pay_type":"IPL7",
888
+ "logistic_info":{
889
+ "logistic_id":"M22216568132",
890
+ "logistic_status":"SATB",
891
+ "logistic_type":"C2C",
892
+ "status_date":"20250925212043"
893
+ }
894
+ }'
895
+ ```
896
+
897
+ #### return_shipped (商品已至退件門店)
898
+
899
+ 當買家未取貨或主動退貨,商品送達退件門市時觸發。
900
+
901
+ ```bash
902
+ curl --location 'https://your-site.com/notify' \
903
+ --header 'Content-Type: application/x-www-form-urlencoded' \
904
+ --data-urlencode 'notify_type=return_shipped' \
905
+ --data-urlencode 'notify_message={
906
+ "order_id":"B2C_Uni_1769853160",
907
+ "pay_type":"IPL7",
908
+ "logistic_info":{
909
+ "logistic_id":"M22216577821",
910
+ "logistic_status":"RATC",
911
+ "logistic_type":"C2C",
912
+ "status_date":"20250927090822"
913
+ }
914
+ }'
915
+ ```
916
+
917
+ ### PHP 接收範例
918
+
919
+ ```php
920
+ <?php
921
+
922
+ // 接收 PChomePay 物流狀態通知
923
+ $notifyType = $_POST['notify_type'] ?? '';
924
+ $notifyMessage = json_decode($_POST['notify_message'] ?? '{}', true);
925
+
926
+ if (!$notifyMessage) {
927
+ http_response_code(400);
928
+ exit('invalid notify_message');
929
+ }
930
+
931
+ $orderId = $notifyMessage['order_id'];
932
+ $status = $notifyMessage['logistic_info']['logistic_status'];
933
+
934
+ switch ($notifyType) {
935
+ case 'seller_dispatched':
936
+ // 商品已交寄
937
+ updateOrderStatus($orderId, 'shipped');
938
+ break;
939
+ case 'pickup_shipped':
940
+ // 商品已到店,可發送取貨通知
941
+ updateOrderStatus($orderId, 'arrived_at_store');
942
+ sendPickupReminder($orderId);
943
+ break;
944
+ case 'return_shipped':
945
+ // 商品退件
946
+ updateOrderStatus($orderId, 'returned');
947
+ break;
948
+ }
949
+
950
+ // PChomePay 不要求特定回應,回 200 即可
951
+ http_response_code(200);
952
+ echo 'OK';
953
+ ```
954
+
955
+ ### Python 接收範例 (Flask)
956
+
957
+ ```python
958
+ import json
959
+ from flask import Flask, request
960
+
961
+ app = Flask(__name__)
962
+
963
+ @app.route('/pchomepay-notify', methods=['POST'])
964
+ def pchomepay_notify():
965
+ notify_type = request.form.get('notify_type')
966
+ notify_message = request.form.get('notify_message', '{}')
967
+
968
+ try:
969
+ message = json.loads(notify_message)
970
+ except json.JSONDecodeError:
971
+ return 'invalid notify_message', 400
972
+
973
+ order_id = message['order_id']
974
+ logistic_status = message['logistic_info']['logistic_status']
975
+
976
+ if notify_type == 'seller_dispatched':
977
+ update_order(order_id, 'shipped')
978
+ elif notify_type == 'pickup_shipped':
979
+ update_order(order_id, 'arrived_at_store')
980
+ elif notify_type == 'return_shipped':
981
+ update_order(order_id, 'returned')
982
+
983
+ return 'OK', 200
984
+ ```
985
+
986
+ ### 通知處理注意事項
987
+
988
+ 1. **重試機制**:PChomePay 若收到非 200 回應,會自動重試多次
989
+ 2. **驗證來源 IP**:建議白名單檢查 `113.196.231.190` 為唯一允許來源
990
+ 3. **冪等處理**:同一狀態變更可能收到多次通知,需以 `order_id + logistic_status + status_date` 去重
991
+ 4. **非阻塞處理**:建議以 queue / async 處理通知內容,避免回應延遲
992
+
993
+ ---
994
+
995
+ ## 錯誤代碼
996
+
997
+ ### 物流相關錯誤代碼
998
+
999
+ | 代碼 | 英文描述 | 中文描述 |
1000
+ |------|---------|---------|
1001
+ | `90001` | invalid status | 物流狀態錯誤 |
1002
+ | `90002` | logistic status history not found | 物流狀態歷程不存在 |
1003
+ | `90004` | Print delivery note fail. | 列印交寄單失敗 |
1004
+
1005
+ ### 認證 / 通用錯誤代碼
1006
+
1007
+ | 代碼 | 英文描述 | 中文描述 |
1008
+ |------|---------|---------|
1009
+ | `10001` | invalid user password | APPID 和 Secret 錯誤 |
1010
+ | `10002` | Server IP not allow | 不被允許的 IP 位址 |
1011
+ | `10003` | invalid token | token 錯誤 |
1012
+ | `10004` | token expired | token 逾期 |
1013
+ | `10006` | api client has not set notifyURL or returnURL yet | 未設定 notifyURL 或 returnURL |
1014
+ | `10007` | function unavailable | 會員帳號暫時無法使用功能服務 |
1015
+
1016
+ ### 訂單相關錯誤代碼
1017
+
1018
+ | 代碼 | 英文描述 | 中文描述 |
1019
+ |------|---------|---------|
1020
+ | `20001` | order id duplicate | 訂單編號不可重複 |
1021
+ | `20002` | order not exists | 訂單不存在 |
1022
+ | `20003` | pay type not support | 付款類別錯誤 |
1023
+ | `20005` | params is not valid | 參數錯誤 |
1024
+ | `20007` | It not allow to check today's data | 目前無法查詢當日資料 |
1025
+ | `20009` | Request data is not a json structure data | 請求格式不是 JSON |
1026
+ | `20014` | cvs setting error. | 未設定超商退貨門市 |
1027
+
1028
+ ### 錯誤回應格式
1029
+
1030
+ ```json
1031
+ {
1032
+ "error_type": "invalid_request_error",
1033
+ "code": 90004,
1034
+ "message": "Print delivery note fail."
1035
+ }
1036
+ ```
1037
+
1038
+ ---
1039
+
1040
+ ## 常見問題排解
1041
+
1042
+ ### Q1: 取號失敗 (90004) 該如何處理?
1043
+
1044
+ **可能原因**:
1045
+
1046
+ 1. 訂單付款方式不是超商取貨 (`IPL7` / `IPLFM` / `IPLHL`)
1047
+ 2. 用戶尚未在付款頁面選擇取件門市
1048
+ 3. 訂單已超過 30 天取號期限
1049
+ 4. 訂單狀態異常 (失敗 / 退款)
1050
+
1051
+ **處理方式**:
1052
+
1053
+ - 先呼叫 `GET /v1/payment/{order_id}` 查詢訂單狀態
1054
+ - 確認 `payment_info.store_id` 是否已存在 (代表用戶已選門市)
1055
+ - 若超過 30 天,需請用戶重新下單
1056
+
1057
+ ### Q2: 為何收不到物流通知?
1058
+
1059
+ **檢查清單**:
1060
+
1061
+ 1. **`notify_url` 設定**:在 PChomePay 後台 > 環境設定 > Notify URL 是否設定正確
1062
+ 2. **IP 白名單**:是否將 `113.196.231.190` 加入防火牆白名單
1063
+ 3. **HTTPS 憑證**:notify URL 須為有效的 HTTPS 端點 (建議使用 Let's Encrypt 等正式憑證)
1064
+ 4. **回應狀態碼**:notify 接收端需回應 200,否則 PChomePay 會持續重試
1065
+ 5. **建立訂單時 `notify_url`**:可於 `POST /v1/payment` 個別覆蓋預設值
1066
+
1067
+ ### Q3: 物流訂單可以重新取號嗎?
1068
+
1069
+ **答**:
1070
+
1071
+ - **同一筆訂單可重複呼叫 `/v1/logistic/batch`**:會回傳同一個 `print_no`,不會重複扣費
1072
+ - **若要更換門市**:無法透過 API,需請買家重新下單
1073
+
1074
+ ### Q4: 如何處理「已到店但用戶未取貨」?
1075
+
1076
+ **SOP**:
1077
+
1078
+ ```
1079
+ 1. 透過 GET /v1/logistic/store_return/{date} 撈出 SATB 但未付款訂單
1080
+ 2. 主動以 SMS / Email 通知買家取貨
1081
+ 3. 超過 7 天後(超商保留期限),商品會自動退件
1082
+ 4. 收到 return_shipped 通知後,自動標記訂單為「退件」狀態
1083
+ 5. 商家從退件門市領回商品
1084
+ ```
1085
+
1086
+ ### Q5: 物流手續費何時收取?
1087
+
1088
+ **答**:
1089
+
1090
+ - **時機**:商品從寄件門店交寄起即收取
1091
+ - **金額**:依各超商之合約價(一般 7-11 / 全家為 NT$65 / 件,實際以後台公告為準)
1092
+ - **無論取貨成敗皆收取**:包括買家未取貨退件
1093
+ - **退款不退手續費**:退款時手續費不會退還,且會額外收取 NT$15 退款手續費
1094
+
1095
+ ### Q6: 是否支援自有物流?
1096
+
1097
+ **答**:
1098
+
1099
+ - PChomePay **僅支援自家整合的超商取貨服務**
1100
+ - 若需使用其他物流(黑貓、新竹貨運、自取等),需自行另外串接 ECPay / PayUni / 物流商 API
1101
+ - PChomePay 會專注於「金流 + 超商取貨」一站式服務的整合
1102
+
1103
+ ### Q7: 與 ECPay / PayUni 物流的差異?
1104
+
1105
+ | 比較項目 | PChomePay | ECPay | PayUni |
1106
+ |---------|-----------|-------|--------|
1107
+ | 物流獨立串接 | ❌ 必須先建金流訂單 | ✅ 物流可獨立串接 | ✅ 物流可獨立串接 |
1108
+ | 支援超商 | 7-11 / 全家 / 萊爾富 | 4 大超商 + 黑貓 + 宅配通 | 7-11 + 黑貓 |
1109
+ | 認證方式 | OAuth-like (Basic Auth → token) | CheckMacValue (MD5) | AES-256-GCM + HMAC |
1110
+ | 物流類型 | C2C 店到店 | C2C / B2C | C2C |
1111
+ | Notify 格式 | x-www-form-urlencoded + JSON | x-www-form-urlencoded | JSON / 加密 |
1112
+
1113
+ ### Q8: 如何測試 Sandbox 環境?
1114
+
1115
+ **測試步驟**:
1116
+
1117
+ 1. 申請正式及測試 APP_ID / SECRET(聯絡 PChomePay 業務)
1118
+ 2. 使用 sandbox URL:`https://sandbox-api.pchomepay.com.tw`
1119
+ 3. 建立超商取貨訂單,金額尾數依[測試規則](#sandbox-測試規則超商取貨)模擬不同狀態
1120
+ 4. 在 sandbox 後台查看訂單與物流狀態
1121
+
1122
+ ### Q9: 訂單狀態 WD 是什麼意思?
1123
+
1124
+ **答**:
1125
+
1126
+ - `WD` = **超商取貨等待商品交寄**
1127
+ - 此狀態出現在 `GET /v1/payment/{order_id}` 之 `status_code`
1128
+ - 代表用戶已成功下單並選擇門市,但商家尚未取號交寄
1129
+ - 此時應呼叫 `POST /v1/logistic/batch` 取號 → 列印交寄單 → 交寄
1130
+
1131
+ ### Q10: 對帳 / 賠款 API 為何回應不是標準 JSON?
1132
+
1133
+ **答**:
1134
+
1135
+ - 文件明確說明:「API 除對帳為特規 JSON 外,其他所有請求以及回應都以 JSON 做為標準請求或回傳格式」
1136
+ - 對帳 / 賠款 API 採**逐行 JSON (NDJSON / JSONL) 格式**:
1137
+ - 第一行:摘要(`total_recs`)
1138
+ - 後續每行:一筆訂單之 JSON object
1139
+ - 不可使用 `json.loads(response.text)` 直接解析,需逐行解析([參考解析範例](#python-解析範例))
1140
+
1141
+ ---
1142
+
1143
+ ## 官方資源
1144
+
1145
+ - **官方網站**: https://www.pchomepay.com.tw/
1146
+ - **API 文件**: https://docs.google.com/document/d/1dPIPJc4xfyjkJ1i2yxaja4OP0G-iGFRXM08NDMuttZE/
1147
+ - **後台管理**: https://web.pchomepay.com.tw/
1148
+ - **WooCommerce 模組**: [PChomePay WooCommerce User Guide](https://docs.google.com/document/d/1ItCUQvY0A4VeVAlOdAMbt48lKB-xlNVZCu7E6L9d0Mg/)
1149
+ - **舊版購物車模組**: https://github.com/PChomePayPlugin
1150
+ - **技術服務信箱**: tech_support@pchomepay.com.tw
1151
+
1152
+ ---
1153
+
1154
+ 最後更新:2026/05/07