taiwan-logistics-skill 1.2.2 → 1.3.0

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.
Files changed (46) hide show
  1. package/README.md +132 -132
  2. package/assets/taiwan-logistics/CLAUDE.md +147 -137
  3. package/assets/taiwan-logistics/EXAMPLES.md +3258 -3258
  4. package/assets/taiwan-logistics/README.md +132 -132
  5. package/assets/taiwan-logistics/SKILL.md +845 -845
  6. package/assets/taiwan-logistics/data/field-mappings.csv +23 -27
  7. package/assets/taiwan-logistics/data/logistics-types.csv +29 -25
  8. package/assets/taiwan-logistics/data/operations.csv +32 -32
  9. package/assets/taiwan-logistics/data/providers.csv +20 -15
  10. package/assets/taiwan-logistics/data/status-codes.csv +89 -35
  11. package/assets/taiwan-logistics/examples/ecpay-logistics-cvs-example.py +175 -175
  12. package/assets/taiwan-logistics/examples/newebpay-logistics-cvs-example.py +524 -524
  13. package/assets/taiwan-logistics/examples/payuni-logistics-cvs-example.py +605 -605
  14. package/assets/taiwan-logistics/examples/store-map-integration-example.html +573 -573
  15. package/assets/taiwan-logistics/references/NEWEBPAY_LOGISTICS_REFERENCE.md +774 -774
  16. package/assets/taiwan-logistics/references/carrier-direct-access.md +134 -0
  17. package/assets/taiwan-logistics/references/ecpay-logistics-api.md +536 -536
  18. package/assets/taiwan-logistics/references/ezship-logistics-api.md +103 -0
  19. package/assets/taiwan-logistics/references/hct-logistics-api.md +1102 -1102
  20. package/assets/taiwan-logistics/references/lalamove-logistics-api.md +138 -0
  21. package/assets/taiwan-logistics/references/paynow-logistics-api.md +1670 -1670
  22. package/assets/taiwan-logistics/references/payuni-logistics-api.md +712 -712
  23. package/assets/taiwan-logistics/references/pchomepay-logistics-api.md +1154 -1154
  24. package/assets/taiwan-logistics/references/smilepay-logistics-api.md +1332 -1332
  25. package/assets/taiwan-logistics/scripts/core.py +276 -276
  26. package/assets/taiwan-logistics/scripts/generate-logistics-service.py +1248 -1248
  27. package/assets/taiwan-logistics/scripts/recommend.py +370 -364
  28. package/assets/taiwan-logistics/scripts/search.py +127 -127
  29. package/assets/taiwan-logistics/scripts/test_logistics.py +300 -300
  30. package/assets/templates/base/quick-reference.md +74 -74
  31. package/assets/templates/base/skill-content.md +845 -845
  32. package/assets/templates/platforms/agent.json +26 -26
  33. package/assets/templates/platforms/claude.json +26 -26
  34. package/assets/templates/platforms/codebuddy.json +25 -25
  35. package/assets/templates/platforms/codex.json +26 -26
  36. package/assets/templates/platforms/continue.json +25 -25
  37. package/assets/templates/platforms/copilot.json +25 -25
  38. package/assets/templates/platforms/cursor.json +26 -26
  39. package/assets/templates/platforms/gemini.json +25 -25
  40. package/assets/templates/platforms/kiro.json +25 -25
  41. package/assets/templates/platforms/opencode.json +25 -25
  42. package/assets/templates/platforms/qoder.json +25 -25
  43. package/assets/templates/platforms/roocode.json +25 -25
  44. package/assets/templates/platforms/trae.json +25 -25
  45. package/assets/templates/platforms/windsurf.json +25 -25
  46. package/package.json +65 -65
