taiwan-logistics-skill 1.2.0 → 1.2.1

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,1102 +1,1102 @@
1
- # HCT Logistics API Reference
2
-
3
- 新竹物流 (HCT, Hsinchu Transportation) **直連 API** 完整參考文件。
4
-
5
- > **重要說明**
6
- > 本文件描述**直連 HCT 自家 API** 的整合方式 (申請後使用)。如僅需透過 ECPay/PayNow/SmilePay 等 aggregator 打 HCT 配送 (`LogisticsType=HCT` / `LogisticsSubType=TCAT`),請參考各 aggregator 的物流文件。
7
- >
8
- > HCT 與本工具包中的其他物流業者不同 — 它**本身就是配送公司 (carrier)**,並非 aggregator。本參考適用於需要直接對接新竹物流系統的中大型出貨企業。
9
-
10
- ---
11
-
12
- ## 目錄
13
-
14
- 1. [文件版本與適用情境](#文件版本與適用情境)
15
- 2. [API 服務分類](#api-服務分類)
16
- 3. [申請流程](#申請流程)
17
- 4. [環境與測試帳號](#環境與測試帳號)
18
- 5. [加解密機制](#加解密機制)
19
- 6. [查貨服務 (Track Shipment)](#查貨服務-track-shipment)
20
- - 網頁串接模式 (單筆)
21
- - 多筆貨號 XML 查詢
22
- - 貨況對應表
23
- 7. [出貨/託運單服務 (EDI Web Service)](#出貨託運單服務-edi-web-service)
24
- - TransData — 傳入託運資料
25
- - UpdData — 修改重量
26
- - TransReport — 列印總表
27
- - QueryEDELNO — 查詢貨號
28
- - R_TransData — 逆物流託運資料
29
- 8. [錯誤原因明細](#錯誤原因明細)
30
- 9. [整合最佳實務](#整合最佳實務)
31
- 10. [aggregator vs 直連對照](#aggregator-vs-直連對照)
32
-
33
- ---
34
-
35
- ## 文件版本與適用情境
36
-
37
- | 項目 | 內容 |
38
- |------|------|
39
- | **官方文件版本** | API 服務說明 V1 (2022/12/30 ver 2.0) |
40
- | **發行單位** | 新竹物流股份有限公司 / HCT Information Integration Services |
41
- | **聯絡電話** | 02-2837-1122 #5123 (許先生) |
42
- | **適用情境** | 大量出貨企業;自有 ERP/WMS 需直接對接 HCT;不透過 aggregator 中介 |
43
- | **不適用情境** | 一般電商小量出貨 (建議走 ECPay/PayNow 等 aggregator 較快) |
44
-
45
- ### 與 aggregator 的差異
46
-
47
- ```
48
- ┌──────────────────┐ ┌──────────────────┐
49
- │ aggregator 模式 │ │ HCT 直連模式 │
50
- ├──────────────────┤ ├──────────────────┤
51
- │ Your System │ │ Your System │
52
- │ ↓ │ │ ↓ │
53
- │ ECPay/PayNow │ │ HCT 自家 API │
54
- │ ↓ │ │ ↓ │
55
- │ HCT (carrier) │ │ HCT (carrier) │
56
- └──────────────────┘ └──────────────────┘
57
- LogisticsSubType=TCAT 直接呼叫 hct.com.tw
58
- 單一商店代號跨多家物流 需與 HCT 站所申請帳密
59
- 不需 HCT 帳號 適合大量出貨
60
- ```
61
-
62
- ---
63
-
64
- ## API 服務分類
65
-
66
- HCT 直連 API 共分為**兩大類**:
67
-
68
- | 服務類別 | 用途 | 串接方式 |
69
- |---------|------|---------|
70
- | **查貨服務** | 給客戶/收件人查貨況 | URL 嵌入 / XML POST |
71
- | **出貨/託運單服務** | 上傳託運資料、列印託運單 | SOAP / JSON / XML Web Service |
72
-
73
- ### 出貨服務主要 SOAP 方法
74
-
75
- | SOAP 方法 | 用途 | 說明 |
76
- |----------|------|------|
77
- | `TransData()` | 上傳託運資料 (列印託運單) | 傳入託運資料、取得貨號、到著站、標籤圖片 |
78
- | `TransData_Json()` | 同上 (JSON 格式) | |
79
- | `TransData_XML()` | 同上 (XML 格式) | |
80
- | `UpdData()` | 修改重量 | 傳入新竹貨號 + 訂單編號修改重量 |
81
- | `UpdData_Json()` | 同上 (JSON) | |
82
- | `UpdData_Xml()` | 同上 (XML) | |
83
- | `TransReport()` | 列印託運總表 | 當日確認出貨 (18:00 前上傳) |
84
- | `TransReport_Json()` | 同上 (JSON) | |
85
- | `TransReport_XML()` | 同上 (XML) | |
86
- | `QueryEDELNO()` | 查詢貨號 | 由訂單編號反查新竹貨號 |
87
- | `QueryEDELNO_Json()` | 同上 (JSON) | |
88
- | `QueryEDELNO_Xml()` | 同上 (XML) | |
89
- | `R_TransData_Json()` | 逆物流託運資料 | 退貨/取件 |
90
-
91
- ---
92
-
93
- ## 申請流程
94
-
95
- HCT 與多數 aggregator 不同,**沒有自助開發者後台**;服務必須透過配合的營業站所申請。
96
-
97
- ### 1. 申請查貨服務
98
-
99
- > API 查貨服務可與**配合站所電腦負責人**申請,將會提供串接申請表單 & 串接說明文件給您填寫。
100
-
101
- 申請後會取得:
102
-
103
- - 加 / 解密金鑰 (`v` 參數值)
104
- - 加密 Sample Code (C#)
105
- - 查貨用「特約客戶帳號」與「客戶代號」(若選擇用訂單編號查詢)
106
-
107
- ### 2. 申請出貨 / 託運單列印服務
108
-
109
- > API 出貨/託運單列印服務可與**配合站所電腦負責人**申請,將會提供串接申請表單 & 串接說明文件給您填寫。
110
-
111
- 申請後會取得:
112
-
113
- - 公司名稱 (`Company`)
114
- - 密碼 (`password`)
115
- - 客代 (`escsno`,11 碼)
116
- - 出貨站代號 (`esstno`,4 碼)
117
- - 新竹貨號區間及規則 (若需自行配號)
118
-
119
- > 申請時需選擇查貨基準鍵:**訂單編號** 或 **十碼貨號**,僅能擇一,**不可動態切換**。若日後要更改需聯繫原申請營業所。
120
-
121
- ---
122
-
123
- ## 環境與測試帳號
124
-
125
- ### 服務端點
126
-
127
- | 服務 | URL |
128
- |------|-----|
129
- | 查貨 (網頁) | `https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx` |
130
- | 查貨 (XML 多筆) | `https://hctapiweb.hct.com.tw/phone/searchGoods_Main_Xml.ashx` |
131
- | 出貨 EDI Web Service | `https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx` |
132
-
133
- ### 測試帳號 (出貨 API)
134
-
135
- | 欄位 | 值 |
136
- |------|-----|
137
- | Company | `test` |
138
- | password | `test1` |
139
-
140
- > ⚠️ **注意**:HCT **沒有獨立 sandbox 環境**。所有 API 端點都是**正式系統**,僅以測試帳號 `test/test1` 隔離測試資料。實作時請務必區分 production / staging 帳號,避免污染真實貨況。
141
-
142
- ### 系統維護時間
143
-
144
- > 我司系統於每日凌晨 **03:40 - 04:30** 進行查貨系統維護,期間不會有相關貨況更新。
145
-
146
- ---
147
-
148
- ## 加解密機制
149
-
150
- ### 重要提示
151
-
152
- > ※ **加 / 解密方式、相關金鑰參數將於申請後提供**。
153
- >
154
- > ※ **加密 Sample Code (C#) 於申請後會提供**。
155
-
156
- 公開文件中**未揭露具體的加解密演算法**,只說明:
157
-
158
- 1. 採 HCT **自訂加解密**機制
159
- 2. 加密後字串作為 `no` 參數附加於查貨網址或 POST body
160
- 3. `v` 參數為金鑰版本號 (公開範例顯示 `v=xxxxxx`)
161
- 4. 申請後 HCT 會提供 C# Sample Code 作為實作參考
162
-
163
- ### 加密應用位置
164
-
165
- | 位置 | 加密目標 |
166
- |------|---------|
167
- | 查貨網頁 URL | 訂單編號 / 貨號 → `no` 參數 |
168
- | 多筆 XML 查詢請求 | 整段 XML body → `no` 參數 |
169
- | 多筆 XML 查詢回應 | 整段 XML body 加密回傳,需自行解密 |
170
-
171
- ### 跨語言實作建議
172
-
173
- 由於官方僅提供 C# Sample Code,若需以 PHP / Python / Node.js / Go 實作,建議:
174
-
175
- 1. **先取得 C# Sample**:申請完成後請求 HCT 技術窗口提供 C# 範例
176
- 2. **解析演算法**:常見為 AES-CBC / DES / TripleDES + Base64 (URL-safe) 或 Hex 編碼,依 Sample 為準
177
- 3. **以單元測試驗證**:將 C# Sample 的「明文 → 密文」對應抓出,於目標語言重現相同輸出
178
- 4. **將 `v` 視為設定**:金鑰版本可能定期輪替,避免硬編碼
179
-
180
- ---
181
-
182
- ## 查貨服務 (Track Shipment)
183
-
184
- ### 網頁串接模式 (單筆訂單)
185
-
186
- 提供**單筆**訂單編號 / 貨號查詢,可直接連至新竹物流網頁顯示貨況。
187
-
188
- #### URL 格式
189
-
190
- ```
191
- https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx?no=加密字串&v=xxxxxx
192
- ```
193
-
194
- | 參數 | 說明 |
195
- |------|------|
196
- | `no` | 加密後的訂單編號或貨號 |
197
- | `v` | 金鑰版本 (申請時提供) |
198
-
199
- #### 使用情境
200
-
201
- > 產生的網址可放置於貴司網頁供客戶點擊查詢。
202
-
203
- 範例 (PHP,加密函式 `encryptHct()` 為申請後 HCT 提供之演算法):
204
-
205
- ```php
206
- <?php
207
- $orderId = 'A00001';
208
- $encrypted = encryptHct($orderId); // HCT 自訂加密
209
- $keyVersion = 'abcdef';
210
-
211
- $trackUrl = sprintf(
212
- 'https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx?no=%s&v=%s',
213
- urlencode($encrypted),
214
- $keyVersion
215
- );
216
-
217
- echo "<a href=\"{$trackUrl}\" target=\"_blank\">查詢貨況</a>";
218
- ```
219
-
220
- ---
221
-
222
- ### 多筆貨號查詢 (XML POST)
223
-
224
- 提供**多筆**訂單編號 / 貨號查詢,回傳 XML 加密後字串,解密後即可使用。
225
-
226
- #### 端點
227
-
228
- ```
229
- POST https://hctapiweb.hct.com.tw/phone/searchGoods_Main_Xml.ashx?no=加密後XML&v=xx
230
- ```
231
-
232
- > ※ 請求類型請使用 **POST**
233
-
234
- #### 加密前傳出格式 (XML)
235
-
236
- ```xml
237
- <?xml version="1.0" encoding="utf-8"?>
238
- <qrylist>
239
- <order orderid="1234567890"></order>
240
- <order orderid="1234567891"></order>
241
- </qrylist>
242
- ```
243
-
244
- #### 解密後返回格式 — 有貨況
245
-
246
- ```xml
247
- <?xml version="1.0" encoding="utf-8"?>
248
- <rlist>
249
- <orders ordersid="1234567890">
250
- <order orderid="1234567890" wrktime="YYYY/MM/DD HH24:MM"
251
- category="狀態分類" status="貨物狀況" />
252
- <order orderid="1234567890" wrktime="YYYY/MM/DD HH24:MM"
253
- category="狀態分類" status="貨物狀況 2" />
254
- </orders>
255
- <orders ordersid="1234567891">
256
- <order orderid="1234567891" wrktime="YYYY/MM/DD HH24:MM"
257
- category="狀態分類" status="貨物狀況" />
258
- </orders>
259
- </rlist>
260
- ```
261
-
262
- #### 解密後返回格式 — 無貨況
263
-
264
- ```xml
265
- <?xml version="1.0" encoding="UTF-8"?>
266
- <rlist />
267
- ```
268
-
269
- #### 注意事項
270
-
271
- | # | 規則 |
272
- |---|------|
273
- | 1 | 一般貨況**僅供查詢 30 天內資料**;歷史查詢需聯繫原申請營業所 |
274
- | 2 | 訂單編號與十碼貨號**只能擇一**進行查詢,申請時即決定 |
275
- | 3 | 若使用訂單編號查詢,**需綁定特約客戶帳號 + 客戶代號** |
276
- | 4 | XML 多筆查詢**單次上限 100 筆**,且需等前次回傳後才可再次提交 |
277
- | 5 | 系統每日凌晨 **03:40 - 04:30** 維護,期間無貨況更新 |
278
- | 6 | 異常請聯繫 02-2837-1122 #5123 許先生 |
279
-
280
- ---
281
-
282
- ### 貨況對應表
283
-
284
- HCT 中文貨況分類,以 `category` (狀態分類) + `status` (詳細描述) 兩層結構回傳。下表為**附件 - 貨況對應表**完整摘錄。
285
-
286
- #### 集貨類
287
-
288
- | category (狀態分類) | status (貨物狀況) |
289
- |---------|------|
290
- | 集貨 | 已由 xx 取件完成 |
291
- | 卸集貨 | 貨件已達 xx,貨件整理中。貨物件數共 N 件 |
292
- | 發送 | 貨件已抵達 xx,前往配送站途中 |
293
- | 到著 | 貨件已抵達 xx,分貨中 |
294
- | 配達 | 貨件由 xx 人員配送中 |
295
- | 持回 | 貨件由 xx 保管中 |
296
-
297
- #### 派遣類
298
-
299
- | category | status |
300
- |---------|------|
301
- | 派遣 | 取貨通知處理中 |
302
- | 支援 | xx 取件中 |
303
- | 客戶不在 | 寄貨人外出無法收件 |
304
- | 已取 | xx 已至客戶端取回貨件 |
305
- | 誤派 | xx 取件中 |
306
- | 址誤 | 取件異常地址錯誤,xx 處理中 |
307
- | 同業收取 | 取件異常,貨件由其他同業取走 |
308
- | 無貨可退 | 取件異常,無貨件可收 |
309
- | 其他 | 取件異常,專人處理中 |
310
-
311
- #### 預計到件時段
312
-
313
- | category | status |
314
- |---------|------|
315
- | 預計 12 點前 | 到客戶端 xx 取件中 |
316
- | 預計 15 點前 | 到客戶端 xx 取件中 |
317
- | 預計 17 點前 | 到客戶端 xx 取件中 |
318
- | 預計 17 點後 | 到客戶端 xx 取件中 |
319
-
320
- #### 取件異常
321
-
322
- | category | status |
323
- |---------|------|
324
- | 查無此人 | 該地址查無此人,確認中 |
325
- | 電聯異常 | 已電話聯繫,無人接聽 |
326
- | 商品保留不退 | 收件人確定保留商品,取消退貨 |
327
- | 約定收件 | 寄貨人外出,另約時間再次取件 |
328
- | 公司行號休息 | 收件地址為公司行號,本日休假 |
329
- | 派遣取消 | 廠商通知取消取件 |
330
- | 派遣確認 | xx 已派遣人員取件中 |
331
-
332
- #### 配交完成 / 異常
333
-
334
- | category | status |
335
- |---------|------|
336
- | 正常配交 | 貨件已由 xx 送達。貨物件數共 N 件 |
337
- | 缺件配達 | xx 缺件配交 |
338
- | 破損配達 | xx 破損配交 |
339
- | 客戶不在 | 送達客戶不在,xx 保管中 |
340
- | 地址錯誤 | 收貨人地址異常,xx 處理中 |
341
- | 查無此人 | 該地址查無此人,xx 處理中 |
342
- | 電聯異常 | 已電話聯繫,無人接聽 |
343
- | 到站自領 | 與客戶另約時間到站自領,xx 保管中 |
344
- | 拒收退回 | 貨件已退回,退貨號碼為 xx |
345
-
346
- #### 委外配送
347
-
348
- | category | status |
349
- |---------|------|
350
- | 委外配送中 | 貨件由 xx 委外金門協力商人員配送中 |
351
- | 委外配送中 | 貨件由 xx 委外澎湖協力商人員配送中 |
352
- | 委外配送中 | 貨件由 xx 種外協力商人員配送中 |
353
- | 委外配送中 | 貨件由 xx 轉運中 |
354
-
355
- > 本工具包未提供完整 `category → 內部訂單狀態` 的對應表;建議依電商系統自行規劃 `delivered` / `in_transit` / `failed` 等內部狀態的映射。
356
-
357
- ---
358
-
359
- ## 出貨/託運單服務 (EDI Web Service)
360
-
361
- ### 端點
362
-
363
- ```
364
- https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx
365
- ```
366
-
367
- > 此端點為 **SOAP Web Service**,亦提供 JSON / XML 變體方法。可透過 `?wsdl` 取得 SOAP 描述檔 (`Service1.asmx?wsdl`)。
368
-
369
- ### 重要規則
370
-
371
- | 規則 | 說明 |
372
- |------|------|
373
- | **客戶可選擇是否上傳新竹貨號** | 一併上傳新竹貨號 (區間及規則洽 HCT 資訊人員);或留空,由回傳值取得系統配號 |
374
- | **新竹貨號 + 訂單編號** | 當日重複上傳,視同**更正**資料內容 |
375
- | **訂單編號** | 同一個 `ESDATE` (出貨日期) **不可重複** |
376
- | **新竹貨號** | **100 天內不可重複** |
377
- | **總表列印** | 除標籤外仍需列印**出貨總表 (一式二份)**,供現場交接貨件使用 |
378
-
379
- ---
380
-
381
- ### TransData — 傳入託運資料
382
-
383
- #### SOAP 方法簽章
384
-
385
- ```csharp
386
- DataSet TransData(string Company, string password, DataSet data)
387
- string TransData_Json(string Company, string password, string json)
388
- string TransData_XML(string Company, string password, string xml)
389
- ```
390
-
391
- #### 傳入欄位 (Data 欄位、說明、長度)
392
-
393
- > PS:「預設值」欄位若有傳入值,**優先使用 DataTable 欄位內資料**
394
-
395
- | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
396
- |---------|---------|---------|------|
397
- | `epino` | 訂單編號 | Char(30) | **必要欄位** |
398
- | `ercsig` | 收貨人名稱 | Char(40) | **必要欄位** |
399
- | `ertel1` | 收貨人電話 1 | Char(15) | **必要欄位** |
400
- | `ertel2` | 收貨人電話 2 | Char(15) | |
401
- | `eraddr` | 收貨人地址 | Char(100) | **必要欄位** |
402
- | `ejamt` | 件數 | Char(4) | **必要欄位** (最小為 1) |
403
- | `eqamt` | 重量 | Char(5) | **必要欄位** (小數進位到整數) |
404
- | `esdate` | 出貨日期 | Char(8) | 預設今天 (`YYYYMMDD`) |
405
- | `escsno` | 客代 | Char(11) | 預設值 |
406
- | `esstno` | 出貨站 | Char(4) | 預設值 |
407
- | `edelno` | 新竹貨號 | Char(10) | 預設值 (如無提供系統自行配號) |
408
- | `etcsig` | 出貨人名稱 | Char(40) | 預設值 |
409
- | `ettel1` | 出貨人電話 1 | Char(15) | 預設值 |
410
- | `ettel2` | 出貨人電話 2 | Char(15) | 預設值 |
411
- | `etaddr` | 出貨地址 | Char(100) | 預設值 |
412
- | `eddate` | 指定日期 | Char(8) | 預設空白 (小於今日代空白) |
413
- | `eqmny` | 代收貨款 | Char(5) / Char(8) | 預設值 0;JSON/XML 變體為 Char(8) |
414
- | `eprdct` | 傳票類別 | Char(2) | 月結 `11` (預設) / 到付 `21` / 現收 `31` |
415
- | `emark` | 備註 | Char(100) | |
416
- | `eprdcl2` | 商品種類 | Char(3) | 一般 `001` (預設) / 冷凍 `003` / 冷藏 `008` |
417
- | `egamt` | 報值金額 | Char(5) | 保值貨物應報值,加收所報值金額 1% 為報值費 |
418
-
419
- #### 回傳欄位
420
-
421
- | 欄位名稱 | 欄位說明 |
422
- |---------|---------|
423
- | `Num` | 傳送序號 |
424
- | `success` | 結果 (新增 `Y` / 修改 `R` / 失敗 `N`) |
425
- | `edelno` | 新竹貨號 |
426
- | `epino` | 訂單編號 |
427
- | `erstno` | 到著站號碼 |
428
- | `eqamt` | 重量 |
429
- | `image` | 標籤圖片字串 (Hex 字串,需轉 byte → Bitmap) |
430
- | `ErrMsg` | 異常錯誤訊息 |
431
-
432
- #### JSON 範例
433
-
434
- **傳入值:**
435
-
436
- ```json
437
- [
438
- {
439
- "epino": "A00001",
440
- "ercsig": "Mary",
441
- "ertel1": "0911123456",
442
- "eraddr": "台中市大雅區中清路三段 513 號",
443
- "ejamt": "1",
444
- "eqamt": "10"
445
- },
446
- {
447
- "epino": "A00002",
448
- "ercsig": "Mary",
449
- "ertel1": "0911123456",
450
- "eraddr": "台中市大雅區中清路三段 513 號",
451
- "ejamt": "1",
452
- "eqamt": "5"
453
- }
454
- ]
455
- ```
456
-
457
- **回傳值:**
458
-
459
- ```json
460
- [
461
- {
462
- "Num": "1",
463
- "success": "Y",
464
- "edelno": "0000000001",
465
- "epino": "A00001",
466
- "erstno": "4004",
467
- "eqamt": "10",
468
- "image": "…(Hex 字串)…",
469
- "ErrMsg": null
470
- },
471
- {
472
- "Num": "2",
473
- "success": "Y",
474
- "edelno": "0000000002",
475
- "epino": "A00002",
476
- "erstno": "4004",
477
- "eqamt": "5",
478
- "image": "…(Hex 字串)…",
479
- "ErrMsg": null
480
- }
481
- ]
482
- ```
483
-
484
- #### XML 範例
485
-
486
- **傳入值:**
487
-
488
- ```xml
489
- <info>
490
- <DataRow>
491
- <epino>A00001</epino>
492
- <ercsig>Mary</ercsig>
493
- <ertel1>0911123456</ertel1>
494
- <eraddr>台中市大雅區中清路三段 513 號</eraddr>
495
- <ejamt>1</ejamt>
496
- <eqamt>10</eqamt>
497
- </DataRow>
498
- <DataRow>
499
- <epino>A00002</epino>
500
- <ercsig>Mary</ercsig>
501
- <ertel1>0911123456</ertel1>
502
- <eraddr>台中市大雅區中清路三段 513 號</eraddr>
503
- <ejamt>1</ejamt>
504
- <eqamt>5</eqamt>
505
- </DataRow>
506
- </info>
507
- ```
508
-
509
- **回傳值:**
510
-
511
- ```xml
512
- <info>
513
- <DataRow>
514
- <Num>1</Num>
515
- <success>Y</success>
516
- <edelno>0000000001</edelno>
517
- <epino>A00001</epino>
518
- <erstno>4004</erstno>
519
- <eqamt>10</eqamt>
520
- <image>…</image>
521
- <ErrMsg></ErrMsg>
522
- </DataRow>
523
- <DataRow>
524
- <Num>2</Num>
525
- <success>Y</success>
526
- <edelno>0000000002</edelno>
527
- <epino>A00002</epino>
528
- <erstno>4004</erstno>
529
- <eqamt>5</eqamt>
530
- <image>…</image>
531
- <ErrMsg></ErrMsg>
532
- </DataRow>
533
- </info>
534
- ```
535
-
536
- #### 圖片字串轉換 (C# 官方範例)
537
-
538
- 回傳的 `image` 欄位為 **Hex 字串**,需轉換為 byte 後再轉成 Bitmap:
539
-
540
- ```csharp
541
- // 字串轉 byte
542
- byte[] GetBytes(string HexString)
543
- {
544
- int byteLength = HexString.Length / 2;
545
- byte[] bytes = new byte[byteLength];
546
- string hex;
547
- int j = 0;
548
- for (int i = 0; i < bytes.Length; i++)
549
- {
550
- hex = new String(new Char[] { HexString[j], HexString[j + 1] });
551
- bytes[i] = HexToByte(hex);
552
- j = j + 2;
553
- }
554
- return bytes;
555
- }
556
-
557
- byte HexToByte(string hex)
558
- {
559
- if (hex.Length > 2 || hex.Length <= 0)
560
- throw new ArgumentException("hex must be 1 or 2 characters in length");
561
- return byte.Parse(hex, System.Globalization.NumberStyles.HexNumber);
562
- }
563
-
564
- // byte 轉成圖片 (1bit 黑白)
565
- Bitmap image(byte[] b)
566
- {
567
- MemoryStream ms = new MemoryStream(b);
568
- Bitmap bmp = (Bitmap)Bitmap.FromStream(ms);
569
- BitmapData bmpData = bmp.LockBits(
570
- new Rectangle(0, 0, bmp.Width, bmp.Height),
571
- ImageLockMode.ReadOnly,
572
- PixelFormat.Format1bppIndexed);
573
- bmp = new Bitmap(bmp.Width, bmp.Height, bmpData.Stride,
574
- PixelFormat.Format1bppIndexed, bmpData.Scan0);
575
- return bmp;
576
- }
577
- ```
578
-
579
- #### 設定檔注意事項 (官方提示)
580
-
581
- ##### TransData (SOAP)
582
-
583
- > 如果需要一次接收 2 張以上圖片,需要將 config 裡的
584
- > `maxBufferSize="65536"` `maxReceivedMessageSize="65536"`
585
- > **65536 的數字改成大一點**,因為 1 張圖片轉成 string 大約就 2 萬多。
586
-
587
- ##### TransData_JSON
588
-
589
- > 使用 JSON 接收圖檔字串,需要將 config 裡的
590
- > `readerQuotas` `maxStringContentLength="8192"`
591
- > **8192 數字改成大一點**,因為 1 張圖片轉成 string 大約就 2 萬多。
592
-
593
- ##### 批次大小
594
-
595
- > **PS:傳送一批資料請不要超過 30 筆,若使用回傳圖檔,一次上限為 5 筆。**
596
-
597
- ---
598
-
599
- ### UpdData — 修改重量
600
-
601
- #### SOAP 方法簽章
602
-
603
- ```csharp
604
- DataSet UpdData(string Company, string password, DataSet data)
605
- string UpdData_Json(string Company, string password, string json)
606
- string UpdData_XML(string Company, string password, string xml)
607
- ```
608
-
609
- #### 傳入欄位
610
-
611
- | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
612
- |---------|---------|---------|------|
613
- | `epino` | 訂單編號 | Char(30) | **必要欄位** |
614
- | `edelno` | 新竹貨號 | Char(10) | **必要欄位** |
615
- | `eqamt` | 重量 | Char(5) | **必要欄位** |
616
-
617
- #### 回傳欄位
618
-
619
- | 欄位名稱 | 欄位說明 |
620
- |---------|---------|
621
- | `Num` | 傳送序號 |
622
- | `success` | 結果 (修改 `R` / 失敗 `N`) |
623
- | `edelno` | 新竹貨號 |
624
- | `epino` | 訂單編號 |
625
- | `eqamt` | 重量 |
626
- | `ErrMsg` | 異常錯誤訊息 |
627
-
628
- ---
629
-
630
- ### TransReport — 列印總表
631
-
632
- 當日確認出貨時呼叫 (**18:00 前上傳**),產出**出貨總表 (一式二份)**,供現場交接貨件使用。
633
-
634
- #### SOAP 方法簽章
635
-
636
- ```csharp
637
- DataSet TransReport(string Company, string password, DataSet dsCus)
638
- string TransReport_Json(string Company, string password, string dsCusJson)
639
- string TransReport_XML(string Company, string password, string dsCusXML)
640
- ```
641
-
642
- #### 傳入欄位
643
-
644
- | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
645
- |---------|---------|---------|------|
646
- | `epino` | 訂單編號 | Char(30) | **必要欄位** |
647
- | `edelno` | 新竹貨號 | Char(10) | **必要欄位** |
648
-
649
- #### 回傳欄位
650
-
651
- | 欄位名稱 | 欄位說明 |
652
- |---------|---------|
653
- | `Num` | 序號 |
654
- | `success` | 結果 (成功 `Y` / 失敗 `N`) |
655
- | `edelno` | 新竹貨號 |
656
- | `epino` | 訂單編號 |
657
- | `ErrMsg` | 異常錯誤訊息 |
658
-
659
- #### XML 範例
660
-
661
- **傳入值:**
662
-
663
- ```xml
664
- <info>
665
- <DataRow>
666
- <epino>A00001</epino>
667
- <edelno>1234567890</edelno>
668
- </DataRow>
669
- <DataRow>
670
- <epino>A00002</epino>
671
- <edelno>1234567894</edelno>
672
- </DataRow>
673
- </info>
674
- ```
675
-
676
- **回傳值:**
677
-
678
- ```xml
679
- <info>
680
- <DataRow>
681
- <Num>1</Num>
682
- <success>Y</success>
683
- <edelno>0000000001</edelno>
684
- <epino>A00001</epino>
685
- <erstno>4004</erstno>
686
- <eqamt>10</eqamt>
687
- <ErrMsg></ErrMsg>
688
- </DataRow>
689
- <DataRow>
690
- <Num>2</Num>
691
- <success>Y</success>
692
- <edelno>0000000002</edelno>
693
- <epino>A00002</epino>
694
- <erstno>4004</erstno>
695
- <eqamt>5</eqamt>
696
- <ErrMsg></ErrMsg>
697
- </DataRow>
698
- </info>
699
- ```
700
-
701
- #### JSON 範例
702
-
703
- **傳入值:**
704
-
705
- ```json
706
- [
707
- { "epino": "A00001", "edelno": "1234567890" },
708
- { "epino": "A00002", "edelno": "1234567894" }
709
- ]
710
- ```
711
-
712
- **回傳值:**
713
-
714
- ```json
715
- [
716
- {
717
- "Num": "1",
718
- "success": "Y",
719
- "edelno": "0000000001",
720
- "epino": "A00001",
721
- "erstno": "4004",
722
- "eqamt": "10",
723
- "ErrMsg": null
724
- },
725
- {
726
- "Num": "2",
727
- "success": "Y",
728
- "edelno": "0000000002",
729
- "epino": "A00002",
730
- "erstno": "4004",
731
- "eqamt": "5",
732
- "ErrMsg": null
733
- }
734
- ]
735
- ```
736
-
737
- ---
738
-
739
- ### QueryEDELNO — 查詢貨號
740
-
741
- 由**訂單編號**反查已配發的**新竹貨號**。
742
-
743
- #### SOAP 方法簽章
744
-
745
- ```csharp
746
- DataSet QueryEDELNO(string company, string password, DataSet data)
747
- string QueryEDELNO_Json(string company, string password, string json)
748
- string QueryEDELNO_Xml(string company, string password, string xml)
749
- ```
750
-
751
- #### 輸入規則
752
-
753
- > `data` / `json` / `xml`:欲查詢貨號的訂單編號 (多筆可用 **`,` 逗號分隔**,**訂單編號中不能有逗號**)
754
-
755
- 範例輸入:`P002,S444` 或 `A001,P003,S444,P001`
756
-
757
- #### 回傳欄位
758
-
759
- | 欄位名稱 | 型別 | 欄位說明 |
760
- |---------|------|---------|
761
- | `success` | String | 結果 (成功 `Y` / 失敗 `N`) |
762
- | `edelno` | String | 新竹貨號 |
763
- | `epino` | String | 訂單編號 |
764
- | `ErrMsg` | String | 異常錯誤訊息 |
765
-
766
- #### JSON 回傳範例
767
-
768
- 傳入 `epino` 值為 `"P002,S444"`:
769
-
770
- ```json
771
- [
772
- {
773
- "success": "Y",
774
- "edelno": "2000001054",
775
- "epino": "P002",
776
- "ErrMsg": ""
777
- },
778
- {
779
- "success": "N",
780
- "edelno": "",
781
- "epino": "S444",
782
- "ErrMsg": "查無資料"
783
- }
784
- ]
785
- ```
786
-
787
- #### XML 回傳範例
788
-
789
- 傳入 `epino` 值為 `"A001,P003,S444,P001"`:
790
-
791
- ```xml
792
- <info>
793
- <DataRow>
794
- <success>Y</success>
795
- <edelno>2000001080</edelno>
796
- <epino>A001</epino>
797
- <ErrMsg></ErrMsg>
798
- </DataRow>
799
- <DataRow>
800
- <success>Y</success>
801
- <edelno>2000001065</edelno>
802
- <epino>P003</epino>
803
- <ErrMsg></ErrMsg>
804
- </DataRow>
805
- <DataRow>
806
- <success>N</success>
807
- <edelno></edelno>
808
- <epino>S444</epino>
809
- <ErrMsg>查無資料</ErrMsg>
810
- </DataRow>
811
- <DataRow>
812
- <success>Y</success>
813
- <edelno>2000001091</edelno>
814
- <epino>P001</epino>
815
- <ErrMsg></ErrMsg>
816
- </DataRow>
817
- </info>
818
- ```
819
-
820
- ---
821
-
822
- ### R_TransData — 逆物流託運資料
823
-
824
- 逆物流 (退貨/取件) 上傳資料。**目前僅提供 JSON 格式**。
825
-
826
- #### SOAP 方法簽章
827
-
828
- ```csharp
829
- string R_TransData_Json(string Company, string password, string json)
830
- ```
831
-
832
- #### 傳入欄位
833
-
834
- | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
835
- |---------|---------|---------|------|
836
- | `epino` | 訂單編號 | Char(30) | **必要欄位**,**不可重複** |
837
- | `ercsig` | 退貨人名稱 | Char(40) | **必要欄位**,逆物流跟誰收 |
838
- | `ertel1` | 退貨人電話 1 | Char(15) | **必要欄位**,逆物流跟誰收的電話 |
839
- | `ertel2` | 退貨人電話 2 | Char(15) | |
840
- | `eraddr` | 退貨人地址 | Char(100) | **必要欄位**,逆物流跟誰收的地址 |
841
- | `ejamt` | 件數 | Char(4) | **必要欄位** (總長運費的件數**只能輸入 1**) |
842
- | `eqamt` | 重量 | Char(5) | 總長重量只能 `60` / `90` / `120` / `150` / `151~999` (如無提供抓系統預設值) |
843
- | `esdate` | 出貨日期 | Char(8) | 預設今天 (`YYYYMMDD`) |
844
- | `escsno` | 客代 | Char(11) | 預設值 |
845
- | `edelno` | 新竹貨號 | Char(10) | 預設值 (如無提供系統自行配號) |
846
- | `etcsig` | 收貨人名稱 | Char(40) | 預設值 |
847
- | `ettel1` | 收貨人電話 1 | Char(15) | 預設值 |
848
- | `etaddr` | 收貨地址 | Char(100) | 預設值 |
849
- | `emark` | 備註 | Char(100) | |
850
- | `eprdcl2` | 商品種類 | Char(3) | 一般 `001` (預設) / 冷凍 `003` / 冷藏 `008` |
851
- | `edelno2` | **原查貨號碼** | Char(10) | **原正物流出貨查貨號碼** |
852
-
853
- #### 回傳欄位
854
-
855
- | 欄位名稱 | 欄位說明 |
856
- |---------|---------|
857
- | `Num` | 傳送序號 |
858
- | `success` | 結果 (新增 `Y` / 失敗 `N`) |
859
- | `edelno` | 新竹查貨貨號 |
860
- | `epino` | 訂單編號 |
861
- | `erstno` | 退貨人到著站號碼 (逆物流跟誰收的站所代號) |
862
- | `eqamt` | 重量 |
863
- | `ErrMsg` | 異常錯誤訊息 |
864
-
865
- #### JSON 範例
866
-
867
- **傳入值:**
868
-
869
- ```json
870
- [
871
- {
872
- "epino": "101000000012345",
873
- "ercsig": "張三",
874
- "ertel1": "0255927298",
875
- "ertel2": "",
876
- "eraddr": "台北市士林區中山北路六段 88 號",
877
- "ejamt": "1",
878
- "eqamt": "60",
879
- "esdate": "",
880
- "escsno": "12345678900",
881
- "edelno": "",
882
- "etcsig": "大大消防",
883
- "ettel1": "0911123456",
884
- "ettel2": "",
885
- "etaddr": "台中市大雅區中清路三段 513 號",
886
- "emark": "",
887
- "eprdcl2": "001",
888
- "edelno2": "8812213345"
889
- },
890
- {
891
- "epino": "101000000012346",
892
- "ercsig": "李四",
893
- "ertel1": "035218811",
894
- "ertel2": "",
895
- "eraddr": "新竹縣新豐鄉建興路 100 號",
896
- "ejamt": "1",
897
- "eqamt": "",
898
- "esdate": "",
899
- "escsno": "12345678900",
900
- "edelno": "",
901
- "etcsig": "大大消防",
902
- "ettel1": "0911123456",
903
- "ettel2": "",
904
- "etaddr": "台中市大雅區中清路三段 513 號",
905
- "emark": "",
906
- "eprdcl2": "001"
907
- }
908
- ]
909
- ```
910
-
911
- **回傳值:**
912
-
913
- ```json
914
- [
915
- {
916
- "Num": "1",
917
- "Success": "N",
918
- "Edelno": "",
919
- "Epino": "101000000012345",
920
- "Erstno": "1247",
921
- "Eqamt": "60",
922
- "ErrMsg": "原貨號檢查碼錯誤"
923
- },
924
- {
925
- "Num": "2",
926
- "Success": "Y",
927
- "Edelno": "2250446752",
928
- "Epino": "101000000012346",
929
- "Erstno": "2060",
930
- "Eqamt": "9",
931
- "ErrMsg": ""
932
- }
933
- ]
934
- ```
935
-
936
- ---
937
-
938
- ## 錯誤原因明細
939
-
940
- ### TransData 錯誤訊息
941
-
942
- | 錯誤訊息 | 錯誤原因 |
943
- |---------|---------|
944
- | 公司名稱或密碼錯誤 | Company / password 驗證失敗 |
945
- | 貨號重複 | 一個月內貨號重複 |
946
- | 貨號錯誤 | 沒新竹貨號 or 新竹貨號沒有 10 碼 |
947
- | 貨號檢查碼錯誤 | 貨號最後一碼規則 |
948
- | 訂單編號錯誤 | 訂單編號空白 |
949
- | 客代錯誤 | 客代沒有 11 碼 |
950
- | 件數錯誤 | 件數 0 |
951
- | 重量錯誤 | 重量 0 |
952
- | 收貨人名稱錯誤 | 收貨人空白 |
953
- | 收貨人電話錯誤 | 收貨人電話空白 |
954
- | 收貨人地址錯誤 | 收貨人地址空白 |
955
- | 出貨站錯誤 | 出貨站沒有 4 碼 |
956
- | 代收貨款錯誤 | TYPE = 41 但是沒有代收 |
957
- | 一個月內貨號重複 | 同一貨號 30 天內重複 |
958
- | 訂單編號重複 | 同一 ESDATE 內訂單編號重複 |
959
-
960
- ### UpdData 錯誤訊息
961
-
962
- | 錯誤訊息 | 錯誤原因 |
963
- |---------|---------|
964
- | 公司名稱或密碼錯誤 | 帳密失敗 |
965
- | 重量錯誤 | 重量 0 或非法 |
966
- | 查無貨號和訂單編號 | 找不到對應託運單 |
967
-
968
- ### TransReport 錯誤訊息
969
-
970
- | 錯誤訊息 | 錯誤原因 |
971
- |---------|---------|
972
- | 查無貨號 | DB 沒貨號 |
973
- | 已經上傳過此筆 | `ISMASTER = 1` (已上傳過總表) |
974
-
975
- ### R_TransData_Json 錯誤訊息
976
-
977
- | 錯誤訊息 | 錯誤原因 |
978
- |---------|---------|
979
- | 貨號重複 | 三個月內貨號重複 |
980
- | 貨號錯誤 | 貨號格式錯誤 |
981
- | 貨號檢查碼錯誤 | 貨號最後一碼規則錯誤 |
982
- | 貨號錯誤必須是 2 開頭 | 逆物流貨號需以 `2` 開頭 |
983
- | 原貨號錯誤 | `edelno2` 原查貨號碼錯誤 |
984
- | 訂單編號錯誤 | 訂單編號空白 |
985
- | 客代錯誤 | 客代格式錯誤 |
986
- | 件數錯誤 | 件數非法 |
987
- | 重量錯誤 | 重量非法 |
988
- | 退貨人名稱錯誤 | 退貨人空白 |
989
- | 退貨人電話錯誤 | 退貨人電話空白 |
990
- | 退貨人地址錯誤 | 退貨人地址空白 |
991
- | 退貨站錯誤 | 退貨站代號錯誤 |
992
- | 收貨人名稱錯誤 | 收貨人空白 |
993
- | 收貨人電話錯誤 | 收貨人電話空白 |
994
- | 收貨人地址錯誤 | 收貨人地址空白 |
995
- | 收貨站錯誤 | 收貨站代號錯誤 |
996
- | 總長請輸入重量 60、90、120、150、151~999 | 逆物流總長重量不在允許值內 |
997
- | 總長件數只能為 1 件 | 逆物流件數限制 |
998
- | 未建收退貨貨號區間 | HCT 端尚未建立逆物流貨號區間 |
999
- | 三個月內貨號重複 | 逆物流貨號 90 天唯一 |
1000
- | 訂單編號重複 | 訂單編號於系統內已存在 |
1001
-
1002
- ---
1003
-
1004
- ## 整合最佳實務
1005
-
1006
- ### 1. 帳密與金鑰管理
1007
-
1008
- - `Company` / `password` 與加解密金鑰請統一存放於後端 secrets 管理 (Vault / KMS / 環境變數)
1009
- - 切勿將測試帳號 `test/test1` 上線
1010
- - 加解密金鑰版本 `v` 視為設定,避免硬編碼
1011
-
1012
- ### 2. 託運單建立流程
1013
-
1014
- ```
1015
- 1. 建立訂單 → 預先保留訂單編號 (epino)
1016
- 2. 出貨日 → 呼叫 TransData 上傳託運資料
1017
- 3. 取得回應 → 儲存 edelno (新竹貨號)、erstno (到著站)、image (標籤)
1018
- 4. 列印標籤 → 將 image Hex 字串轉 Bitmap 印出
1019
- 5. 18:00 前 → 呼叫 TransReport 確認當日出貨 (重要!)
1020
- 6. 列印總表一式二份 → 現場交接貨件使用
1021
- ```
1022
-
1023
- > **TransReport 必呼叫**:未呼叫 TransReport 即視為**未確認出貨**,HCT 不會排車收件。
1024
-
1025
- ### 3. 重量更新時機
1026
-
1027
- 當實際過磅重量與預估不同時,**在 TransReport 之前**呼叫 `UpdData` 修改重量;TransReport 後重量即固化。
1028
-
1029
- ### 4. 貨況查詢策略
1030
-
1031
- | 場景 | 建議 API |
1032
- |------|---------|
1033
- | 客戶端「查詢貨況」按鈕 | 網頁串接模式 (URL 嵌入) |
1034
- | 後端排程同步多筆貨況 | XML 多筆查詢 (每次 ≤ 100 筆) |
1035
- | 訂單列表顯示「目前狀態」 | XML 多筆查詢 + 內部狀態映射 |
1036
-
1037
- > 貨況僅保留 30 天,請於後端 DB 持久化關鍵狀態 (集貨 / 配達 / 異常)。
1038
-
1039
- ### 5. 批次大小
1040
-
1041
- | API | 批次上限 |
1042
- |-----|---------|
1043
- | TransData (純資料) | 30 筆 / 批 |
1044
- | TransData (含 image 回傳) | **5 筆 / 批** |
1045
- | 多筆貨號 XML 查詢 | 100 筆 / 批 |
1046
-
1047
- ### 6. 重複保護
1048
-
1049
- | 鍵 | 重複窗口 |
1050
- |---|---------|
1051
- | `epino` (訂單編號) | 同一 `esdate` 內唯一 |
1052
- | `edelno` (新竹貨號) | 100 天唯一 |
1053
- | 逆物流 `edelno` | 90 天唯一 (錯誤訊息為「三個月內貨號重複」) |
1054
-
1055
- ### 7. 重試策略
1056
-
1057
- - HCT 系統每日 **03:40 - 04:30** 維護,建議排程避開此時段
1058
- - 對暫時性 5xx 錯誤可重試 (建議指數退避,最多 3 次)
1059
- - 對「貨號重複」「貨號檢查碼錯誤」等業務型錯誤**不可盲目重試**,需人工檢核
1060
-
1061
- ### 8. 跨語言實作建議
1062
-
1063
- 由於官方僅提供 .NET / C# Sample (`DataSet` 為 .NET 特有型別),建議:
1064
-
1065
- - **Java / Kotlin / Go / Python / Node.js**:直接使用 `*_Json` / `*_XML` 變體方法,避免處理 .NET DataSet 序列化
1066
- - **PHP**:可用 SOAP Extension 或直接 HTTP POST 至 `?wsdl` 端點
1067
- - **WSDL 取得**:`https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx?wsdl`
1068
-
1069
- ---
1070
-
1071
- ## aggregator vs 直連對照
1072
-
1073
- | 構面 | 透過 aggregator (ECPay/PayNow/SmilePay) | 直連 HCT API |
1074
- |------|----------------------------------------|-------------|
1075
- | **申請門檻** | 低 (註冊網路會員即可) | 中高 (需與營業所簽約) |
1076
- | **適合規模** | 個人/中小型電商 | 中大型企業 / ERP 整合 |
1077
- | **費率** | aggregator 抽成 + 物流費 | 直接費率 (依量級議價) |
1078
- | **物流業者切換** | 改 `LogisticsSubType` 即可 | 僅限 HCT |
1079
- | **託運單編號** | aggregator 包裝後的 ID | 原生新竹貨號 (10 碼) |
1080
- | **貨況同步** | aggregator webhook | 自行排程查詢 (XML 多筆) |
1081
- | **逆物流** | 透過 aggregator 建立 | `R_TransData` 直接送 HCT |
1082
- | **代碼對照** | `LogisticsSubType=TCAT` (黑貓) / `HCT` (新竹) | 不適用,直接是 HCT 系統 |
1083
- | **WSDL / SOAP** | 由 aggregator 抽象掉 | 需自行處理 SOAP / JSON / XML |
1084
-
1085
- > 提醒:在 ECPay 物流文件中常出現的 `LogisticsSubType=TCAT` 是「黑貓宅急便」,並非新竹物流;新竹物流在 aggregator 中通常以獨立的子類型代碼表示,請以該 aggregator 文件為準。
1086
-
1087
- ---
1088
-
1089
- ## 官方資源
1090
-
1091
- - **官方網站**:https://www.hct.com.tw/
1092
- - **API 端點 (查貨)**:https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx
1093
- - **API 端點 (查貨 XML)**:https://hctapiweb.hct.com.tw/phone/searchGoods_Main_Xml.ashx
1094
- - **API 端點 (出貨 SOAP)**:https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx
1095
- - **WSDL**:https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx?wsdl
1096
- - **技術窗口**:02-2837-1122 #5123 (許先生)
1097
- - **官方文件**:申請後由 HCT 站所電腦負責人提供 PDF (`API服務說明_V1.pdf`,27 頁)
1098
- - **加密 Sample Code**:申請後由 HCT 提供 (C# 版本)
1099
-
1100
- ---
1101
-
1102
- 最後更新:2026/05/07
1
+ # HCT Logistics API Reference
2
+
3
+ 新竹物流 (HCT, Hsinchu Transportation) **直連 API** 完整參考文件。
4
+
5
+ > **重要說明**
6
+ > 本文件描述**直連 HCT 自家 API** 的整合方式 (申請後使用)。如僅需透過 ECPay/PayNow/SmilePay 等 aggregator 打 HCT 配送 (`LogisticsType=HCT` / `LogisticsSubType=TCAT`),請參考各 aggregator 的物流文件。
7
+ >
8
+ > HCT 與本工具包中的其他物流業者不同 — 它**本身就是配送公司 (carrier)**,並非 aggregator。本參考適用於需要直接對接新竹物流系統的中大型出貨企業。
9
+
10
+ ---
11
+
12
+ ## 目錄
13
+
14
+ 1. [文件版本與適用情境](#文件版本與適用情境)
15
+ 2. [API 服務分類](#api-服務分類)
16
+ 3. [申請流程](#申請流程)
17
+ 4. [環境與測試帳號](#環境與測試帳號)
18
+ 5. [加解密機制](#加解密機制)
19
+ 6. [查貨服務 (Track Shipment)](#查貨服務-track-shipment)
20
+ - 網頁串接模式 (單筆)
21
+ - 多筆貨號 XML 查詢
22
+ - 貨況對應表
23
+ 7. [出貨/託運單服務 (EDI Web Service)](#出貨託運單服務-edi-web-service)
24
+ - TransData — 傳入託運資料
25
+ - UpdData — 修改重量
26
+ - TransReport — 列印總表
27
+ - QueryEDELNO — 查詢貨號
28
+ - R_TransData — 逆物流託運資料
29
+ 8. [錯誤原因明細](#錯誤原因明細)
30
+ 9. [整合最佳實務](#整合最佳實務)
31
+ 10. [aggregator vs 直連對照](#aggregator-vs-直連對照)
32
+
33
+ ---
34
+
35
+ ## 文件版本與適用情境
36
+
37
+ | 項目 | 內容 |
38
+ |------|------|
39
+ | **官方文件版本** | API 服務說明 V1 (2022/12/30 ver 2.0) |
40
+ | **發行單位** | 新竹物流股份有限公司 / HCT Information Integration Services |
41
+ | **聯絡電話** | 02-2837-1122 #5123 (許先生) |
42
+ | **適用情境** | 大量出貨企業;自有 ERP/WMS 需直接對接 HCT;不透過 aggregator 中介 |
43
+ | **不適用情境** | 一般電商小量出貨 (建議走 ECPay/PayNow 等 aggregator 較快) |
44
+
45
+ ### 與 aggregator 的差異
46
+
47
+ ```
48
+ ┌──────────────────┐ ┌──────────────────┐
49
+ │ aggregator 模式 │ │ HCT 直連模式 │
50
+ ├──────────────────┤ ├──────────────────┤
51
+ │ Your System │ │ Your System │
52
+ │ ↓ │ │ ↓ │
53
+ │ ECPay/PayNow │ │ HCT 自家 API │
54
+ │ ↓ │ │ ↓ │
55
+ │ HCT (carrier) │ │ HCT (carrier) │
56
+ └──────────────────┘ └──────────────────┘
57
+ LogisticsSubType=TCAT 直接呼叫 hct.com.tw
58
+ 單一商店代號跨多家物流 需與 HCT 站所申請帳密
59
+ 不需 HCT 帳號 適合大量出貨
60
+ ```
61
+
62
+ ---
63
+
64
+ ## API 服務分類
65
+
66
+ HCT 直連 API 共分為**兩大類**:
67
+
68
+ | 服務類別 | 用途 | 串接方式 |
69
+ |---------|------|---------|
70
+ | **查貨服務** | 給客戶/收件人查貨況 | URL 嵌入 / XML POST |
71
+ | **出貨/託運單服務** | 上傳託運資料、列印託運單 | SOAP / JSON / XML Web Service |
72
+
73
+ ### 出貨服務主要 SOAP 方法
74
+
75
+ | SOAP 方法 | 用途 | 說明 |
76
+ |----------|------|------|
77
+ | `TransData()` | 上傳託運資料 (列印託運單) | 傳入託運資料、取得貨號、到著站、標籤圖片 |
78
+ | `TransData_Json()` | 同上 (JSON 格式) | |
79
+ | `TransData_XML()` | 同上 (XML 格式) | |
80
+ | `UpdData()` | 修改重量 | 傳入新竹貨號 + 訂單編號修改重量 |
81
+ | `UpdData_Json()` | 同上 (JSON) | |
82
+ | `UpdData_Xml()` | 同上 (XML) | |
83
+ | `TransReport()` | 列印託運總表 | 當日確認出貨 (18:00 前上傳) |
84
+ | `TransReport_Json()` | 同上 (JSON) | |
85
+ | `TransReport_XML()` | 同上 (XML) | |
86
+ | `QueryEDELNO()` | 查詢貨號 | 由訂單編號反查新竹貨號 |
87
+ | `QueryEDELNO_Json()` | 同上 (JSON) | |
88
+ | `QueryEDELNO_Xml()` | 同上 (XML) | |
89
+ | `R_TransData_Json()` | 逆物流託運資料 | 退貨/取件 |
90
+
91
+ ---
92
+
93
+ ## 申請流程
94
+
95
+ HCT 與多數 aggregator 不同,**沒有自助開發者後台**;服務必須透過配合的營業站所申請。
96
+
97
+ ### 1. 申請查貨服務
98
+
99
+ > API 查貨服務可與**配合站所電腦負責人**申請,將會提供串接申請表單 & 串接說明文件給您填寫。
100
+
101
+ 申請後會取得:
102
+
103
+ - 加 / 解密金鑰 (`v` 參數值)
104
+ - 加密 Sample Code (C#)
105
+ - 查貨用「特約客戶帳號」與「客戶代號」(若選擇用訂單編號查詢)
106
+
107
+ ### 2. 申請出貨 / 託運單列印服務
108
+
109
+ > API 出貨/託運單列印服務可與**配合站所電腦負責人**申請,將會提供串接申請表單 & 串接說明文件給您填寫。
110
+
111
+ 申請後會取得:
112
+
113
+ - 公司名稱 (`Company`)
114
+ - 密碼 (`password`)
115
+ - 客代 (`escsno`,11 碼)
116
+ - 出貨站代號 (`esstno`,4 碼)
117
+ - 新竹貨號區間及規則 (若需自行配號)
118
+
119
+ > 申請時需選擇查貨基準鍵:**訂單編號** 或 **十碼貨號**,僅能擇一,**不可動態切換**。若日後要更改需聯繫原申請營業所。
120
+
121
+ ---
122
+
123
+ ## 環境與測試帳號
124
+
125
+ ### 服務端點
126
+
127
+ | 服務 | URL |
128
+ |------|-----|
129
+ | 查貨 (網頁) | `https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx` |
130
+ | 查貨 (XML 多筆) | `https://hctapiweb.hct.com.tw/phone/searchGoods_Main_Xml.ashx` |
131
+ | 出貨 EDI Web Service | `https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx` |
132
+
133
+ ### 測試帳號 (出貨 API)
134
+
135
+ | 欄位 | 值 |
136
+ |------|-----|
137
+ | Company | `test` |
138
+ | password | `test1` |
139
+
140
+ > ⚠️ **注意**:HCT **沒有獨立 sandbox 環境**。所有 API 端點都是**正式系統**,僅以測試帳號 `test/test1` 隔離測試資料。實作時請務必區分 production / staging 帳號,避免污染真實貨況。
141
+
142
+ ### 系統維護時間
143
+
144
+ > 我司系統於每日凌晨 **03:40 - 04:30** 進行查貨系統維護,期間不會有相關貨況更新。
145
+
146
+ ---
147
+
148
+ ## 加解密機制
149
+
150
+ ### 重要提示
151
+
152
+ > ※ **加 / 解密方式、相關金鑰參數將於申請後提供**。
153
+ >
154
+ > ※ **加密 Sample Code (C#) 於申請後會提供**。
155
+
156
+ 公開文件中**未揭露具體的加解密演算法**,只說明:
157
+
158
+ 1. 採 HCT **自訂加解密**機制
159
+ 2. 加密後字串作為 `no` 參數附加於查貨網址或 POST body
160
+ 3. `v` 參數為金鑰版本號 (公開範例顯示 `v=xxxxxx`)
161
+ 4. 申請後 HCT 會提供 C# Sample Code 作為實作參考
162
+
163
+ ### 加密應用位置
164
+
165
+ | 位置 | 加密目標 |
166
+ |------|---------|
167
+ | 查貨網頁 URL | 訂單編號 / 貨號 → `no` 參數 |
168
+ | 多筆 XML 查詢請求 | 整段 XML body → `no` 參數 |
169
+ | 多筆 XML 查詢回應 | 整段 XML body 加密回傳,需自行解密 |
170
+
171
+ ### 跨語言實作建議
172
+
173
+ 由於官方僅提供 C# Sample Code,若需以 PHP / Python / Node.js / Go 實作,建議:
174
+
175
+ 1. **先取得 C# Sample**:申請完成後請求 HCT 技術窗口提供 C# 範例
176
+ 2. **解析演算法**:常見為 AES-CBC / DES / TripleDES + Base64 (URL-safe) 或 Hex 編碼,依 Sample 為準
177
+ 3. **以單元測試驗證**:將 C# Sample 的「明文 → 密文」對應抓出,於目標語言重現相同輸出
178
+ 4. **將 `v` 視為設定**:金鑰版本可能定期輪替,避免硬編碼
179
+
180
+ ---
181
+
182
+ ## 查貨服務 (Track Shipment)
183
+
184
+ ### 網頁串接模式 (單筆訂單)
185
+
186
+ 提供**單筆**訂單編號 / 貨號查詢,可直接連至新竹物流網頁顯示貨況。
187
+
188
+ #### URL 格式
189
+
190
+ ```
191
+ https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx?no=加密字串&v=xxxxxx
192
+ ```
193
+
194
+ | 參數 | 說明 |
195
+ |------|------|
196
+ | `no` | 加密後的訂單編號或貨號 |
197
+ | `v` | 金鑰版本 (申請時提供) |
198
+
199
+ #### 使用情境
200
+
201
+ > 產生的網址可放置於貴司網頁供客戶點擊查詢。
202
+
203
+ 範例 (PHP,加密函式 `encryptHct()` 為申請後 HCT 提供之演算法):
204
+
205
+ ```php
206
+ <?php
207
+ $orderId = 'A00001';
208
+ $encrypted = encryptHct($orderId); // HCT 自訂加密
209
+ $keyVersion = 'abcdef';
210
+
211
+ $trackUrl = sprintf(
212
+ 'https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx?no=%s&v=%s',
213
+ urlencode($encrypted),
214
+ $keyVersion
215
+ );
216
+
217
+ echo "<a href=\"{$trackUrl}\" target=\"_blank\">查詢貨況</a>";
218
+ ```
219
+
220
+ ---
221
+
222
+ ### 多筆貨號查詢 (XML POST)
223
+
224
+ 提供**多筆**訂單編號 / 貨號查詢,回傳 XML 加密後字串,解密後即可使用。
225
+
226
+ #### 端點
227
+
228
+ ```
229
+ POST https://hctapiweb.hct.com.tw/phone/searchGoods_Main_Xml.ashx?no=加密後XML&v=xx
230
+ ```
231
+
232
+ > ※ 請求類型請使用 **POST**
233
+
234
+ #### 加密前傳出格式 (XML)
235
+
236
+ ```xml
237
+ <?xml version="1.0" encoding="utf-8"?>
238
+ <qrylist>
239
+ <order orderid="1234567890"></order>
240
+ <order orderid="1234567891"></order>
241
+ </qrylist>
242
+ ```
243
+
244
+ #### 解密後返回格式 — 有貨況
245
+
246
+ ```xml
247
+ <?xml version="1.0" encoding="utf-8"?>
248
+ <rlist>
249
+ <orders ordersid="1234567890">
250
+ <order orderid="1234567890" wrktime="YYYY/MM/DD HH24:MM"
251
+ category="狀態分類" status="貨物狀況" />
252
+ <order orderid="1234567890" wrktime="YYYY/MM/DD HH24:MM"
253
+ category="狀態分類" status="貨物狀況 2" />
254
+ </orders>
255
+ <orders ordersid="1234567891">
256
+ <order orderid="1234567891" wrktime="YYYY/MM/DD HH24:MM"
257
+ category="狀態分類" status="貨物狀況" />
258
+ </orders>
259
+ </rlist>
260
+ ```
261
+
262
+ #### 解密後返回格式 — 無貨況
263
+
264
+ ```xml
265
+ <?xml version="1.0" encoding="UTF-8"?>
266
+ <rlist />
267
+ ```
268
+
269
+ #### 注意事項
270
+
271
+ | # | 規則 |
272
+ |---|------|
273
+ | 1 | 一般貨況**僅供查詢 30 天內資料**;歷史查詢需聯繫原申請營業所 |
274
+ | 2 | 訂單編號與十碼貨號**只能擇一**進行查詢,申請時即決定 |
275
+ | 3 | 若使用訂單編號查詢,**需綁定特約客戶帳號 + 客戶代號** |
276
+ | 4 | XML 多筆查詢**單次上限 100 筆**,且需等前次回傳後才可再次提交 |
277
+ | 5 | 系統每日凌晨 **03:40 - 04:30** 維護,期間無貨況更新 |
278
+ | 6 | 異常請聯繫 02-2837-1122 #5123 許先生 |
279
+
280
+ ---
281
+
282
+ ### 貨況對應表
283
+
284
+ HCT 中文貨況分類,以 `category` (狀態分類) + `status` (詳細描述) 兩層結構回傳。下表為**附件 - 貨況對應表**完整摘錄。
285
+
286
+ #### 集貨類
287
+
288
+ | category (狀態分類) | status (貨物狀況) |
289
+ |---------|------|
290
+ | 集貨 | 已由 xx 取件完成 |
291
+ | 卸集貨 | 貨件已達 xx,貨件整理中。貨物件數共 N 件 |
292
+ | 發送 | 貨件已抵達 xx,前往配送站途中 |
293
+ | 到著 | 貨件已抵達 xx,分貨中 |
294
+ | 配達 | 貨件由 xx 人員配送中 |
295
+ | 持回 | 貨件由 xx 保管中 |
296
+
297
+ #### 派遣類
298
+
299
+ | category | status |
300
+ |---------|------|
301
+ | 派遣 | 取貨通知處理中 |
302
+ | 支援 | xx 取件中 |
303
+ | 客戶不在 | 寄貨人外出無法收件 |
304
+ | 已取 | xx 已至客戶端取回貨件 |
305
+ | 誤派 | xx 取件中 |
306
+ | 址誤 | 取件異常地址錯誤,xx 處理中 |
307
+ | 同業收取 | 取件異常,貨件由其他同業取走 |
308
+ | 無貨可退 | 取件異常,無貨件可收 |
309
+ | 其他 | 取件異常,專人處理中 |
310
+
311
+ #### 預計到件時段
312
+
313
+ | category | status |
314
+ |---------|------|
315
+ | 預計 12 點前 | 到客戶端 xx 取件中 |
316
+ | 預計 15 點前 | 到客戶端 xx 取件中 |
317
+ | 預計 17 點前 | 到客戶端 xx 取件中 |
318
+ | 預計 17 點後 | 到客戶端 xx 取件中 |
319
+
320
+ #### 取件異常
321
+
322
+ | category | status |
323
+ |---------|------|
324
+ | 查無此人 | 該地址查無此人,確認中 |
325
+ | 電聯異常 | 已電話聯繫,無人接聽 |
326
+ | 商品保留不退 | 收件人確定保留商品,取消退貨 |
327
+ | 約定收件 | 寄貨人外出,另約時間再次取件 |
328
+ | 公司行號休息 | 收件地址為公司行號,本日休假 |
329
+ | 派遣取消 | 廠商通知取消取件 |
330
+ | 派遣確認 | xx 已派遣人員取件中 |
331
+
332
+ #### 配交完成 / 異常
333
+
334
+ | category | status |
335
+ |---------|------|
336
+ | 正常配交 | 貨件已由 xx 送達。貨物件數共 N 件 |
337
+ | 缺件配達 | xx 缺件配交 |
338
+ | 破損配達 | xx 破損配交 |
339
+ | 客戶不在 | 送達客戶不在,xx 保管中 |
340
+ | 地址錯誤 | 收貨人地址異常,xx 處理中 |
341
+ | 查無此人 | 該地址查無此人,xx 處理中 |
342
+ | 電聯異常 | 已電話聯繫,無人接聽 |
343
+ | 到站自領 | 與客戶另約時間到站自領,xx 保管中 |
344
+ | 拒收退回 | 貨件已退回,退貨號碼為 xx |
345
+
346
+ #### 委外配送
347
+
348
+ | category | status |
349
+ |---------|------|
350
+ | 委外配送中 | 貨件由 xx 委外金門協力商人員配送中 |
351
+ | 委外配送中 | 貨件由 xx 委外澎湖協力商人員配送中 |
352
+ | 委外配送中 | 貨件由 xx 種外協力商人員配送中 |
353
+ | 委外配送中 | 貨件由 xx 轉運中 |
354
+
355
+ > 本工具包未提供完整 `category → 內部訂單狀態` 的對應表;建議依電商系統自行規劃 `delivered` / `in_transit` / `failed` 等內部狀態的映射。
356
+
357
+ ---
358
+
359
+ ## 出貨/託運單服務 (EDI Web Service)
360
+
361
+ ### 端點
362
+
363
+ ```
364
+ https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx
365
+ ```
366
+
367
+ > 此端點為 **SOAP Web Service**,亦提供 JSON / XML 變體方法。可透過 `?wsdl` 取得 SOAP 描述檔 (`Service1.asmx?wsdl`)。
368
+
369
+ ### 重要規則
370
+
371
+ | 規則 | 說明 |
372
+ |------|------|
373
+ | **客戶可選擇是否上傳新竹貨號** | 一併上傳新竹貨號 (區間及規則洽 HCT 資訊人員);或留空,由回傳值取得系統配號 |
374
+ | **新竹貨號 + 訂單編號** | 當日重複上傳,視同**更正**資料內容 |
375
+ | **訂單編號** | 同一個 `ESDATE` (出貨日期) **不可重複** |
376
+ | **新竹貨號** | **100 天內不可重複** |
377
+ | **總表列印** | 除標籤外仍需列印**出貨總表 (一式二份)**,供現場交接貨件使用 |
378
+
379
+ ---
380
+
381
+ ### TransData — 傳入託運資料
382
+
383
+ #### SOAP 方法簽章
384
+
385
+ ```csharp
386
+ DataSet TransData(string Company, string password, DataSet data)
387
+ string TransData_Json(string Company, string password, string json)
388
+ string TransData_XML(string Company, string password, string xml)
389
+ ```
390
+
391
+ #### 傳入欄位 (Data 欄位、說明、長度)
392
+
393
+ > PS:「預設值」欄位若有傳入值,**優先使用 DataTable 欄位內資料**
394
+
395
+ | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
396
+ |---------|---------|---------|------|
397
+ | `epino` | 訂單編號 | Char(30) | **必要欄位** |
398
+ | `ercsig` | 收貨人名稱 | Char(40) | **必要欄位** |
399
+ | `ertel1` | 收貨人電話 1 | Char(15) | **必要欄位** |
400
+ | `ertel2` | 收貨人電話 2 | Char(15) | |
401
+ | `eraddr` | 收貨人地址 | Char(100) | **必要欄位** |
402
+ | `ejamt` | 件數 | Char(4) | **必要欄位** (最小為 1) |
403
+ | `eqamt` | 重量 | Char(5) | **必要欄位** (小數進位到整數) |
404
+ | `esdate` | 出貨日期 | Char(8) | 預設今天 (`YYYYMMDD`) |
405
+ | `escsno` | 客代 | Char(11) | 預設值 |
406
+ | `esstno` | 出貨站 | Char(4) | 預設值 |
407
+ | `edelno` | 新竹貨號 | Char(10) | 預設值 (如無提供系統自行配號) |
408
+ | `etcsig` | 出貨人名稱 | Char(40) | 預設值 |
409
+ | `ettel1` | 出貨人電話 1 | Char(15) | 預設值 |
410
+ | `ettel2` | 出貨人電話 2 | Char(15) | 預設值 |
411
+ | `etaddr` | 出貨地址 | Char(100) | 預設值 |
412
+ | `eddate` | 指定日期 | Char(8) | 預設空白 (小於今日代空白) |
413
+ | `eqmny` | 代收貨款 | Char(5) / Char(8) | 預設值 0;JSON/XML 變體為 Char(8) |
414
+ | `eprdct` | 傳票類別 | Char(2) | 月結 `11` (預設) / 到付 `21` / 現收 `31` |
415
+ | `emark` | 備註 | Char(100) | |
416
+ | `eprdcl2` | 商品種類 | Char(3) | 一般 `001` (預設) / 冷凍 `003` / 冷藏 `008` |
417
+ | `egamt` | 報值金額 | Char(5) | 保值貨物應報值,加收所報值金額 1% 為報值費 |
418
+
419
+ #### 回傳欄位
420
+
421
+ | 欄位名稱 | 欄位說明 |
422
+ |---------|---------|
423
+ | `Num` | 傳送序號 |
424
+ | `success` | 結果 (新增 `Y` / 修改 `R` / 失敗 `N`) |
425
+ | `edelno` | 新竹貨號 |
426
+ | `epino` | 訂單編號 |
427
+ | `erstno` | 到著站號碼 |
428
+ | `eqamt` | 重量 |
429
+ | `image` | 標籤圖片字串 (Hex 字串,需轉 byte → Bitmap) |
430
+ | `ErrMsg` | 異常錯誤訊息 |
431
+
432
+ #### JSON 範例
433
+
434
+ **傳入值:**
435
+
436
+ ```json
437
+ [
438
+ {
439
+ "epino": "A00001",
440
+ "ercsig": "Mary",
441
+ "ertel1": "0911123456",
442
+ "eraddr": "台中市大雅區中清路三段 513 號",
443
+ "ejamt": "1",
444
+ "eqamt": "10"
445
+ },
446
+ {
447
+ "epino": "A00002",
448
+ "ercsig": "Mary",
449
+ "ertel1": "0911123456",
450
+ "eraddr": "台中市大雅區中清路三段 513 號",
451
+ "ejamt": "1",
452
+ "eqamt": "5"
453
+ }
454
+ ]
455
+ ```
456
+
457
+ **回傳值:**
458
+
459
+ ```json
460
+ [
461
+ {
462
+ "Num": "1",
463
+ "success": "Y",
464
+ "edelno": "0000000001",
465
+ "epino": "A00001",
466
+ "erstno": "4004",
467
+ "eqamt": "10",
468
+ "image": "…(Hex 字串)…",
469
+ "ErrMsg": null
470
+ },
471
+ {
472
+ "Num": "2",
473
+ "success": "Y",
474
+ "edelno": "0000000002",
475
+ "epino": "A00002",
476
+ "erstno": "4004",
477
+ "eqamt": "5",
478
+ "image": "…(Hex 字串)…",
479
+ "ErrMsg": null
480
+ }
481
+ ]
482
+ ```
483
+
484
+ #### XML 範例
485
+
486
+ **傳入值:**
487
+
488
+ ```xml
489
+ <info>
490
+ <DataRow>
491
+ <epino>A00001</epino>
492
+ <ercsig>Mary</ercsig>
493
+ <ertel1>0911123456</ertel1>
494
+ <eraddr>台中市大雅區中清路三段 513 號</eraddr>
495
+ <ejamt>1</ejamt>
496
+ <eqamt>10</eqamt>
497
+ </DataRow>
498
+ <DataRow>
499
+ <epino>A00002</epino>
500
+ <ercsig>Mary</ercsig>
501
+ <ertel1>0911123456</ertel1>
502
+ <eraddr>台中市大雅區中清路三段 513 號</eraddr>
503
+ <ejamt>1</ejamt>
504
+ <eqamt>5</eqamt>
505
+ </DataRow>
506
+ </info>
507
+ ```
508
+
509
+ **回傳值:**
510
+
511
+ ```xml
512
+ <info>
513
+ <DataRow>
514
+ <Num>1</Num>
515
+ <success>Y</success>
516
+ <edelno>0000000001</edelno>
517
+ <epino>A00001</epino>
518
+ <erstno>4004</erstno>
519
+ <eqamt>10</eqamt>
520
+ <image>…</image>
521
+ <ErrMsg></ErrMsg>
522
+ </DataRow>
523
+ <DataRow>
524
+ <Num>2</Num>
525
+ <success>Y</success>
526
+ <edelno>0000000002</edelno>
527
+ <epino>A00002</epino>
528
+ <erstno>4004</erstno>
529
+ <eqamt>5</eqamt>
530
+ <image>…</image>
531
+ <ErrMsg></ErrMsg>
532
+ </DataRow>
533
+ </info>
534
+ ```
535
+
536
+ #### 圖片字串轉換 (C# 官方範例)
537
+
538
+ 回傳的 `image` 欄位為 **Hex 字串**,需轉換為 byte 後再轉成 Bitmap:
539
+
540
+ ```csharp
541
+ // 字串轉 byte
542
+ byte[] GetBytes(string HexString)
543
+ {
544
+ int byteLength = HexString.Length / 2;
545
+ byte[] bytes = new byte[byteLength];
546
+ string hex;
547
+ int j = 0;
548
+ for (int i = 0; i < bytes.Length; i++)
549
+ {
550
+ hex = new String(new Char[] { HexString[j], HexString[j + 1] });
551
+ bytes[i] = HexToByte(hex);
552
+ j = j + 2;
553
+ }
554
+ return bytes;
555
+ }
556
+
557
+ byte HexToByte(string hex)
558
+ {
559
+ if (hex.Length > 2 || hex.Length <= 0)
560
+ throw new ArgumentException("hex must be 1 or 2 characters in length");
561
+ return byte.Parse(hex, System.Globalization.NumberStyles.HexNumber);
562
+ }
563
+
564
+ // byte 轉成圖片 (1bit 黑白)
565
+ Bitmap image(byte[] b)
566
+ {
567
+ MemoryStream ms = new MemoryStream(b);
568
+ Bitmap bmp = (Bitmap)Bitmap.FromStream(ms);
569
+ BitmapData bmpData = bmp.LockBits(
570
+ new Rectangle(0, 0, bmp.Width, bmp.Height),
571
+ ImageLockMode.ReadOnly,
572
+ PixelFormat.Format1bppIndexed);
573
+ bmp = new Bitmap(bmp.Width, bmp.Height, bmpData.Stride,
574
+ PixelFormat.Format1bppIndexed, bmpData.Scan0);
575
+ return bmp;
576
+ }
577
+ ```
578
+
579
+ #### 設定檔注意事項 (官方提示)
580
+
581
+ ##### TransData (SOAP)
582
+
583
+ > 如果需要一次接收 2 張以上圖片,需要將 config 裡的
584
+ > `maxBufferSize="65536"` `maxReceivedMessageSize="65536"`
585
+ > **65536 的數字改成大一點**,因為 1 張圖片轉成 string 大約就 2 萬多。
586
+
587
+ ##### TransData_JSON
588
+
589
+ > 使用 JSON 接收圖檔字串,需要將 config 裡的
590
+ > `readerQuotas` `maxStringContentLength="8192"`
591
+ > **8192 數字改成大一點**,因為 1 張圖片轉成 string 大約就 2 萬多。
592
+
593
+ ##### 批次大小
594
+
595
+ > **PS:傳送一批資料請不要超過 30 筆,若使用回傳圖檔,一次上限為 5 筆。**
596
+
597
+ ---
598
+
599
+ ### UpdData — 修改重量
600
+
601
+ #### SOAP 方法簽章
602
+
603
+ ```csharp
604
+ DataSet UpdData(string Company, string password, DataSet data)
605
+ string UpdData_Json(string Company, string password, string json)
606
+ string UpdData_XML(string Company, string password, string xml)
607
+ ```
608
+
609
+ #### 傳入欄位
610
+
611
+ | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
612
+ |---------|---------|---------|------|
613
+ | `epino` | 訂單編號 | Char(30) | **必要欄位** |
614
+ | `edelno` | 新竹貨號 | Char(10) | **必要欄位** |
615
+ | `eqamt` | 重量 | Char(5) | **必要欄位** |
616
+
617
+ #### 回傳欄位
618
+
619
+ | 欄位名稱 | 欄位說明 |
620
+ |---------|---------|
621
+ | `Num` | 傳送序號 |
622
+ | `success` | 結果 (修改 `R` / 失敗 `N`) |
623
+ | `edelno` | 新竹貨號 |
624
+ | `epino` | 訂單編號 |
625
+ | `eqamt` | 重量 |
626
+ | `ErrMsg` | 異常錯誤訊息 |
627
+
628
+ ---
629
+
630
+ ### TransReport — 列印總表
631
+
632
+ 當日確認出貨時呼叫 (**18:00 前上傳**),產出**出貨總表 (一式二份)**,供現場交接貨件使用。
633
+
634
+ #### SOAP 方法簽章
635
+
636
+ ```csharp
637
+ DataSet TransReport(string Company, string password, DataSet dsCus)
638
+ string TransReport_Json(string Company, string password, string dsCusJson)
639
+ string TransReport_XML(string Company, string password, string dsCusXML)
640
+ ```
641
+
642
+ #### 傳入欄位
643
+
644
+ | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
645
+ |---------|---------|---------|------|
646
+ | `epino` | 訂單編號 | Char(30) | **必要欄位** |
647
+ | `edelno` | 新竹貨號 | Char(10) | **必要欄位** |
648
+
649
+ #### 回傳欄位
650
+
651
+ | 欄位名稱 | 欄位說明 |
652
+ |---------|---------|
653
+ | `Num` | 序號 |
654
+ | `success` | 結果 (成功 `Y` / 失敗 `N`) |
655
+ | `edelno` | 新竹貨號 |
656
+ | `epino` | 訂單編號 |
657
+ | `ErrMsg` | 異常錯誤訊息 |
658
+
659
+ #### XML 範例
660
+
661
+ **傳入值:**
662
+
663
+ ```xml
664
+ <info>
665
+ <DataRow>
666
+ <epino>A00001</epino>
667
+ <edelno>1234567890</edelno>
668
+ </DataRow>
669
+ <DataRow>
670
+ <epino>A00002</epino>
671
+ <edelno>1234567894</edelno>
672
+ </DataRow>
673
+ </info>
674
+ ```
675
+
676
+ **回傳值:**
677
+
678
+ ```xml
679
+ <info>
680
+ <DataRow>
681
+ <Num>1</Num>
682
+ <success>Y</success>
683
+ <edelno>0000000001</edelno>
684
+ <epino>A00001</epino>
685
+ <erstno>4004</erstno>
686
+ <eqamt>10</eqamt>
687
+ <ErrMsg></ErrMsg>
688
+ </DataRow>
689
+ <DataRow>
690
+ <Num>2</Num>
691
+ <success>Y</success>
692
+ <edelno>0000000002</edelno>
693
+ <epino>A00002</epino>
694
+ <erstno>4004</erstno>
695
+ <eqamt>5</eqamt>
696
+ <ErrMsg></ErrMsg>
697
+ </DataRow>
698
+ </info>
699
+ ```
700
+
701
+ #### JSON 範例
702
+
703
+ **傳入值:**
704
+
705
+ ```json
706
+ [
707
+ { "epino": "A00001", "edelno": "1234567890" },
708
+ { "epino": "A00002", "edelno": "1234567894" }
709
+ ]
710
+ ```
711
+
712
+ **回傳值:**
713
+
714
+ ```json
715
+ [
716
+ {
717
+ "Num": "1",
718
+ "success": "Y",
719
+ "edelno": "0000000001",
720
+ "epino": "A00001",
721
+ "erstno": "4004",
722
+ "eqamt": "10",
723
+ "ErrMsg": null
724
+ },
725
+ {
726
+ "Num": "2",
727
+ "success": "Y",
728
+ "edelno": "0000000002",
729
+ "epino": "A00002",
730
+ "erstno": "4004",
731
+ "eqamt": "5",
732
+ "ErrMsg": null
733
+ }
734
+ ]
735
+ ```
736
+
737
+ ---
738
+
739
+ ### QueryEDELNO — 查詢貨號
740
+
741
+ 由**訂單編號**反查已配發的**新竹貨號**。
742
+
743
+ #### SOAP 方法簽章
744
+
745
+ ```csharp
746
+ DataSet QueryEDELNO(string company, string password, DataSet data)
747
+ string QueryEDELNO_Json(string company, string password, string json)
748
+ string QueryEDELNO_Xml(string company, string password, string xml)
749
+ ```
750
+
751
+ #### 輸入規則
752
+
753
+ > `data` / `json` / `xml`:欲查詢貨號的訂單編號 (多筆可用 **`,` 逗號分隔**,**訂單編號中不能有逗號**)
754
+
755
+ 範例輸入:`P002,S444` 或 `A001,P003,S444,P001`
756
+
757
+ #### 回傳欄位
758
+
759
+ | 欄位名稱 | 型別 | 欄位說明 |
760
+ |---------|------|---------|
761
+ | `success` | String | 結果 (成功 `Y` / 失敗 `N`) |
762
+ | `edelno` | String | 新竹貨號 |
763
+ | `epino` | String | 訂單編號 |
764
+ | `ErrMsg` | String | 異常錯誤訊息 |
765
+
766
+ #### JSON 回傳範例
767
+
768
+ 傳入 `epino` 值為 `"P002,S444"`:
769
+
770
+ ```json
771
+ [
772
+ {
773
+ "success": "Y",
774
+ "edelno": "2000001054",
775
+ "epino": "P002",
776
+ "ErrMsg": ""
777
+ },
778
+ {
779
+ "success": "N",
780
+ "edelno": "",
781
+ "epino": "S444",
782
+ "ErrMsg": "查無資料"
783
+ }
784
+ ]
785
+ ```
786
+
787
+ #### XML 回傳範例
788
+
789
+ 傳入 `epino` 值為 `"A001,P003,S444,P001"`:
790
+
791
+ ```xml
792
+ <info>
793
+ <DataRow>
794
+ <success>Y</success>
795
+ <edelno>2000001080</edelno>
796
+ <epino>A001</epino>
797
+ <ErrMsg></ErrMsg>
798
+ </DataRow>
799
+ <DataRow>
800
+ <success>Y</success>
801
+ <edelno>2000001065</edelno>
802
+ <epino>P003</epino>
803
+ <ErrMsg></ErrMsg>
804
+ </DataRow>
805
+ <DataRow>
806
+ <success>N</success>
807
+ <edelno></edelno>
808
+ <epino>S444</epino>
809
+ <ErrMsg>查無資料</ErrMsg>
810
+ </DataRow>
811
+ <DataRow>
812
+ <success>Y</success>
813
+ <edelno>2000001091</edelno>
814
+ <epino>P001</epino>
815
+ <ErrMsg></ErrMsg>
816
+ </DataRow>
817
+ </info>
818
+ ```
819
+
820
+ ---
821
+
822
+ ### R_TransData — 逆物流託運資料
823
+
824
+ 逆物流 (退貨/取件) 上傳資料。**目前僅提供 JSON 格式**。
825
+
826
+ #### SOAP 方法簽章
827
+
828
+ ```csharp
829
+ string R_TransData_Json(string Company, string password, string json)
830
+ ```
831
+
832
+ #### 傳入欄位
833
+
834
+ | 欄位名稱 | 欄位說明 | 欄位長度 | 備註 |
835
+ |---------|---------|---------|------|
836
+ | `epino` | 訂單編號 | Char(30) | **必要欄位**,**不可重複** |
837
+ | `ercsig` | 退貨人名稱 | Char(40) | **必要欄位**,逆物流跟誰收 |
838
+ | `ertel1` | 退貨人電話 1 | Char(15) | **必要欄位**,逆物流跟誰收的電話 |
839
+ | `ertel2` | 退貨人電話 2 | Char(15) | |
840
+ | `eraddr` | 退貨人地址 | Char(100) | **必要欄位**,逆物流跟誰收的地址 |
841
+ | `ejamt` | 件數 | Char(4) | **必要欄位** (總長運費的件數**只能輸入 1**) |
842
+ | `eqamt` | 重量 | Char(5) | 總長重量只能 `60` / `90` / `120` / `150` / `151~999` (如無提供抓系統預設值) |
843
+ | `esdate` | 出貨日期 | Char(8) | 預設今天 (`YYYYMMDD`) |
844
+ | `escsno` | 客代 | Char(11) | 預設值 |
845
+ | `edelno` | 新竹貨號 | Char(10) | 預設值 (如無提供系統自行配號) |
846
+ | `etcsig` | 收貨人名稱 | Char(40) | 預設值 |
847
+ | `ettel1` | 收貨人電話 1 | Char(15) | 預設值 |
848
+ | `etaddr` | 收貨地址 | Char(100) | 預設值 |
849
+ | `emark` | 備註 | Char(100) | |
850
+ | `eprdcl2` | 商品種類 | Char(3) | 一般 `001` (預設) / 冷凍 `003` / 冷藏 `008` |
851
+ | `edelno2` | **原查貨號碼** | Char(10) | **原正物流出貨查貨號碼** |
852
+
853
+ #### 回傳欄位
854
+
855
+ | 欄位名稱 | 欄位說明 |
856
+ |---------|---------|
857
+ | `Num` | 傳送序號 |
858
+ | `success` | 結果 (新增 `Y` / 失敗 `N`) |
859
+ | `edelno` | 新竹查貨貨號 |
860
+ | `epino` | 訂單編號 |
861
+ | `erstno` | 退貨人到著站號碼 (逆物流跟誰收的站所代號) |
862
+ | `eqamt` | 重量 |
863
+ | `ErrMsg` | 異常錯誤訊息 |
864
+
865
+ #### JSON 範例
866
+
867
+ **傳入值:**
868
+
869
+ ```json
870
+ [
871
+ {
872
+ "epino": "101000000012345",
873
+ "ercsig": "張三",
874
+ "ertel1": "0255927298",
875
+ "ertel2": "",
876
+ "eraddr": "台北市士林區中山北路六段 88 號",
877
+ "ejamt": "1",
878
+ "eqamt": "60",
879
+ "esdate": "",
880
+ "escsno": "12345678900",
881
+ "edelno": "",
882
+ "etcsig": "大大消防",
883
+ "ettel1": "0911123456",
884
+ "ettel2": "",
885
+ "etaddr": "台中市大雅區中清路三段 513 號",
886
+ "emark": "",
887
+ "eprdcl2": "001",
888
+ "edelno2": "8812213345"
889
+ },
890
+ {
891
+ "epino": "101000000012346",
892
+ "ercsig": "李四",
893
+ "ertel1": "035218811",
894
+ "ertel2": "",
895
+ "eraddr": "新竹縣新豐鄉建興路 100 號",
896
+ "ejamt": "1",
897
+ "eqamt": "",
898
+ "esdate": "",
899
+ "escsno": "12345678900",
900
+ "edelno": "",
901
+ "etcsig": "大大消防",
902
+ "ettel1": "0911123456",
903
+ "ettel2": "",
904
+ "etaddr": "台中市大雅區中清路三段 513 號",
905
+ "emark": "",
906
+ "eprdcl2": "001"
907
+ }
908
+ ]
909
+ ```
910
+
911
+ **回傳值:**
912
+
913
+ ```json
914
+ [
915
+ {
916
+ "Num": "1",
917
+ "Success": "N",
918
+ "Edelno": "",
919
+ "Epino": "101000000012345",
920
+ "Erstno": "1247",
921
+ "Eqamt": "60",
922
+ "ErrMsg": "原貨號檢查碼錯誤"
923
+ },
924
+ {
925
+ "Num": "2",
926
+ "Success": "Y",
927
+ "Edelno": "2250446752",
928
+ "Epino": "101000000012346",
929
+ "Erstno": "2060",
930
+ "Eqamt": "9",
931
+ "ErrMsg": ""
932
+ }
933
+ ]
934
+ ```
935
+
936
+ ---
937
+
938
+ ## 錯誤原因明細
939
+
940
+ ### TransData 錯誤訊息
941
+
942
+ | 錯誤訊息 | 錯誤原因 |
943
+ |---------|---------|
944
+ | 公司名稱或密碼錯誤 | Company / password 驗證失敗 |
945
+ | 貨號重複 | 一個月內貨號重複 |
946
+ | 貨號錯誤 | 沒新竹貨號 or 新竹貨號沒有 10 碼 |
947
+ | 貨號檢查碼錯誤 | 貨號最後一碼規則 |
948
+ | 訂單編號錯誤 | 訂單編號空白 |
949
+ | 客代錯誤 | 客代沒有 11 碼 |
950
+ | 件數錯誤 | 件數 0 |
951
+ | 重量錯誤 | 重量 0 |
952
+ | 收貨人名稱錯誤 | 收貨人空白 |
953
+ | 收貨人電話錯誤 | 收貨人電話空白 |
954
+ | 收貨人地址錯誤 | 收貨人地址空白 |
955
+ | 出貨站錯誤 | 出貨站沒有 4 碼 |
956
+ | 代收貨款錯誤 | TYPE = 41 但是沒有代收 |
957
+ | 一個月內貨號重複 | 同一貨號 30 天內重複 |
958
+ | 訂單編號重複 | 同一 ESDATE 內訂單編號重複 |
959
+
960
+ ### UpdData 錯誤訊息
961
+
962
+ | 錯誤訊息 | 錯誤原因 |
963
+ |---------|---------|
964
+ | 公司名稱或密碼錯誤 | 帳密失敗 |
965
+ | 重量錯誤 | 重量 0 或非法 |
966
+ | 查無貨號和訂單編號 | 找不到對應託運單 |
967
+
968
+ ### TransReport 錯誤訊息
969
+
970
+ | 錯誤訊息 | 錯誤原因 |
971
+ |---------|---------|
972
+ | 查無貨號 | DB 沒貨號 |
973
+ | 已經上傳過此筆 | `ISMASTER = 1` (已上傳過總表) |
974
+
975
+ ### R_TransData_Json 錯誤訊息
976
+
977
+ | 錯誤訊息 | 錯誤原因 |
978
+ |---------|---------|
979
+ | 貨號重複 | 三個月內貨號重複 |
980
+ | 貨號錯誤 | 貨號格式錯誤 |
981
+ | 貨號檢查碼錯誤 | 貨號最後一碼規則錯誤 |
982
+ | 貨號錯誤必須是 2 開頭 | 逆物流貨號需以 `2` 開頭 |
983
+ | 原貨號錯誤 | `edelno2` 原查貨號碼錯誤 |
984
+ | 訂單編號錯誤 | 訂單編號空白 |
985
+ | 客代錯誤 | 客代格式錯誤 |
986
+ | 件數錯誤 | 件數非法 |
987
+ | 重量錯誤 | 重量非法 |
988
+ | 退貨人名稱錯誤 | 退貨人空白 |
989
+ | 退貨人電話錯誤 | 退貨人電話空白 |
990
+ | 退貨人地址錯誤 | 退貨人地址空白 |
991
+ | 退貨站錯誤 | 退貨站代號錯誤 |
992
+ | 收貨人名稱錯誤 | 收貨人空白 |
993
+ | 收貨人電話錯誤 | 收貨人電話空白 |
994
+ | 收貨人地址錯誤 | 收貨人地址空白 |
995
+ | 收貨站錯誤 | 收貨站代號錯誤 |
996
+ | 總長請輸入重量 60、90、120、150、151~999 | 逆物流總長重量不在允許值內 |
997
+ | 總長件數只能為 1 件 | 逆物流件數限制 |
998
+ | 未建收退貨貨號區間 | HCT 端尚未建立逆物流貨號區間 |
999
+ | 三個月內貨號重複 | 逆物流貨號 90 天唯一 |
1000
+ | 訂單編號重複 | 訂單編號於系統內已存在 |
1001
+
1002
+ ---
1003
+
1004
+ ## 整合最佳實務
1005
+
1006
+ ### 1. 帳密與金鑰管理
1007
+
1008
+ - `Company` / `password` 與加解密金鑰請統一存放於後端 secrets 管理 (Vault / KMS / 環境變數)
1009
+ - 切勿將測試帳號 `test/test1` 上線
1010
+ - 加解密金鑰版本 `v` 視為設定,避免硬編碼
1011
+
1012
+ ### 2. 託運單建立流程
1013
+
1014
+ ```
1015
+ 1. 建立訂單 → 預先保留訂單編號 (epino)
1016
+ 2. 出貨日 → 呼叫 TransData 上傳託運資料
1017
+ 3. 取得回應 → 儲存 edelno (新竹貨號)、erstno (到著站)、image (標籤)
1018
+ 4. 列印標籤 → 將 image Hex 字串轉 Bitmap 印出
1019
+ 5. 18:00 前 → 呼叫 TransReport 確認當日出貨 (重要!)
1020
+ 6. 列印總表一式二份 → 現場交接貨件使用
1021
+ ```
1022
+
1023
+ > **TransReport 必呼叫**:未呼叫 TransReport 即視為**未確認出貨**,HCT 不會排車收件。
1024
+
1025
+ ### 3. 重量更新時機
1026
+
1027
+ 當實際過磅重量與預估不同時,**在 TransReport 之前**呼叫 `UpdData` 修改重量;TransReport 後重量即固化。
1028
+
1029
+ ### 4. 貨況查詢策略
1030
+
1031
+ | 場景 | 建議 API |
1032
+ |------|---------|
1033
+ | 客戶端「查詢貨況」按鈕 | 網頁串接模式 (URL 嵌入) |
1034
+ | 後端排程同步多筆貨況 | XML 多筆查詢 (每次 ≤ 100 筆) |
1035
+ | 訂單列表顯示「目前狀態」 | XML 多筆查詢 + 內部狀態映射 |
1036
+
1037
+ > 貨況僅保留 30 天,請於後端 DB 持久化關鍵狀態 (集貨 / 配達 / 異常)。
1038
+
1039
+ ### 5. 批次大小
1040
+
1041
+ | API | 批次上限 |
1042
+ |-----|---------|
1043
+ | TransData (純資料) | 30 筆 / 批 |
1044
+ | TransData (含 image 回傳) | **5 筆 / 批** |
1045
+ | 多筆貨號 XML 查詢 | 100 筆 / 批 |
1046
+
1047
+ ### 6. 重複保護
1048
+
1049
+ | 鍵 | 重複窗口 |
1050
+ |---|---------|
1051
+ | `epino` (訂單編號) | 同一 `esdate` 內唯一 |
1052
+ | `edelno` (新竹貨號) | 100 天唯一 |
1053
+ | 逆物流 `edelno` | 90 天唯一 (錯誤訊息為「三個月內貨號重複」) |
1054
+
1055
+ ### 7. 重試策略
1056
+
1057
+ - HCT 系統每日 **03:40 - 04:30** 維護,建議排程避開此時段
1058
+ - 對暫時性 5xx 錯誤可重試 (建議指數退避,最多 3 次)
1059
+ - 對「貨號重複」「貨號檢查碼錯誤」等業務型錯誤**不可盲目重試**,需人工檢核
1060
+
1061
+ ### 8. 跨語言實作建議
1062
+
1063
+ 由於官方僅提供 .NET / C# Sample (`DataSet` 為 .NET 特有型別),建議:
1064
+
1065
+ - **Java / Kotlin / Go / Python / Node.js**:直接使用 `*_Json` / `*_XML` 變體方法,避免處理 .NET DataSet 序列化
1066
+ - **PHP**:可用 SOAP Extension 或直接 HTTP POST 至 `?wsdl` 端點
1067
+ - **WSDL 取得**:`https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx?wsdl`
1068
+
1069
+ ---
1070
+
1071
+ ## aggregator vs 直連對照
1072
+
1073
+ | 構面 | 透過 aggregator (ECPay/PayNow/SmilePay) | 直連 HCT API |
1074
+ |------|----------------------------------------|-------------|
1075
+ | **申請門檻** | 低 (註冊網路會員即可) | 中高 (需與營業所簽約) |
1076
+ | **適合規模** | 個人/中小型電商 | 中大型企業 / ERP 整合 |
1077
+ | **費率** | aggregator 抽成 + 物流費 | 直接費率 (依量級議價) |
1078
+ | **物流業者切換** | 改 `LogisticsSubType` 即可 | 僅限 HCT |
1079
+ | **託運單編號** | aggregator 包裝後的 ID | 原生新竹貨號 (10 碼) |
1080
+ | **貨況同步** | aggregator webhook | 自行排程查詢 (XML 多筆) |
1081
+ | **逆物流** | 透過 aggregator 建立 | `R_TransData` 直接送 HCT |
1082
+ | **代碼對照** | `LogisticsSubType=TCAT` (黑貓) / `HCT` (新竹) | 不適用,直接是 HCT 系統 |
1083
+ | **WSDL / SOAP** | 由 aggregator 抽象掉 | 需自行處理 SOAP / JSON / XML |
1084
+
1085
+ > 提醒:在 ECPay 物流文件中常出現的 `LogisticsSubType=TCAT` 是「黑貓宅急便」,並非新竹物流;新竹物流在 aggregator 中通常以獨立的子類型代碼表示,請以該 aggregator 文件為準。
1086
+
1087
+ ---
1088
+
1089
+ ## 官方資源
1090
+
1091
+ - **官方網站**:https://www.hct.com.tw/
1092
+ - **API 端點 (查貨)**:https://hctapiweb.hct.com.tw/phone/searchGoods_Main.aspx
1093
+ - **API 端點 (查貨 XML)**:https://hctapiweb.hct.com.tw/phone/searchGoods_Main_Xml.ashx
1094
+ - **API 端點 (出貨 SOAP)**:https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx
1095
+ - **WSDL**:https://Hctrt.hct.com.tw/EDI_WebService2/Service1.asmx?wsdl
1096
+ - **技術窗口**:02-2837-1122 #5123 (許先生)
1097
+ - **官方文件**:申請後由 HCT 站所電腦負責人提供 PDF (`API服務說明_V1.pdf`,27 頁)
1098
+ - **加密 Sample Code**:申請後由 HCT 提供 (C# 版本)
1099
+
1100
+ ---
1101
+
1102
+ 最後更新:2026/05/07