@@ -1,845 +1,845 @@
1
- # Taiwan Logistics Development Skill
2
-
3
- **Comprehensive guide for Taiwan Logistics integration (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow + HCT direct API)**
4
-
5
- ---
6
-
7
- ## Supported Providers
8
-
9
- This skill covers **6 logistics aggregators** + **1 direct carrier API**:
10
-
11
- | Provider | 類型 | Reference |
12
- |---|---|---|
13
- | **ECPay 綠界** | aggregator | `references/ecpay-logistics-api.md` |
14
- | **NewebPay 藍新** | aggregator | `references/NEWEBPAY_LOGISTICS_REFERENCE.md` |
15
- | **PAYUNi 統一** | aggregator | `references/payuni-logistics-api.md` |
16
- | **SmilePay 速買配** | aggregator (含 7-11/全家 + 黑貓 Pay_zg 矩陣) | `references/smilepay-logistics-api.md` |
17
- | **PChomePay 拍錢包** | aggregator (金物流二合一) | `references/pchomepay-logistics-api.md` |
18
- | **PayNow 立吉富** | aggregator (11 條產品線, 3DES/ECB/Zero-Padding) | `references/paynow-logistics-api.md` |
19
- | **HCT 新竹物流** | **直連 carrier API** | `references/hct-logistics-api.md` |
20
-
21
- > 註:選用 `HCT 直連 API` 適合大量出貨企業;一般電商透過 aggregator (`LogisticsType=HCT`) 走 HCT 配送即可,不需自行串接。
22
-
23
- ---
24
-
25
- ## Quick Reference
26
-
27
- ### Core Concepts
28
-
29
- **Logistics Types:**
30
- - **B2C (大宗寄倉)**: Bulk warehouse shipping - Merchant ships to logistics center, then distributed to stores
31
- - **C2C (店到店)**: Store-to-store - Merchant ships to convenience store, then delivered to pickup store
32
-
33
- **Trade Types:**
34
- - **取貨付款 (Cash on Delivery)**: Customer pays when picking up
35
- - **取貨不付款 (No Payment)**: Customer only picks up (payment already completed)
36
-
37
- **Supported Convenience Stores:**
38
- 1. 7-ELEVEN
39
- 2. FamilyMart (全家)
40
- 3. Hi-Life (萊爾富)
41
- 4. OK Mart
42
-
43
- **Key APIs:**
44
- 1. Store Map Query - Select pickup/sender store
45
- 2. Create Shipment - Create logistics order
46
- 3. Get Shipment Number - Get shipping code
47
- 4. Print Label - Print shipping label
48
- 5. Query Shipment - Check order status
49
- 6. Modify Shipment - Update order details
50
- 7. Track Shipment - Track delivery history
51
- 8. Status Notification - Real-time status updates
52
-
53
- ---
54
-
55
- ## Service Providers
56
-
57
- ### NewebPay Logistics (藍新物流)
58
-
59
- **Encryption**: AES-256-CBC + SHA256 (same as NewebPay payment)
60
-
61
- **API Style**: Form POST with AES encryption
62
-
63
- **Supported Services:**
64
- - C2C Store-to-Store: 4 convenience stores (7-11, FamilyMart, Hi-Life, OK Mart)
65
- - B2C Bulk Warehouse: 7-ELEVEN only
66
-
67
- **Test Environment:**
68
- - Store Map: `https://ccore.newebpay.com/API/Logistic/storeMap`
69
- - Create Shipment: `https://ccore.newebpay.com/API/Logistic/createShipment`
70
- - Get Shipment No: `https://ccore.newebpay.com/API/Logistic/getShipmentNo`
71
- - Print Label: `https://ccore.newebpay.com/API/Logistic/printLabel`
72
- - Query Shipment: `https://ccore.newebpay.com/API/Logistic/queryShipment`
73
- - Modify Shipment: `https://ccore.newebpay.com/API/Logistic/modifyShipment`
74
- - Track Shipment: `https://ccore.newebpay.com/API/Logistic/trace`
75
-
76
- **Production Environment:**
77
- - Replace `ccore.newebpay.com` with `core.newebpay.com`
78
-
79
- ---
80
-
81
- ### ECPay Logistics (綠界物流)
82
-
83
- **Encryption**: MD5 CheckMacValue
84
-
85
- **API Style**: Form POST with URL-encoded parameters
86
-
87
- **Supported Services:**
88
- - C2C Store-to-Store: 4 convenience stores (7-11, FamilyMart, Hi-Life, OK Mart)
89
- - C2C Frozen: 7-ELEVEN frozen goods
90
- - Home Delivery: T-Cat, HCT, Pelican Express
91
-
92
- **Test Environment:**
93
- - Base URL: `https://logistics-stage.ecpay.com.tw`
94
- - Create: `POST /Express/Create`
95
- - Query: `POST /Helper/QueryLogisticsTradeInfo/V2`
96
- - Print: `POST /helper/printTradeDocument`
97
- - Map: `POST /Express/map`
98
-
99
- **Production Environment:**
100
- - Base URL: `https://logistics.ecpay.com.tw`
101
-
102
- **Logistics SubTypes (CVS):**
103
- - `FAMI` - FamilyMart (全家)
104
- - `UNIMART` - 7-ELEVEN (常溫)
105
- - `UNIMARTFREEZE` - 7-ELEVEN (冷凍)
106
- - `HILIFE` - Hi-Life (萊爾富)
107
- - `OKMART` - OK Mart
108
-
109
- **Logistics SubTypes (Home Delivery):**
110
- - `TCAT` - T-Cat (黑貓宅急便)
111
- - `ECAN` - HCT (新竹物流)
112
- - `POST` - Pelican Express (宅配通)
113
-
114
- **Temperature Control (Home Delivery):**
115
- - `0001` - Normal temperature (常溫)
116
- - `0002` - Refrigerated (冷藏)
117
- - `0003` - Frozen (冷凍)
118
-
119
- **Specification (Package Size):**
120
- - `0001` - 60cm
121
- - `0002` - 90cm
122
- - `0003` - 120cm
123
- - `0004` - 150cm
124
-
125
- **Distance (Delivery Range):**
126
- - `00` - Same district
127
- - `01` - Same city
128
- - `02` - Cross city
129
- - `03` - Outlying islands
130
-
131
- **Test Credentials:**
132
- - MerchantID: `2000132`
133
- - HashKey: `5294y06JbISpM5x9`
134
- - HashIV: `v77hoKGq4kWxNNIS`
135
-
136
- ---
137
-
138
- ### PAYUNi Logistics (統一物流)
139
-
140
- **Encryption**: AES-256-GCM + SHA256 (same as PAYUNi payment)
141
-
142
- **API Style**: RESTful JSON with AES-GCM encryption
143
-
144
- **Supported Services:**
145
- - C2C Store-to-Store: 7-ELEVEN (normal temperature + frozen)
146
- - B2C Bulk Warehouse: 7-ELEVEN only
147
- - Home Delivery: T-Cat (normal temperature, frozen, refrigerated)
148
-
149
- **Test Environment:**
150
- - Base URL: `https://sandbox-api.payuni.com.tw/api/`
151
- - Create Shipment: `POST /logistics/create`
152
- - Query Shipment: `POST /logistics/query`
153
- - Cancel Shipment: `POST /logistics/cancel`
154
-
155
- **Production Environment:**
156
- - Base URL: `https://api.payuni.com.tw/api/`
157
-
158
- **Logistics Types:**
159
- - `PAYUNi_Logistic_711` - 7-11 C2C (normal temperature)
160
- - `PAYUNi_Logistic_711_Freeze` - 7-11 C2C (frozen)
161
- - `PAYUNi_Logistic_711_B2C` - 7-11 B2C (bulk warehouse)
162
- - `PAYUNi_Logistic_Tcat` - T-Cat home delivery (normal)
163
- - `PAYUNi_Logistic_Tcat_Freeze` - T-Cat frozen
164
- - `PAYUNi_Logistic_Tcat_Cold` - T-Cat refrigerated
165
-
166
- **Temperature Codes:**
167
- - `1` - Normal temperature
168
- - `2` - Frozen
169
- - `3` - Refrigerated (T-Cat only)
170
-
171
- **Size & Weight Limits:**
172
- - Normal temperature: 150cm material volume, 20kg
173
- - Frozen/Refrigerated: 120cm material volume, 15kg
174
- - Material volume calculation: Length + Width + Height ≤ Limit
175
-
176
- ---
177
-
178
- ## Transaction Flows
179
-
180
- ### 1. B2C Bulk Warehouse - Cash on Delivery
181
-
182
- 1. **Create Order**: Customer selects store, merchant calls Create Shipment API
183
- 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
184
- 3. **Merchant Ships**: Merchant delivers goods to logistics center
185
- 4. **Logistics Distributes**: Logistics center verifies and distributes to pickup store
186
- 5. **Customer Picks Up**: Customer picks up and pays, NewebPay notifies merchant
187
-
188
- ### 2. C2C Store-to-Store - Cash on Delivery
189
-
190
- 1. **Create Order**: Customer selects store, merchant calls Create Shipment API
191
- 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
192
- 3. **Merchant Ships**: Merchant delivers goods to sender store
193
- 4. **Store Ships**: Sender store ships to logistics center, then to pickup store
194
- 5. **Customer Picks Up**: Customer picks up and pays, NewebPay notifies merchant
195
-
196
- ### 3. B2C Bulk Warehouse - No Payment
197
-
198
- 1. **Create Order**: Customer selects store (payment already completed)
199
- 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
200
- 3. **Merchant Ships**: Merchant delivers goods to logistics center
201
- 4. **Logistics Distributes**: Logistics center verifies and distributes to pickup store
202
- 5. **Customer Picks Up**: Customer picks up, NewebPay notifies merchant
203
-
204
- ### 4. C2C Store-to-Store - No Payment
205
-
206
- 1. **Create Order**: Customer selects store (payment already completed)
207
- 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
208
- 3. **Merchant Ships**: Merchant delivers goods to sender store
209
- 4. **Store Ships**: Sender store ships to logistics center, then to pickup store
210
- 5. **Customer Picks Up**: Customer picks up, NewebPay notifies merchant
211
-
212
- ---
213
-
214
- ## API Operations
215
-
216
- ### 1. Store Map Query API [NPA-B51]
217
-
218
- Query convenience store locations for pickup or sender.
219
-
220
- **Endpoint:**
221
- - Test: `https://ccore.newebpay.com/API/Logistic/storeMap`
222
- - Production: `https://core.newebpay.com/API/Logistic/storeMap`
223
-
224
- **Request Parameters:**
225
-
226
- | Field | Description | Type | Required |
227
- |-------|-------------|------|----------|
228
- | UID_ | Merchant ID | Varchar(15) | V |
229
- | EncryptData_ | Encrypted data | Text | V |
230
- | HashData_ | Hash data | Text | V |
231
- | Version_ | API version | Varchar(5) | V |
232
- | RespondType_ | Response format | Varchar(6) | V |
233
-
234
- **EncryptData_ Parameters:**
235
-
236
- | Field | Description | Type | Required | Notes |
237
- |-------|-------------|------|----------|-------|
238
- | MerchantOrderNo | Merchant order number | Varchar(30) | V | Unique order ID |
239
- | LgsType | Logistics type | Varchar(15) | V | B2C or C2C |
240
- | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
241
- | ReturnURL | Return URL | Varchar(50) | V | URL after store selection |
242
- | TimeStamp | Unix timestamp | Text | V | Current time in seconds |
243
- | ExtraData | Extra data | Varchar(20) | - | Returned as-is |
244
-
245
- **Response EncryptData_ Parameters:**
246
-
247
- | Field | Description | Type | Notes |
248
- |-------|-------------|------|-------|
249
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
250
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
251
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
252
- | StoreName | Store name | Varchar(10) | Selected store name |
253
- | StoreTel | Store phone | Varchar(12) | Store phone number |
254
- | StoreAddr | Store address | Varchar(100) | Store address |
255
- | StoreID | Store code | Varchar(8) | Store ID (use this for shipment) |
256
- | ExtraData | Extra data | Varchar(20) | Original value returned |
257
-
258
- ---
259
-
260
- ### 2. Create Shipment API [NPA-B52]
261
-
262
- Create logistics shipment order after payment order is established.
263
-
264
- **Endpoint:**
265
- - Test: `https://ccore.newebpay.com/API/Logistic/createShipment`
266
- - Production: `https://core.newebpay.com/API/Logistic/createShipment`
267
-
268
- **EncryptData_ Parameters:**
269
-
270
- | Field | Description | Type | Required | Notes |
271
- |-------|-------------|------|----------|-------|
272
- | MerchantOrderNo | Merchant order number | Varchar(30) | V | Unique order ID |
273
- | TradeType | Trade type | Int(1) | V | 1=COD, 3=No Payment |
274
- | UserName | Recipient name | Varchar(20) | V | Pickup person name |
275
- | UserTel | Recipient phone | Varchar(10) | V | Mobile number |
276
- | UserEmail | Recipient email | Varchar(50) | V | Email address |
277
- | StoreID | Pickup store ID | Varchar(10) | V | From store map query |
278
- | Amt | Transaction amount | Int(10) | V | Order amount |
279
- | NotifyURL | Notification URL | Varchar(100) | - | Pickup completion callback |
280
- | ItemDesc | Product description | Varchar(100) | - | Product name |
281
- | LgsType | Logistics type | Varchar(3) | V | B2C or C2C |
282
- | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
283
- | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
284
-
285
- **Response EncryptData_ Parameters:**
286
-
287
- | Field | Description | Type | Notes |
288
- |-------|-------------|------|-------|
289
- | MerchantID | Merchant ID | Varchar(15) | NewebPay merchant ID |
290
- | Amt | Transaction amount | Int(10) | Order amount |
291
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
292
- | TradeNo | NewebPay trade number | Varchar(20) | Platform transaction ID |
293
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
294
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
295
- | StoreID | Pickup store ID | Varchar(10) | Store code |
296
- | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
297
-
298
- ---
299
-
300
- ### 3. Get Shipment Number API [NPA-B53]
301
-
302
- Get shipping code before shipment. Merchants can print labels at convenience store Kiosk.
303
-
304
- **Endpoint:**
305
- - Test: `https://ccore.newebpay.com/API/Logistic/getShipmentNo`
306
- - Production: `https://core.newebpay.com/API/Logistic/getShipmentNo`
307
-
308
- **EncryptData_ Parameters:**
309
-
310
- | Field | Description | Type | Required | Notes |
311
- |-------|-------------|------|----------|-------|
312
- | MerchantOrderNo | Merchant order numbers | Json_array | V | Max 10 orders at once |
313
- | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
314
-
315
- **Response EncryptData_ Parameters:**
316
-
317
- | Field | Description | Type | Notes |
318
- |-------|-------------|------|-------|
319
- | SUCCESS | Success array | Json_array | Multiple records |
320
- | ERROR | Error array | Json_array | Multiple records |
321
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
322
- | ErrorCode | Error code | Varchar(20) | SUCCESS or error code |
323
- | LgsNo | Shipment number | Varchar(20) | Logistics tracking number |
324
- | StorePrintNo | Store print code | Varchar(20) | Code for Kiosk printing |
325
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
326
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
327
-
328
- ---
329
-
330
- ### 4. Print Label API [NPA-B54]
331
-
332
- Print shipping labels to attach to products.
333
-
334
- **Endpoint:**
335
- - Test: `https://ccore.newebpay.com/API/Logistic/printLabel`
336
- - Production: `https://core.newebpay.com/API/Logistic/printLabel`
337
-
338
- **Important**: Must use Form POST method (not JSON API call)
339
-
340
- **EncryptData_ Parameters:**
341
-
342
- | Field | Description | Type | Required | Notes |
343
- |-------|-------------|------|----------|-------|
344
- | LgsType | Logistics type | Varchar(15) | V | B2C or C2C |
345
- | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
346
- | MerchantOrderNo | Merchant order numbers | json_array | V | Max: 7-11(18), FamilyMart(8), Hi-Life(18), OK Mart(18) |
347
- | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
348
-
349
- **Response**: Returns HTML page with printable shipping label
350
-
351
- ---
352
-
353
- ### 5. Query Shipment API [NPA-B55]
354
-
355
- Query logistics order information and status.
356
-
357
- **Endpoint:**
358
- - Test: `https://ccore.newebpay.com/API/Logistic/queryShipment`
359
- - Production: `https://core.newebpay.com/API/Logistic/queryShipment`
360
-
361
- **EncryptData_ Parameters:**
362
-
363
- | Field | Description | Type | Required | Notes |
364
- |-------|-------------|------|----------|-------|
365
- | MerchantOrderNo | Merchant order number | Varchar(30) | V | Order ID |
366
- | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
367
-
368
- **Response EncryptData_ Parameters:**
369
-
370
- | Field | Description | Type | Notes |
371
- |-------|-------------|------|-------|
372
- | MerchantID | Merchant ID | Varchar(15) | NewebPay merchant ID |
373
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
374
- | TradeNo | NewebPay trade number | Varchar(20) | Platform transaction ID |
375
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
376
- | Amt | Transaction amount | Int(10) | Order amount |
377
- | ItemDesc | Product description | Varchar(100) | Product name |
378
- | NotifyURL | Notification URL | Varchar(50) | Callback URL |
379
- | LgsNo | Shipment number | Varchar(20) | Logistics tracking number |
380
- | StorePrintNo | Store print code | Varchar(20) | Kiosk print code |
381
- | collectionAmt | Collection amount | Int(10) | COD amount |
382
- | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
383
- | Type | Order type | Int(1) | 1=Normal, 3=Return |
384
- | ShopDate | Ship date | Date | Shipping date |
385
- | UserName | Recipient name | Varchar(20) | Pickup person |
386
- | UserTel | Recipient phone | Varchar(10) | Mobile number |
387
- | UserEmail | Recipient email | Varchar(50) | Email |
388
- | StoreID | Pickup store ID | Varchar(10) | Store code |
389
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
390
- | StoreName | Store name | Varchar(20) | Store name |
391
- | RetId | Status code | Varchar(10) | See status code table |
392
- | RetString | Status description | Varchar(30) | See status description |
393
-
394
- ---
395
-
396
- ### 6. Modify Shipment API [NPA-B56]
397
-
398
- Modify shipment order details (only for orders not yet shipped or expired).
399
-
400
- **Endpoint:**
401
- - Test: `https://ccore.newebpay.com/API/Logistic/modifyShipment`
402
- - Production: `https://core.newebpay.com/API/Logistic/modifyShipment`
403
-
404
- **Modifiable Conditions:**
405
- - Not yet obtained shipping number
406
- - Shipment expired
407
- - Store reselection
408
-
409
- **EncryptData_ Parameters:**
410
-
411
- | Field | Description | Type | Required | Notes |
412
- |-------|-------------|------|----------|-------|
413
- | MerchantOrderNo | Merchant order number | Varchar(30) | V | Order ID |
414
- | LgsType | Logistics type | Varchar(15) | V | B2C or C2C |
415
- | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
416
- | UserName | Recipient name | Varchar(20) | - | New recipient name |
417
- | UserTel | Recipient phone | Varchar(10) | - | New phone number |
418
- | UserEmail | Recipient email | Varchar(50) | - | New email |
419
- | StoreID | Pickup store ID | Varchar(10) | + | New store ID |
420
- | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
421
-
422
- **Response EncryptData_ Parameters:**
423
-
424
- | Field | Description | Type | Notes |
425
- |-------|-------------|------|-------|
426
- | MerchantID | Merchant ID | Varchar(15) | NewebPay merchant ID |
427
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
428
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
429
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
430
-
431
- ---
432
-
433
- ### 7. Track Shipment API [NPA-B57]
434
-
435
- Track complete logistics delivery history.
436
-
437
- **Endpoint:**
438
- - Test: `https://ccore.newebpay.com/API/Logistic/trace`
439
- - Production: `https://core.newebpay.com/API/Logistic/trace`
440
-
441
- **EncryptData_ Parameters:**
442
-
443
- | Field | Description | Type | Required | Notes |
444
- |-------|-------------|------|----------|-------|
445
- | MerchantOrderNo | Merchant order number | Varchar(30) | V | Order ID |
446
- | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
447
-
448
- **Response EncryptData_ Parameters:**
449
-
450
- | Field | Description | Type | Notes |
451
- |-------|-------------|------|-------|
452
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
453
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
454
- | LgsNo | Shipment number | Varchar(20) | Tracking number |
455
- | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
456
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
457
- | History | History array | json_array | Tracking history |
458
- | RetId | Status code | Varchar(10) | See status code table |
459
- | RetString | Status description | Varchar(30) | See status description |
460
- | EventTime | Event time | Varchar(20) | Timestamp |
461
-
462
- ---
463
-
464
- ### 8. Status Notification [NPA-B58]
465
-
466
- Real-time notification when shipment status changes.
467
-
468
- **Merchant provides NotifyURL to receive notifications**
469
-
470
- **POST Parameters:**
471
-
472
- | Field | Description | Type | Notes |
473
- |-------|-------------|------|-------|
474
- | Status | Response status | Varchar(10) | SUCCESS or error code |
475
- | Message | Response message | Varchar(30) | Status description |
476
- | EncryptData_ | Encrypted data | Text | - |
477
- | HashData_ | Hash data | Text | - |
478
- | UID_ | Merchant ID | Varchar(15) | NewebPay merchant ID |
479
- | Version_ | API version | Varchar(5) | Fixed: 1.0 |
480
-
481
- **EncryptData_ Parameters:**
482
-
483
- | Field | Description | Type | Notes |
484
- |-------|-------------|------|-------|
485
- | LgsType | Logistics type | Varchar(15) | B2C or C2C |
486
- | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
487
- | LgsNo | Shipment number | Varchar(20) | Tracking number |
488
- | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
489
- | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
490
- | RetId | Status code | Varchar(10) | See status code table |
491
- | RetString | Status description | Varchar(30) | See status description |
492
- | EventTime | Event time | Varchar(20) | Timestamp |
493
-
494
- ---
495
-
496
- ## Encryption Methods
497
-
498
- ### Hash Data Processing
499
-
500
- NewebPay Logistics uses the same encryption method as NewebPay Payment:
501
-
502
- 1. **AES-256-CBC Encryption**: Encrypt data using merchant's HashKey and HashIV
503
- 2. **SHA256 Hash**: Add HashKey + AES result + HashIV, then SHA256 hash and uppercase
504
-
505
- **Process:**
506
- ```
507
- EncryptData = AES-256-CBC(data, HashKey, HashIV)
508
- HashData = SHA256(HashKey + EncryptData + HashIV).toUpperCase()
509
- ```
510
-
511
- ---
512
-
513
- ## Status Codes
514
-
515
- ### RetId Status Codes & RetString Descriptions
516
-
517
- | RetId | RetString | Category |
518
- |-------|-----------|----------|
519
- | 0_1 | Order not processed | Pending |
520
- | 0_2 | Shipment number expired, please get new number | Pending |
521
- | 0_3 | Shipment canceled | Pending |
522
- | 1 | Order processing | Processing |
523
- | 2 | Store received shipment | In Transit |
524
- | 3 | Store reselected, waiting for re-shipment | In Transit |
525
- | 4 | Arrived at logistics center | In Transit |
526
- | 11 | Pickup store closed, please reselect | In Transit |
527
- | 5 | Arrived at pickup store | Ready for Pickup |
528
- | 6 | Customer picked up | Completed |
529
- | -1 | Returned to merchant | Completed |
530
- | -6 | Home delivery return requested | Completed |
531
- | -9 | Logistics inspection error | Completed |
532
- | -2 | Returned to sender/designated return store | Return/Compensation |
533
- | -3 | Returned to logistics center | Return/Compensation |
534
- | -4 | Returning to logistics center (customer did not pickup) | Return/Compensation |
535
- | -5 | Soon to be returned (customer did not pickup) | Return/Compensation |
536
- | -7 | Error compensation approved | Return/Compensation |
537
- | -10 | Product destroyed/discarded | Return/Compensation |
538
- | -11 | Product destroyed/discarded | Return/Compensation |
539
- | 10 | Soon to be returned | Return/Compensation |
540
- | 12 | Return store closed, please reselect | Return/Compensation |
541
- | 13 | Returning to logistics center (merchant did not pickup) | Return/Compensation |
542
- | 14 | Please request home delivery return | Return/Compensation |
543
- | 15 | Product destroyed/discarded | Return/Compensation |
544
- | 16 | Please confirm bank account | Return/Compensation |
545
-
546
- ---
547
-
548
- ## Error Codes
549
-
550
- ### Common Error Codes
551
-
552
- | Code | Message | Notes |
553
- |------|---------|-------|
554
- | SUCCESS | Success | - |
555
- | 1101 | Failed to create logistics order | - |
556
- | 1102 | Merchant not found | - |
557
- | 1103 | Duplicate merchant order number | - |
558
- | 1104 | Logistics service not enabled | - |
559
- | 1105 | Store information invalid or empty | - |
560
- | 1106 | IP not allowed | - |
561
- | 1107 | Payment order not found | - |
562
- | 1108 | System error, cannot query logistics order | - |
563
- | 1109 | Logistics order not found | - |
564
- | 1110 | System error, cannot modify logistics order | - |
565
- | 1111 | Order status cannot be modified | - |
566
- | 1112 | Failed to modify logistics order | - |
567
- | 1113 | System error, cannot query tracking history | - |
568
- | 1114 | Insufficient prepaid balance | - |
569
- | 1115 | Failed to get shipment number | - |
570
- | 1116 | Shipment already created for this transaction | - |
571
- | 2100 | Data format error | - |
572
- | 2101 | Version error | - |
573
- | 2102 | UID_ cannot be empty | - |
574
- | 2103 | COD amount limit: 20000 NTD | - |
575
- | 2104 | No payment amount limit: 20000 NTD | - |
576
- | 2105 | Max 10 shipment numbers per request | - |
577
- | 2106 | Max labels per request: 7-11(18), FamilyMart(8), Hi-Life(18), OK Mart(18) | - |
578
- | 4101 | IP restricted | - |
579
- | 4103 | HashData_ verification failed | - |
580
- | 4104 | Encryption error, check Hash_Key and Hash_IV | - |
581
-
582
- ---
583
-
584
- ## Important Notes
585
-
586
- ### Amount Limits
587
- - **COD (Cash on Delivery)**: Maximum 20,000 NTD
588
- - **No Payment**: Maximum 20,000 NTD
589
-
590
- ### Batch Limits
591
- - **Get Shipment Number**: Maximum 10 orders per request
592
- - **Print Label**:
593
- - 7-ELEVEN: Maximum 18 labels
594
- - FamilyMart: Maximum 8 labels
595
- - Hi-Life: Maximum 18 labels
596
- - OK Mart: Maximum 18 labels
597
-
598
- ### Store Code Notes
599
- - For FamilyMart and OK Mart, the store code displayed on the map may not be the real code
600
- - Always use the store code returned in the API response (StoreID field)
601
-
602
- ### Timestamp
603
- - Must use Unix timestamp (seconds since 1970-01-01 00:00:00 GMT)
604
- - Tolerance: 120 seconds
605
- - Incorrect timestamp will cause transaction failure
606
-
607
- ---
608
-
609
- ## PAYUNi API Operations
610
-
611
- ### 1. Create 7-11 C2C Shipment
612
-
613
- Create store-to-store logistics order.
614
-
615
- **Endpoint:** `POST /api/logistics/create`
616
-
617
- **Request Body:**
618
-
619
- | Field | Type | Required | Description |
620
- |-------|------|----------|-------------|
621
- | MerID | String | ● | Merchant ID |
622
- | Version | String | ● | API version (1.0) |
623
- | EncryptInfo | String | ● | AES-256-GCM encrypted data |
624
- | HashInfo | String | ● | SHA256 hash |
625
-
626
- **EncryptInfo Parameters:**
627
-
628
- | Field | Type | Required | Description |
629
- |-------|------|----------|-------------|
630
- | MerID | String(20) | ● | Merchant ID |
631
- | MerTradeNo | String(50) | ● | Unique order number |
632
- | LogisticsType | String(50) | ● | PAYUNi_Logistic_711 |
633
- | GoodsType | Integer | ● | 1=Normal, 2=Frozen |
634
- | GoodsAmount | Integer | ● | Product amount |
635
- | GoodsName | String(50) | ● | Product name |
636
- | SenderName | String(10) | ● | Sender name |
637
- | SenderPhone | String(20) | ● | Sender phone |
638
- | SenderStoreID | String(10) | ● | Sender store code (C2C only) |
639
- | ReceiverName | String(10) | ● | Receiver name |
640
- | ReceiverPhone | String(20) | ● | Receiver phone |
641
- | ReceiverStoreID | String(10) | ● | Receiver store code |
642
- | NotifyURL | String(500) | ● | Status notification URL |
643
- | Timestamp | Integer | ● | Unix timestamp |
644
-
645
- **Response (Decrypted EncryptInfo):**
646
-
647
- | Field | Description |
648
- |-------|-------------|
649
- | LogisticsID | PAYUNi logistics ID |
650
- | MerTradeNo | Merchant order number |
651
- | CVSPaymentNo | Store payment code |
652
- | CVSValidationNo | Store validation code |
653
- | ExpireDate | Pickup deadline |
654
-
655
- ---
656
-
657
- ### 2. Create T-Cat Home Delivery
658
-
659
- Create home delivery shipment.
660
-
661
- **Endpoint:** `POST /api/logistics/create`
662
-
663
- **Additional EncryptInfo Parameters:**
664
-
665
- | Field | Type | Required | Description |
666
- |-------|------|----------|-------------|
667
- | LogisticsType | String(50) | ● | PAYUNi_Logistic_Tcat |
668
- | GoodsType | Integer | ● | 1=Normal, 2=Frozen, 3=Refrigerated |
669
- | GoodsWeight | Integer | - | Weight in grams |
670
- | SenderZipCode | String(5) | ● | Sender postal code |
671
- | SenderAddress | String(200) | ● | Sender address |
672
- | ReceiverZipCode | String(5) | ● | Receiver postal code |
673
- | ReceiverAddress | String(200) | ● | Receiver address |
674
- | ScheduledPickupDate | String(10) | - | Pickup date (yyyy/MM/dd) |
675
- | ScheduledDeliveryDate | String(10) | - | Delivery date (yyyy/MM/dd) |
676
- | ScheduledDeliveryTime | String(2) | - | 01/02/03 (time slot) |
677
-
678
- **Delivery Time Slots:**
679
- - `01` - Before 13:00
680
- - `02` - 14:00 - 18:00
681
- - `03` - Not specified
682
-
683
- **Response (Decrypted EncryptInfo):**
684
-
685
- | Field | Description |
686
- |-------|-------------|
687
- | LogisticsID | PAYUNi logistics ID |
688
- | MerTradeNo | Merchant order number |
689
- | ShipmentNo | T-Cat tracking number |
690
- | BookingNote | Pickup number |
691
-
692
- ---
693
-
694
- ### 3. Query Shipment Status
695
-
696
- Query logistics order status.
697
-
698
- **Endpoint:** `POST /api/logistics/query`
699
-
700
- **EncryptInfo Parameters:**
701
-
702
- | Field | Type | Required | Description |
703
- |-------|------|----------|-------------|
704
- | MerID | String | ● | Merchant ID |
705
- | MerTradeNo | String | ● | Order number |
706
- | Timestamp | Integer | ● | Unix timestamp |
707
-
708
- **Response (Decrypted EncryptInfo):**
709
-
710
- | Field | Description |
711
- |-------|-------------|
712
- | LogisticsID | PAYUNi logistics ID |
713
- | MerTradeNo | Merchant order number |
714
- | LogisticsType | Logistics type |
715
- | LogisticsStatus | Status code (11/21/22/31/32) |
716
- | LogisticsStatusMsg | Status message |
717
- | ShipmentNo | Tracking number |
718
- | ReceiverStoreID | Receiver store code |
719
- | UpdateTime | Last update time |
720
-
721
- **Logistics Status Codes:**
722
-
723
- | Code | Description | Category |
724
- |------|-------------|----------|
725
- | 11 | Shipped | In Transit |
726
- | 21 | Arrived at store / In delivery | In Transit |
727
- | 22 | Picked up / Delivered | Completed |
728
- | 31 | Returning | Return |
729
- | 32 | Return completed | Return |
730
-
731
- ---
732
-
733
- ### 4. Status Notification Callback
734
-
735
- Handle real-time status updates from PAYUNi.
736
-
737
- **Callback Request (POST to NotifyURL):**
738
-
739
- | Field | Type | Description |
740
- |-------|------|-------------|
741
- | MerID | String | Merchant ID |
742
- | EncryptInfo | String | Encrypted status data |
743
- | HashInfo | String | SHA256 hash |
744
-
745
- **Decrypted EncryptInfo:**
746
-
747
- | Field | Description |
748
- |-------|-------------|
749
- | MerID | Merchant ID |
750
- | MerTradeNo | Merchant order number |
751
- | LogisticsID | PAYUNi logistics ID |
752
- | LogisticsType | Logistics type |
753
- | LogisticsStatus | Status code |
754
- | LogisticsStatusMsg | Status message |
755
- | UpdateTime | Update timestamp |
756
-
757
- **Response Required:**
758
- - Success: `SUCCESS`
759
- - Error: Any other response
760
-
761
- ---
762
-
763
- ## PAYUNi Encryption (AES-256-GCM)
764
-
765
- ### Encryption Process
766
-
767
- ```
768
- 1. Create Query String from parameters
769
- 2. AES-256-GCM encrypt (with 16-byte tag)
770
- 3. Convert to hex: EncryptInfo = hex(encrypted + tag)
771
- 4. Generate HashInfo: SHA256(EncryptInfo + HashKey + HashIV)
772
- ```
773
-
774
- ### Decryption Process
775
-
776
- ```
777
- 1. Convert hex to binary
778
- 2. Split: encrypted = data[:-16], tag = data[-16:]
779
- 3. AES-256-GCM decrypt and verify tag
780
- 4. Parse query string to get parameters
781
- ```
782
-
783
- ---
784
-
785
- ## Best Practices
786
-
787
- 1. **Store Selection**: Always use the StoreID from the Store Map API response, not the displayed code
788
- 2. **Error Handling**: Implement proper error handling for all API calls with retry logic
789
- 3. **Status Tracking**: Use Status Notification webhook for real-time updates instead of polling
790
- 4. **Encryption**: Securely store HashKey and HashIV, never expose in client-side code
791
- 5. **Order Numbers**: Ensure MerchantOrderNo is unique across all orders
792
- 6. **Timestamp**: Always generate fresh timestamp for each API call
793
- 7. **Testing**: Use test environment extensively before going to production
794
- 8. **Validation**: Validate all user input (name, phone, email) before API calls
795
- 9. **Logging**: Log all API requests and responses for debugging and auditing
796
- 10. **Notification URL**: Ensure NotifyURL is accessible from NewebPay servers (not localhost)
797
-
798
- ---
799
-
800
- ## Use Cases
801
-
802
- ### E-commerce Platform
803
- - Integrate store map for customers to select pickup location
804
- - Create shipment automatically after order confirmation
805
- - Send tracking updates to customers via email/SMS
806
- - Handle returns and exchanges through modify shipment API
807
-
808
- ### Marketplace
809
- - Support multiple vendors shipping to convenience stores
810
- - Provide unified logistics tracking interface
811
- - Automate shipment number retrieval and label printing
812
- - Handle COD payment collection and settlement
813
-
814
- ### Subscription Service
815
- - Schedule recurring shipments to same pickup store
816
- - Automatic label generation for regular deliveries
817
- - Batch shipment creation for multiple orders
818
- - Track delivery success rate and optimize logistics
819
-
820
- ---
821
-
822
- ## Related Resources
823
-
824
- - [EXAMPLES.md](./EXAMPLES.md) - Complete code examples (TypeScript, Python, PHP)
825
- - [references/NEWEBPAY_LOGISTICS_REFERENCE.md](./references/NEWEBPAY_LOGISTICS_REFERENCE.md) - NewebPay Logistics API full specification
826
- - [scripts/search.py](./scripts/search.py) - BM25 search engine for error codes and fields
827
- - [scripts/test_logistics.py](./scripts/test_logistics.py) - Connection testing tool
828
-
829
- ---
830
-
831
- ## Support
832
-
833
- ### NewebPay Technical Support
834
- - Phone: 02-2655-8938
835
- - Official Documentation: https://www.newebpay.com
836
-
837
- ### API Version
838
- Current Version: 1.0
839
-
840
- ### Last Updated
841
- 2026-01-29
842
-
843
- ---
844
-
845
- **Total Lines**: 750+
1
+ # Taiwan Logistics Development Skill
2
+
3
+ **Comprehensive guide for Taiwan Logistics integration (ECPay, NewebPay, PAYUNi, SmilePay, PChomePay, PayNow + HCT direct API)**
4
+
5
+ ---
6
+
7
+ ## Supported Providers
8
+
9
+ This skill covers **6 logistics aggregators** + **1 direct carrier API**:
10
+
11
+ | Provider | 類型 | Reference |
12
+ |---|---|---|
13
+ | **ECPay 綠界** | aggregator | `references/ecpay-logistics-api.md` |
14
+ | **NewebPay 藍新** | aggregator | `references/NEWEBPAY_LOGISTICS_REFERENCE.md` |
15
+ | **PAYUNi 統一** | aggregator | `references/payuni-logistics-api.md` |
16
+ | **SmilePay 速買配** | aggregator (含 7-11/全家 + 黑貓 Pay_zg 矩陣) | `references/smilepay-logistics-api.md` |
17
+ | **PChomePay 拍錢包** | aggregator (金物流二合一) | `references/pchomepay-logistics-api.md` |
18
+ | **PayNow 立吉富** | aggregator (11 條產品線, 3DES/ECB/Zero-Padding) | `references/paynow-logistics-api.md` |
19
+ | **HCT 新竹物流** | **直連 carrier API** | `references/hct-logistics-api.md` |
20
+
21
+ > 註:選用 `HCT 直連 API` 適合大量出貨企業;一般電商透過 aggregator (`LogisticsType=HCT`) 走 HCT 配送即可,不需自行串接。
22
+
23
+ ---
24
+
25
+ ## Quick Reference
26
+
27
+ ### Core Concepts
28
+
29
+ **Logistics Types:**
30
+ - **B2C (大宗寄倉)**: Bulk warehouse shipping - Merchant ships to logistics center, then distributed to stores
31
+ - **C2C (店到店)**: Store-to-store - Merchant ships to convenience store, then delivered to pickup store
32
+
33
+ **Trade Types:**
34
+ - **取貨付款 (Cash on Delivery)**: Customer pays when picking up
35
+ - **取貨不付款 (No Payment)**: Customer only picks up (payment already completed)
36
+
37
+ **Supported Convenience Stores:**
38
+ 1. 7-ELEVEN
39
+ 2. FamilyMart (全家)
40
+ 3. Hi-Life (萊爾富)
41
+ 4. OK Mart
42
+
43
+ **Key APIs:**
44
+ 1. Store Map Query - Select pickup/sender store
45
+ 2. Create Shipment - Create logistics order
46
+ 3. Get Shipment Number - Get shipping code
47
+ 4. Print Label - Print shipping label
48
+ 5. Query Shipment - Check order status
49
+ 6. Modify Shipment - Update order details
50
+ 7. Track Shipment - Track delivery history
51
+ 8. Status Notification - Real-time status updates
52
+
53
+ ---
54
+
55
+ ## Service Providers
56
+
57
+ ### NewebPay Logistics (藍新物流)
58
+
59
+ **Encryption**: AES-256-CBC + SHA256 (same as NewebPay payment)
60
+
61
+ **API Style**: Form POST with AES encryption
62
+
63
+ **Supported Services:**
64
+ - C2C Store-to-Store: 4 convenience stores (7-11, FamilyMart, Hi-Life, OK Mart)
65
+ - B2C Bulk Warehouse: 7-ELEVEN only
66
+
67
+ **Test Environment:**
68
+ - Store Map: `https://ccore.newebpay.com/API/Logistic/storeMap`
69
+ - Create Shipment: `https://ccore.newebpay.com/API/Logistic/createShipment`
70
+ - Get Shipment No: `https://ccore.newebpay.com/API/Logistic/getShipmentNo`
71
+ - Print Label: `https://ccore.newebpay.com/API/Logistic/printLabel`
72
+ - Query Shipment: `https://ccore.newebpay.com/API/Logistic/queryShipment`
73
+ - Modify Shipment: `https://ccore.newebpay.com/API/Logistic/modifyShipment`
74
+ - Track Shipment: `https://ccore.newebpay.com/API/Logistic/trace`
75
+
76
+ **Production Environment:**
77
+ - Replace `ccore.newebpay.com` with `core.newebpay.com`
78
+
79
+ ---
80
+
81
+ ### ECPay Logistics (綠界物流)
82
+
83
+ **Encryption**: MD5 CheckMacValue
84
+
85
+ **API Style**: Form POST with URL-encoded parameters
86
+
87
+ **Supported Services:**
88
+ - C2C Store-to-Store: 4 convenience stores (7-11, FamilyMart, Hi-Life, OK Mart)
89
+ - C2C Frozen: 7-ELEVEN frozen goods
90
+ - Home Delivery: T-Cat, HCT, Pelican Express
91
+
92
+ **Test Environment:**
93
+ - Base URL: `https://logistics-stage.ecpay.com.tw`
94
+ - Create: `POST /Express/Create`
95
+ - Query: `POST /Helper/QueryLogisticsTradeInfo/V2`
96
+ - Print: `POST /helper/printTradeDocument`
97
+ - Map: `POST /Express/map`
98
+
99
+ **Production Environment:**
100
+ - Base URL: `https://logistics.ecpay.com.tw`
101
+
102
+ **Logistics SubTypes (CVS):**
103
+ - `FAMI` - FamilyMart (全家)
104
+ - `UNIMART` - 7-ELEVEN (常溫)
105
+ - `UNIMARTFREEZE` - 7-ELEVEN (冷凍)
106
+ - `HILIFE` - Hi-Life (萊爾富)
107
+ - `OKMART` - OK Mart
108
+
109
+ **Logistics SubTypes (Home Delivery):**
110
+ - `TCAT` - T-Cat (黑貓宅急便)
111
+ - `ECAN` - HCT (新竹物流)
112
+ - `POST` - Pelican Express (宅配通)
113
+
114
+ **Temperature Control (Home Delivery):**
115
+ - `0001` - Normal temperature (常溫)
116
+ - `0002` - Refrigerated (冷藏)
117
+ - `0003` - Frozen (冷凍)
118
+
119
+ **Specification (Package Size):**
120
+ - `0001` - 60cm
121
+ - `0002` - 90cm
122
+ - `0003` - 120cm
123
+ - `0004` - 150cm
124
+
125
+ **Distance (Delivery Range):**
126
+ - `00` - Same district
127
+ - `01` - Same city
128
+ - `02` - Cross city
129
+ - `03` - Outlying islands
130
+
131
+ **Test Credentials:**
132
+ - MerchantID: `2000132`
133
+ - HashKey: `5294y06JbISpM5x9`
134
+ - HashIV: `v77hoKGq4kWxNNIS`
135
+
136
+ ---
137
+
138
+ ### PAYUNi Logistics (統一物流)
139
+
140
+ **Encryption**: AES-256-GCM + SHA256 (same as PAYUNi payment)
141
+
142
+ **API Style**: RESTful JSON with AES-GCM encryption
143
+
144
+ **Supported Services:**
145
+ - C2C Store-to-Store: 7-ELEVEN (normal temperature + frozen)
146
+ - B2C Bulk Warehouse: 7-ELEVEN only
147
+ - Home Delivery: T-Cat (normal temperature, frozen, refrigerated)
148
+
149
+ **Test Environment:**
150
+ - Base URL: `https://sandbox-api.payuni.com.tw/api/`
151
+ - Create Shipment: `POST /logistics/create`
152
+ - Query Shipment: `POST /logistics/query`
153
+ - Cancel Shipment: `POST /logistics/cancel`
154
+
155
+ **Production Environment:**
156
+ - Base URL: `https://api.payuni.com.tw/api/`
157
+
158
+ **Logistics Types:**
159
+ - `PAYUNi_Logistic_711` - 7-11 C2C (normal temperature)
160
+ - `PAYUNi_Logistic_711_Freeze` - 7-11 C2C (frozen)
161
+ - `PAYUNi_Logistic_711_B2C` - 7-11 B2C (bulk warehouse)
162
+ - `PAYUNi_Logistic_Tcat` - T-Cat home delivery (normal)
163
+ - `PAYUNi_Logistic_Tcat_Freeze` - T-Cat frozen
164
+ - `PAYUNi_Logistic_Tcat_Cold` - T-Cat refrigerated
165
+
166
+ **Temperature Codes:**
167
+ - `1` - Normal temperature
168
+ - `2` - Frozen
169
+ - `3` - Refrigerated (T-Cat only)
170
+
171
+ **Size & Weight Limits:**
172
+ - Normal temperature: 150cm material volume, 20kg
173
+ - Frozen/Refrigerated: 120cm material volume, 15kg
174
+ - Material volume calculation: Length + Width + Height ≤ Limit
175
+
176
+ ---
177
+
178
+ ## Transaction Flows
179
+
180
+ ### 1. B2C Bulk Warehouse - Cash on Delivery
181
+
182
+ 1. **Create Order**: Customer selects store, merchant calls Create Shipment API
183
+ 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
184
+ 3. **Merchant Ships**: Merchant delivers goods to logistics center
185
+ 4. **Logistics Distributes**: Logistics center verifies and distributes to pickup store
186
+ 5. **Customer Picks Up**: Customer picks up and pays, NewebPay notifies merchant
187
+
188
+ ### 2. C2C Store-to-Store - Cash on Delivery
189
+
190
+ 1. **Create Order**: Customer selects store, merchant calls Create Shipment API
191
+ 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
192
+ 3. **Merchant Ships**: Merchant delivers goods to sender store
193
+ 4. **Store Ships**: Sender store ships to logistics center, then to pickup store
194
+ 5. **Customer Picks Up**: Customer picks up and pays, NewebPay notifies merchant
195
+
196
+ ### 3. B2C Bulk Warehouse - No Payment
197
+
198
+ 1. **Create Order**: Customer selects store (payment already completed)
199
+ 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
200
+ 3. **Merchant Ships**: Merchant delivers goods to logistics center
201
+ 4. **Logistics Distributes**: Logistics center verifies and distributes to pickup store
202
+ 5. **Customer Picks Up**: Customer picks up, NewebPay notifies merchant
203
+
204
+ ### 4. C2C Store-to-Store - No Payment
205
+
206
+ 1. **Create Order**: Customer selects store (payment already completed)
207
+ 2. **Get Shipping Code**: Merchant calls Get Shipment Number API & Print Label API
208
+ 3. **Merchant Ships**: Merchant delivers goods to sender store
209
+ 4. **Store Ships**: Sender store ships to logistics center, then to pickup store
210
+ 5. **Customer Picks Up**: Customer picks up, NewebPay notifies merchant
211
+
212
+ ---
213
+
214
+ ## API Operations
215
+
216
+ ### 1. Store Map Query API [NPA-B51]
217
+
218
+ Query convenience store locations for pickup or sender.
219
+
220
+ **Endpoint:**
221
+ - Test: `https://ccore.newebpay.com/API/Logistic/storeMap`
222
+ - Production: `https://core.newebpay.com/API/Logistic/storeMap`
223
+
224
+ **Request Parameters:**
225
+
226
+ | Field | Description | Type | Required |
227
+ |-------|-------------|------|----------|
228
+ | UID_ | Merchant ID | Varchar(15) | V |
229
+ | EncryptData_ | Encrypted data | Text | V |
230
+ | HashData_ | Hash data | Text | V |
231
+ | Version_ | API version | Varchar(5) | V |
232
+ | RespondType_ | Response format | Varchar(6) | V |
233
+
234
+ **EncryptData_ Parameters:**
235
+
236
+ | Field | Description | Type | Required | Notes |
237
+ |-------|-------------|------|----------|-------|
238
+ | MerchantOrderNo | Merchant order number | Varchar(30) | V | Unique order ID |
239
+ | LgsType | Logistics type | Varchar(15) | V | B2C or C2C |
240
+ | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
241
+ | ReturnURL | Return URL | Varchar(50) | V | URL after store selection |
242
+ | TimeStamp | Unix timestamp | Text | V | Current time in seconds |
243
+ | ExtraData | Extra data | Varchar(20) | - | Returned as-is |
244
+
245
+ **Response EncryptData_ Parameters:**
246
+
247
+ | Field | Description | Type | Notes |
248
+ |-------|-------------|------|-------|
249
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
250
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
251
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
252
+ | StoreName | Store name | Varchar(10) | Selected store name |
253
+ | StoreTel | Store phone | Varchar(12) | Store phone number |
254
+ | StoreAddr | Store address | Varchar(100) | Store address |
255
+ | StoreID | Store code | Varchar(8) | Store ID (use this for shipment) |
256
+ | ExtraData | Extra data | Varchar(20) | Original value returned |
257
+
258
+ ---
259
+
260
+ ### 2. Create Shipment API [NPA-B52]
261
+
262
+ Create logistics shipment order after payment order is established.
263
+
264
+ **Endpoint:**
265
+ - Test: `https://ccore.newebpay.com/API/Logistic/createShipment`
266
+ - Production: `https://core.newebpay.com/API/Logistic/createShipment`
267
+
268
+ **EncryptData_ Parameters:**
269
+
270
+ | Field | Description | Type | Required | Notes |
271
+ |-------|-------------|------|----------|-------|
272
+ | MerchantOrderNo | Merchant order number | Varchar(30) | V | Unique order ID |
273
+ | TradeType | Trade type | Int(1) | V | 1=COD, 3=No Payment |
274
+ | UserName | Recipient name | Varchar(20) | V | Pickup person name |
275
+ | UserTel | Recipient phone | Varchar(10) | V | Mobile number |
276
+ | UserEmail | Recipient email | Varchar(50) | V | Email address |
277
+ | StoreID | Pickup store ID | Varchar(10) | V | From store map query |
278
+ | Amt | Transaction amount | Int(10) | V | Order amount |
279
+ | NotifyURL | Notification URL | Varchar(100) | - | Pickup completion callback |
280
+ | ItemDesc | Product description | Varchar(100) | - | Product name |
281
+ | LgsType | Logistics type | Varchar(3) | V | B2C or C2C |
282
+ | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
283
+ | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
284
+
285
+ **Response EncryptData_ Parameters:**
286
+
287
+ | Field | Description | Type | Notes |
288
+ |-------|-------------|------|-------|
289
+ | MerchantID | Merchant ID | Varchar(15) | NewebPay merchant ID |
290
+ | Amt | Transaction amount | Int(10) | Order amount |
291
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
292
+ | TradeNo | NewebPay trade number | Varchar(20) | Platform transaction ID |
293
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
294
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
295
+ | StoreID | Pickup store ID | Varchar(10) | Store code |
296
+ | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
297
+
298
+ ---
299
+
300
+ ### 3. Get Shipment Number API [NPA-B53]
301
+
302
+ Get shipping code before shipment. Merchants can print labels at convenience store Kiosk.
303
+
304
+ **Endpoint:**
305
+ - Test: `https://ccore.newebpay.com/API/Logistic/getShipmentNo`
306
+ - Production: `https://core.newebpay.com/API/Logistic/getShipmentNo`
307
+
308
+ **EncryptData_ Parameters:**
309
+
310
+ | Field | Description | Type | Required | Notes |
311
+ |-------|-------------|------|----------|-------|
312
+ | MerchantOrderNo | Merchant order numbers | Json_array | V | Max 10 orders at once |
313
+ | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
314
+
315
+ **Response EncryptData_ Parameters:**
316
+
317
+ | Field | Description | Type | Notes |
318
+ |-------|-------------|------|-------|
319
+ | SUCCESS | Success array | Json_array | Multiple records |
320
+ | ERROR | Error array | Json_array | Multiple records |
321
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
322
+ | ErrorCode | Error code | Varchar(20) | SUCCESS or error code |
323
+ | LgsNo | Shipment number | Varchar(20) | Logistics tracking number |
324
+ | StorePrintNo | Store print code | Varchar(20) | Code for Kiosk printing |
325
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
326
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
327
+
328
+ ---
329
+
330
+ ### 4. Print Label API [NPA-B54]
331
+
332
+ Print shipping labels to attach to products.
333
+
334
+ **Endpoint:**
335
+ - Test: `https://ccore.newebpay.com/API/Logistic/printLabel`
336
+ - Production: `https://core.newebpay.com/API/Logistic/printLabel`
337
+
338
+ **Important**: Must use Form POST method (not JSON API call)
339
+
340
+ **EncryptData_ Parameters:**
341
+
342
+ | Field | Description | Type | Required | Notes |
343
+ |-------|-------------|------|----------|-------|
344
+ | LgsType | Logistics type | Varchar(15) | V | B2C or C2C |
345
+ | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
346
+ | MerchantOrderNo | Merchant order numbers | json_array | V | Max: 7-11(18), FamilyMart(8), Hi-Life(18), OK Mart(18) |
347
+ | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
348
+
349
+ **Response**: Returns HTML page with printable shipping label
350
+
351
+ ---
352
+
353
+ ### 5. Query Shipment API [NPA-B55]
354
+
355
+ Query logistics order information and status.
356
+
357
+ **Endpoint:**
358
+ - Test: `https://ccore.newebpay.com/API/Logistic/queryShipment`
359
+ - Production: `https://core.newebpay.com/API/Logistic/queryShipment`
360
+
361
+ **EncryptData_ Parameters:**
362
+
363
+ | Field | Description | Type | Required | Notes |
364
+ |-------|-------------|------|----------|-------|
365
+ | MerchantOrderNo | Merchant order number | Varchar(30) | V | Order ID |
366
+ | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
367
+
368
+ **Response EncryptData_ Parameters:**
369
+
370
+ | Field | Description | Type | Notes |
371
+ |-------|-------------|------|-------|
372
+ | MerchantID | Merchant ID | Varchar(15) | NewebPay merchant ID |
373
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
374
+ | TradeNo | NewebPay trade number | Varchar(20) | Platform transaction ID |
375
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
376
+ | Amt | Transaction amount | Int(10) | Order amount |
377
+ | ItemDesc | Product description | Varchar(100) | Product name |
378
+ | NotifyURL | Notification URL | Varchar(50) | Callback URL |
379
+ | LgsNo | Shipment number | Varchar(20) | Logistics tracking number |
380
+ | StorePrintNo | Store print code | Varchar(20) | Kiosk print code |
381
+ | collectionAmt | Collection amount | Int(10) | COD amount |
382
+ | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
383
+ | Type | Order type | Int(1) | 1=Normal, 3=Return |
384
+ | ShopDate | Ship date | Date | Shipping date |
385
+ | UserName | Recipient name | Varchar(20) | Pickup person |
386
+ | UserTel | Recipient phone | Varchar(10) | Mobile number |
387
+ | UserEmail | Recipient email | Varchar(50) | Email |
388
+ | StoreID | Pickup store ID | Varchar(10) | Store code |
389
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
390
+ | StoreName | Store name | Varchar(20) | Store name |
391
+ | RetId | Status code | Varchar(10) | See status code table |
392
+ | RetString | Status description | Varchar(30) | See status description |
393
+
394
+ ---
395
+
396
+ ### 6. Modify Shipment API [NPA-B56]
397
+
398
+ Modify shipment order details (only for orders not yet shipped or expired).
399
+
400
+ **Endpoint:**
401
+ - Test: `https://ccore.newebpay.com/API/Logistic/modifyShipment`
402
+ - Production: `https://core.newebpay.com/API/Logistic/modifyShipment`
403
+
404
+ **Modifiable Conditions:**
405
+ - Not yet obtained shipping number
406
+ - Shipment expired
407
+ - Store reselection
408
+
409
+ **EncryptData_ Parameters:**
410
+
411
+ | Field | Description | Type | Required | Notes |
412
+ |-------|-------------|------|----------|-------|
413
+ | MerchantOrderNo | Merchant order number | Varchar(30) | V | Order ID |
414
+ | LgsType | Logistics type | Varchar(15) | V | B2C or C2C |
415
+ | ShipType | Logistics provider | Varchar(15) | V | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
416
+ | UserName | Recipient name | Varchar(20) | - | New recipient name |
417
+ | UserTel | Recipient phone | Varchar(10) | - | New phone number |
418
+ | UserEmail | Recipient email | Varchar(50) | - | New email |
419
+ | StoreID | Pickup store ID | Varchar(10) | + | New store ID |
420
+ | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
421
+
422
+ **Response EncryptData_ Parameters:**
423
+
424
+ | Field | Description | Type | Notes |
425
+ |-------|-------------|------|-------|
426
+ | MerchantID | Merchant ID | Varchar(15) | NewebPay merchant ID |
427
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
428
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
429
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
430
+
431
+ ---
432
+
433
+ ### 7. Track Shipment API [NPA-B57]
434
+
435
+ Track complete logistics delivery history.
436
+
437
+ **Endpoint:**
438
+ - Test: `https://ccore.newebpay.com/API/Logistic/trace`
439
+ - Production: `https://core.newebpay.com/API/Logistic/trace`
440
+
441
+ **EncryptData_ Parameters:**
442
+
443
+ | Field | Description | Type | Required | Notes |
444
+ |-------|-------------|------|----------|-------|
445
+ | MerchantOrderNo | Merchant order number | Varchar(30) | V | Order ID |
446
+ | TimeStamp | Unix timestamp | Varchar(50) | V | Current time in seconds |
447
+
448
+ **Response EncryptData_ Parameters:**
449
+
450
+ | Field | Description | Type | Notes |
451
+ |-------|-------------|------|-------|
452
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
453
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
454
+ | LgsNo | Shipment number | Varchar(20) | Tracking number |
455
+ | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
456
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
457
+ | History | History array | json_array | Tracking history |
458
+ | RetId | Status code | Varchar(10) | See status code table |
459
+ | RetString | Status description | Varchar(30) | See status description |
460
+ | EventTime | Event time | Varchar(20) | Timestamp |
461
+
462
+ ---
463
+
464
+ ### 8. Status Notification [NPA-B58]
465
+
466
+ Real-time notification when shipment status changes.
467
+
468
+ **Merchant provides NotifyURL to receive notifications**
469
+
470
+ **POST Parameters:**
471
+
472
+ | Field | Description | Type | Notes |
473
+ |-------|-------------|------|-------|
474
+ | Status | Response status | Varchar(10) | SUCCESS or error code |
475
+ | Message | Response message | Varchar(30) | Status description |
476
+ | EncryptData_ | Encrypted data | Text | - |
477
+ | HashData_ | Hash data | Text | - |
478
+ | UID_ | Merchant ID | Varchar(15) | NewebPay merchant ID |
479
+ | Version_ | API version | Varchar(5) | Fixed: 1.0 |
480
+
481
+ **EncryptData_ Parameters:**
482
+
483
+ | Field | Description | Type | Notes |
484
+ |-------|-------------|------|-------|
485
+ | LgsType | Logistics type | Varchar(15) | B2C or C2C |
486
+ | MerchantOrderNo | Merchant order number | Varchar(30) | Order ID |
487
+ | LgsNo | Shipment number | Varchar(20) | Tracking number |
488
+ | TradeType | Trade type | Int(1) | 1=COD, 3=No Payment |
489
+ | ShipType | Logistics provider | Varchar(15) | 1=7-11, 2=FamilyMart, 3=Hi-Life, 4=OK Mart |
490
+ | RetId | Status code | Varchar(10) | See status code table |
491
+ | RetString | Status description | Varchar(30) | See status description |
492
+ | EventTime | Event time | Varchar(20) | Timestamp |
493
+
494
+ ---
495
+
496
+ ## Encryption Methods
497
+
498
+ ### Hash Data Processing
499
+
500
+ NewebPay Logistics uses the same encryption method as NewebPay Payment:
501
+
502
+ 1. **AES-256-CBC Encryption**: Encrypt data using merchant's HashKey and HashIV
503
+ 2. **SHA256 Hash**: Add HashKey + AES result + HashIV, then SHA256 hash and uppercase
504
+
505
+ **Process:**
506
+ ```
507
+ EncryptData = AES-256-CBC(data, HashKey, HashIV)
508
+ HashData = SHA256(HashKey + EncryptData + HashIV).toUpperCase()
509
+ ```
510
+
511
+ ---
512
+
513
+ ## Status Codes
514
+
515
+ ### RetId Status Codes & RetString Descriptions
516
+
517
+ | RetId | RetString | Category |
518
+ |-------|-----------|----------|
519
+ | 0_1 | Order not processed | Pending |
520
+ | 0_2 | Shipment number expired, please get new number | Pending |
521
+ | 0_3 | Shipment canceled | Pending |
522
+ | 1 | Order processing | Processing |
523
+ | 2 | Store received shipment | In Transit |
524
+ | 3 | Store reselected, waiting for re-shipment | In Transit |
525
+ | 4 | Arrived at logistics center | In Transit |
526
+ | 11 | Pickup store closed, please reselect | In Transit |
527
+ | 5 | Arrived at pickup store | Ready for Pickup |
528
+ | 6 | Customer picked up | Completed |
529
+ | -1 | Returned to merchant | Completed |
530
+ | -6 | Home delivery return requested | Completed |
531
+ | -9 | Logistics inspection error | Completed |
532
+ | -2 | Returned to sender/designated return store | Return/Compensation |
533
+ | -3 | Returned to logistics center | Return/Compensation |
534
+ | -4 | Returning to logistics center (customer did not pickup) | Return/Compensation |
535
+ | -5 | Soon to be returned (customer did not pickup) | Return/Compensation |
536
+ | -7 | Error compensation approved | Return/Compensation |
537
+ | -10 | Product destroyed/discarded | Return/Compensation |
538
+ | -11 | Product destroyed/discarded | Return/Compensation |
539
+ | 10 | Soon to be returned | Return/Compensation |
540
+ | 12 | Return store closed, please reselect | Return/Compensation |
541
+ | 13 | Returning to logistics center (merchant did not pickup) | Return/Compensation |
542
+ | 14 | Please request home delivery return | Return/Compensation |
543
+ | 15 | Product destroyed/discarded | Return/Compensation |
544
+ | 16 | Please confirm bank account | Return/Compensation |
545
+
546
+ ---
547
+
548
+ ## Error Codes
549
+
550
+ ### Common Error Codes
551
+
552
+ | Code | Message | Notes |
553
+ |------|---------|-------|
554
+ | SUCCESS | Success | - |
555
+ | 1101 | Failed to create logistics order | - |
556
+ | 1102 | Merchant not found | - |
557
+ | 1103 | Duplicate merchant order number | - |
558
+ | 1104 | Logistics service not enabled | - |
559
+ | 1105 | Store information invalid or empty | - |
560
+ | 1106 | IP not allowed | - |
561
+ | 1107 | Payment order not found | - |
562
+ | 1108 | System error, cannot query logistics order | - |
563
+ | 1109 | Logistics order not found | - |
564
+ | 1110 | System error, cannot modify logistics order | - |
565
+ | 1111 | Order status cannot be modified | - |
566
+ | 1112 | Failed to modify logistics order | - |
567
+ | 1113 | System error, cannot query tracking history | - |
568
+ | 1114 | Insufficient prepaid balance | - |
569
+ | 1115 | Failed to get shipment number | - |
570
+ | 1116 | Shipment already created for this transaction | - |
571
+ | 2100 | Data format error | - |
572
+ | 2101 | Version error | - |
573
+ | 2102 | UID_ cannot be empty | - |
574
+ | 2103 | COD amount limit: 20000 NTD | - |
575
+ | 2104 | No payment amount limit: 20000 NTD | - |
576
+ | 2105 | Max 10 shipment numbers per request | - |
577
+ | 2106 | Max labels per request: 7-11(18), FamilyMart(8), Hi-Life(18), OK Mart(18) | - |
578
+ | 4101 | IP restricted | - |
579
+ | 4103 | HashData_ verification failed | - |
580
+ | 4104 | Encryption error, check Hash_Key and Hash_IV | - |
581
+
582
+ ---
583
+
584
+ ## Important Notes
585
+
586
+ ### Amount Limits
587
+ - **COD (Cash on Delivery)**: Maximum 20,000 NTD
588
+ - **No Payment**: Maximum 20,000 NTD
589
+
590
+ ### Batch Limits
591
+ - **Get Shipment Number**: Maximum 10 orders per request
592
+ - **Print Label**:
593
+ - 7-ELEVEN: Maximum 18 labels
594
+ - FamilyMart: Maximum 8 labels
595
+ - Hi-Life: Maximum 18 labels
596
+ - OK Mart: Maximum 18 labels
597
+
598
+ ### Store Code Notes
599
+ - For FamilyMart and OK Mart, the store code displayed on the map may not be the real code
600
+ - Always use the store code returned in the API response (StoreID field)
601
+
602
+ ### Timestamp
603
+ - Must use Unix timestamp (seconds since 1970-01-01 00:00:00 GMT)
604
+ - Tolerance: 120 seconds
605
+ - Incorrect timestamp will cause transaction failure
606
+
607
+ ---
608
+
609
+ ## PAYUNi API Operations
610
+
611
+ ### 1. Create 7-11 C2C Shipment
612
+
613
+ Create store-to-store logistics order.
614
+
615
+ **Endpoint:** `POST /api/logistics/create`
616
+
617
+ **Request Body:**
618
+
619
+ | Field | Type | Required | Description |
620
+ |-------|------|----------|-------------|
621
+ | MerID | String | ● | Merchant ID |
622
+ | Version | String | ● | API version (1.0) |
623
+ | EncryptInfo | String | ● | AES-256-GCM encrypted data |
624
+ | HashInfo | String | ● | SHA256 hash |
625
+
626
+ **EncryptInfo Parameters:**
627
+
628
+ | Field | Type | Required | Description |
629
+ |-------|------|----------|-------------|
630
+ | MerID | String(20) | ● | Merchant ID |
631
+ | MerTradeNo | String(50) | ● | Unique order number |
632
+ | LogisticsType | String(50) | ● | PAYUNi_Logistic_711 |
633
+ | GoodsType | Integer | ● | 1=Normal, 2=Frozen |
634
+ | GoodsAmount | Integer | ● | Product amount |
635
+ | GoodsName | String(50) | ● | Product name |
636
+ | SenderName | String(10) | ● | Sender name |
637
+ | SenderPhone | String(20) | ● | Sender phone |
638
+ | SenderStoreID | String(10) | ● | Sender store code (C2C only) |
639
+ | ReceiverName | String(10) | ● | Receiver name |
640
+ | ReceiverPhone | String(20) | ● | Receiver phone |
641
+ | ReceiverStoreID | String(10) | ● | Receiver store code |
642
+ | NotifyURL | String(500) | ● | Status notification URL |
643
+ | Timestamp | Integer | ● | Unix timestamp |
644
+
645
+ **Response (Decrypted EncryptInfo):**
646
+
647
+ | Field | Description |
648
+ |-------|-------------|
649
+ | LogisticsID | PAYUNi logistics ID |
650
+ | MerTradeNo | Merchant order number |
651
+ | CVSPaymentNo | Store payment code |
652
+ | CVSValidationNo | Store validation code |
653
+ | ExpireDate | Pickup deadline |
654
+
655
+ ---
656
+
657
+ ### 2. Create T-Cat Home Delivery
658
+
659
+ Create home delivery shipment.
660
+
661
+ **Endpoint:** `POST /api/logistics/create`
662
+
663
+ **Additional EncryptInfo Parameters:**
664
+
665
+ | Field | Type | Required | Description |
666
+ |-------|------|----------|-------------|
667
+ | LogisticsType | String(50) | ● | PAYUNi_Logistic_Tcat |
668
+ | GoodsType | Integer | ● | 1=Normal, 2=Frozen, 3=Refrigerated |
669
+ | GoodsWeight | Integer | - | Weight in grams |
670
+ | SenderZipCode | String(5) | ● | Sender postal code |
671
+ | SenderAddress | String(200) | ● | Sender address |
672
+ | ReceiverZipCode | String(5) | ● | Receiver postal code |
673
+ | ReceiverAddress | String(200) | ● | Receiver address |
674
+ | ScheduledPickupDate | String(10) | - | Pickup date (yyyy/MM/dd) |
675
+ | ScheduledDeliveryDate | String(10) | - | Delivery date (yyyy/MM/dd) |
676
+ | ScheduledDeliveryTime | String(2) | - | 01/02/03 (time slot) |
677
+
678
+ **Delivery Time Slots:**
679
+ - `01` - Before 13:00
680
+ - `02` - 14:00 - 18:00
681
+ - `03` - Not specified
682
+
683
+ **Response (Decrypted EncryptInfo):**
684
+
685
+ | Field | Description |
686
+ |-------|-------------|
687
+ | LogisticsID | PAYUNi logistics ID |
688
+ | MerTradeNo | Merchant order number |
689
+ | ShipmentNo | T-Cat tracking number |
690
+ | BookingNote | Pickup number |
691
+
692
+ ---
693
+
694
+ ### 3. Query Shipment Status
695
+
696
+ Query logistics order status.
697
+
698
+ **Endpoint:** `POST /api/logistics/query`
699
+
700
+ **EncryptInfo Parameters:**
701
+
702
+ | Field | Type | Required | Description |
703
+ |-------|------|----------|-------------|
704
+ | MerID | String | ● | Merchant ID |
705
+ | MerTradeNo | String | ● | Order number |
706
+ | Timestamp | Integer | ● | Unix timestamp |
707
+
708
+ **Response (Decrypted EncryptInfo):**
709
+
710
+ | Field | Description |
711
+ |-------|-------------|
712
+ | LogisticsID | PAYUNi logistics ID |
713
+ | MerTradeNo | Merchant order number |
714
+ | LogisticsType | Logistics type |
715
+ | LogisticsStatus | Status code (11/21/22/31/32) |
716
+ | LogisticsStatusMsg | Status message |
717
+ | ShipmentNo | Tracking number |
718
+ | ReceiverStoreID | Receiver store code |
719
+ | UpdateTime | Last update time |
720
+
721
+ **Logistics Status Codes:**
722
+
723
+ | Code | Description | Category |
724
+ |------|-------------|----------|
725
+ | 11 | Shipped | In Transit |
726
+ | 21 | Arrived at store / In delivery | In Transit |
727
+ | 22 | Picked up / Delivered | Completed |
728
+ | 31 | Returning | Return |
729
+ | 32 | Return completed | Return |
730
+
731
+ ---
732
+
733
+ ### 4. Status Notification Callback
734
+
735
+ Handle real-time status updates from PAYUNi.
736
+
737
+ **Callback Request (POST to NotifyURL):**
738
+
739
+ | Field | Type | Description |
740
+ |-------|------|-------------|
741
+ | MerID | String | Merchant ID |
742
+ | EncryptInfo | String | Encrypted status data |
743
+ | HashInfo | String | SHA256 hash |
744
+
745
+ **Decrypted EncryptInfo:**
746
+
747
+ | Field | Description |
748
+ |-------|-------------|
749
+ | MerID | Merchant ID |
750
+ | MerTradeNo | Merchant order number |
751
+ | LogisticsID | PAYUNi logistics ID |
752
+ | LogisticsType | Logistics type |
753
+ | LogisticsStatus | Status code |
754
+ | LogisticsStatusMsg | Status message |
755
+ | UpdateTime | Update timestamp |
756
+
757
+ **Response Required:**
758
+ - Success: `SUCCESS`
759
+ - Error: Any other response
760
+
761
+ ---
762
+
763
+ ## PAYUNi Encryption (AES-256-GCM)
764
+
765
+ ### Encryption Process
766
+
767
+ ```
768
+ 1. Create Query String from parameters
769
+ 2. AES-256-GCM encrypt (with 16-byte tag)
770
+ 3. Convert to hex: EncryptInfo = hex(encrypted + tag)
771
+ 4. Generate HashInfo: SHA256(EncryptInfo + HashKey + HashIV)
772
+ ```
773
+
774
+ ### Decryption Process
775
+
776
+ ```
777
+ 1. Convert hex to binary
778
+ 2. Split: encrypted = data[:-16], tag = data[-16:]
779
+ 3. AES-256-GCM decrypt and verify tag
780
+ 4. Parse query string to get parameters
781
+ ```
782
+
783
+ ---
784
+
785
+ ## Best Practices
786
+
787
+ 1. **Store Selection**: Always use the StoreID from the Store Map API response, not the displayed code
788
+ 2. **Error Handling**: Implement proper error handling for all API calls with retry logic
789
+ 3. **Status Tracking**: Use Status Notification webhook for real-time updates instead of polling
790
+ 4. **Encryption**: Securely store HashKey and HashIV, never expose in client-side code
791
+ 5. **Order Numbers**: Ensure MerchantOrderNo is unique across all orders
792
+ 6. **Timestamp**: Always generate fresh timestamp for each API call
793
+ 7. **Testing**: Use test environment extensively before going to production
794
+ 8. **Validation**: Validate all user input (name, phone, email) before API calls
795
+ 9. **Logging**: Log all API requests and responses for debugging and auditing
796
+ 10. **Notification URL**: Ensure NotifyURL is accessible from NewebPay servers (not localhost)
797
+
798
+ ---
799
+
800
+ ## Use Cases
801
+
802
+ ### E-commerce Platform
803
+ - Integrate store map for customers to select pickup location
804
+ - Create shipment automatically after order confirmation
805
+ - Send tracking updates to customers via email/SMS
806
+ - Handle returns and exchanges through modify shipment API
807
+
808
+ ### Marketplace
809
+ - Support multiple vendors shipping to convenience stores
810
+ - Provide unified logistics tracking interface
811
+ - Automate shipment number retrieval and label printing
812
+ - Handle COD payment collection and settlement
813
+
814
+ ### Subscription Service
815
+ - Schedule recurring shipments to same pickup store
816
+ - Automatic label generation for regular deliveries
817
+ - Batch shipment creation for multiple orders
818
+ - Track delivery success rate and optimize logistics
819
+
820
+ ---
821
+
822
+ ## Related Resources
823
+
824
+ - [EXAMPLES.md](./EXAMPLES.md) - Complete code examples (TypeScript, Python, PHP)
825
+ - [references/NEWEBPAY_LOGISTICS_REFERENCE.md](./references/NEWEBPAY_LOGISTICS_REFERENCE.md) - NewebPay Logistics API full specification
826
+ - [scripts/search.py](./scripts/search.py) - BM25 search engine for error codes and fields
827
+ - [scripts/test_logistics.py](./scripts/test_logistics.py) - Connection testing tool
828
+
829
+ ---
830
+
831
+ ## Support
832
+
833
+ ### NewebPay Technical Support
834
+ - Phone: 02-2655-8938
835
+ - Official Documentation: https://www.newebpay.com
836
+
837
+ ### API Version
838
+ Current Version: 1.0
839
+
840
+ ### Last Updated
841
+ 2026-01-29
842
+
843
+ ---
844
+
845
+ **Total Lines**: 750+