# 雲端發票加值中心 DLL 規格書

文件版本：1.1.8　｜　更新日期：2026-10-22　｜　對應 DLL：1.5.1.8

## 系統需求

- Windows XP SP3 以上版本
- .Net Framework 4.0 以上版本

## 介接程式語言

- Visual Basic 6.0 (Net Dll)
- Visual Basic .Net (Net Dll)
- Delphi 6.0 以上(ActiveX)
- C#.Net (Net Dll)

## DLL 版本資訊

| 文件 | Dll | 修正記錄 |
| --- | --- | --- |
| 1.0.0 | 1.2.0.0 | 初版 |
| 1.0.2 | 1.2.0.2 | 修改 addInvoiceDetail<br>Add queryInvoiceQueueNonUpload |
| 1.0.3 | 1.2.0.3 | Add getnowPeriodTrack<br>Add queryNextTrackNo<br>Add printDetailON<br>Add printDetailOFF<br>Add setPrinterInvoiceHeader_FooterWord<br>新增 Activex 元件版本與支援函式庫表 說明 |
| 1.0.4 | 1.2.0.5 | Add toHandleInvoiceSync |
| 1.0.5 | 1.2.0.9 | Add PrintInvoiceON<br>Add PrintInvoiceOFF<br>Add onlyPrintInvoice<br>Add supplyPrinterInvoice |
| 1.0.6 | 1.2.1.1 | Add openSendB2B<br>Add closeSendB2B |
| 1.0.7 | 1.3.6.5 |  |
| 1.0.8 | 1.3.7.5 | 增加使用範例 |
| 1.0.9 | 1.3.8.1 | 增加註銷發票 |
| 1.1.0 | 1.3.8.7 | 增加查詢發票狀態 |
| 1.1.1 | 1.3.9.5 | 增加印表機開啟<br>增加印表機關閉<br>增加印表機重設格式<br>增加列印文字大小調整<br>增加印表機文字對齊位置<br>增加印表機文字列印<br>增加印表機行距設定<br>增加印表機換行<br>增加印表機裁切 |
| 1.1.2 | 1.4.0.0 | 增加印表機狀態判斷 |
| 1.1.3 | 1.4.1.2 | 調整addInvoiceHeader參數<br>增加載具隱碼及交換開立 |
| 1.1.4 | 1.4.2.1 | 調整addInvoiceHeader參數，增加保留欄位<br>調整startPrinterServir支援印表機型號TP809 |
| 1.1.5 | 1.4.2.8 | 增加取得未上傳發票數量<br>增加發票上傳 |
| 1.1.6 | 1.4.5.5 | 31.openSendB2B 增加回傳資訊 |
| 1.1.7 | 1.4.5.6 | 9.getTrackNo 增加參數設定 |
| 1.1.8 | 1.5.0.1 | 11.addInvoiceHeader 增加參數設定 |

## Activex 元件 版本與支援函式庫表

COM ProgID：`ECloud.EcloudPOSDll`

| SN | Function | Description |
| --- | --- | --- |
| 1 | activexGateWay | 中介 |

目前支援函式

| SN | Function | Description |
| --- | --- | --- |
| 1 | setPrinterInvoiceHeader_FooterWord | 設定發票下方提示文字 |

### 1. activexGateWay

函式簽名：

```csharp
String activexGateWay(String funName, String parameter);
```

參數：funName 為函式名稱；parameter 使用 `p1=Value1,p2=Value2` 格式。值請避免包含逗號或等號。目前 gateway 僅轉接 setPrinterInvoiceHeader_FooterWord，使用 printword 欄位。

範列：

activexGateWay("setPrinterInvoiceHeader_FooterWord","printword=退貨憑電子發票

證明聯正本辨理")

## DLL 函式庫表

| SN | Function | Description |
| --- | --- | --- |
| 1 | getDllVersion | 版本資訊 |
| 2 | initEcloud | 初始化資料存放目錄 |
| 3 | setInformation | 使用 API Key 與 Secret Key 設定平台連線 |
| 4 | setSalesInformation | 設定營業人資訊 |
| 5 | setProfile | 設定營業人基本資料 |
| 6 | startService | DLL 啟動服務 |
| 7 | setTrackInformation | 字軌設定 |
| 8 | startTrackService | 啟動字軌服務 |
| 9 | getTrackNo | 取字軌號碼 |
| 10 | startPrinterService | 啟動印表機服務 |
| 11 | addInvoiceHeader | 發票主體 |
| 12 | addInvoiceDetail | 發票明細 |
| 13 | toHandleInvoice | 處理發票 |
| 14 | cancelInvoice | 作廢發票 |
| 15 | rePrinterInvoice | 重新列印發票 |
| 16 | queryInvoice | 查詢發票狀態 |
| 17 | stopServiceAll | 停止 DLL 服務 |
| 18 | queryInvoiceQueueNonUpload | 查詢 Queue發票 |
| 19 | getnowPeriodTrack | 手動強制執行取當期字軌 |
| 20 | queryNextTrackNo | 查詢下一張發票號碼 |
| 21 | printDetailON | 列印明細 |
| 22 | printDetailOFF | 關閉列印明細 |
| 23 | setPrinterInvoiceHeader_FooterWord | 設定發票下方提示文字 |
| 24 | toHandleInvoiceSync | 開立立即上傳，必須等待 Server 回應 |
| 25 | addallowancesTitle | 開立折讓主體 |
| 26 | addallowancesItem | 開立折讓明細 |
| 27 | PrintInvoiceON | 開啟列印發票 |
| 28 | PrintInvoiceOFF | 關閉列印發票 |
| 29 | onlyPrintInvoice | 僅列印發票 |
| 30 | supplyPrinterInvoice | 補印發票 |
| 31 | openSendB2B | 客戶申請 B2B 存證傳送 |
| 32 | closeSendB2B | 關閉 B2B 傳送(預設) |
| 33 | writeOffInvoice | 註銷發票 |
| 34 | GetInvoiceStatusWithDate | 取得發票狀態 |
| 35 | openPrinter | 開啟印表機 |
| 36 | closePrinter | 關閉印表機 |
| 37 | resetPrinterFormat | 重置印表機 |
| 38 | printerSetChineseFontStyle | 設定列印文字大小 |
| 39 | printerSetJustification | 設定列印對齊方式 |
| 40 | printerPrintString | 列印文字 |
| 41 | printerNewLine | 印表機換行 |
| 42 | printerSetLineSpacing | 設定印表機行距 |
| 43 | printerCut | 印表機裁剪 |
| 44 | checkPaperStatus | 確認印表機及紙量狀況 |
| 45 | toOnlyUploadInvoice | 發票上傳 |
| 46 | GetWaitUploadInvoiceCount | 取得未上傳發票數量 |

## 共同回傳欄位

除個別函式另有說明外，JSON 回傳的欄位如下。String 是 .NET 字串；JSON 字串欄位中的內容需要再解析一次。回傳型別為 int、Boolean、void 或純字串的函式，請依各函式簽名處理。

| 欄位 | 型別 | 說明 |
| --- | --- | --- |
| rtCode | String | 結果代碼；0000 表示成功，非 0000 請檢查 rtMessage |
| rtMessage | String | 結果或錯誤說明，預設空字串 |
| rtOtherMessage | String | 補充訊息，預設空字串 |
| rtData | String | 依函式提供資料，可能為空字串、數字字串、逗號分隔字串或 JSON 字串 |
| rtInvoice | String | queryInvoice 的發票物件 JSON 字串；成功時解析此字串取得發票內容 |
| rtState | String | queryInvoice 的本機處理狀態，不等同平台發票狀態 |
| rtInvoiceArray | String | queryInvoiceQueueNonUpload 的識別資料陣列 JSON 字串；元素含 InvoiceNumber、TrackYear、TrackPeriod |

請先完成 initEcloud、連線設定、setSalesInformation 與 startService，再啟動字軌或印表機服務。void 不提供結果碼；有回傳值時應先檢查結果，勿只以沒有拋出例外判定成功。平台查詢可能回傳 null，需先判斷再解析。

## DLL 錯誤代碼表

| rtCode | Description |
| --- | --- |
| 0000 | 成功 |
| 0001 | DLL Service 錯誤 |
| 0002 | 印表機服務錯誤 |
| 1001 | 參數錯誤 |
| 1002 | 檔案系統錯誤 |
| 1003 | 發票資料錯誤 |
| 1004 | 抓取字軌錯誤 |
| 1005 | 資料庫錯誤 |
| 2000 | 找不到印表機 |
| 2001 | 印表機錯誤，發票正常開立 |
| 2002 | 印表機未設定 |
| 2003 | 列印錯誤 |
| 2004 | 印表機缺紙 |
| 3001 | 發票資訊不存在 |
| 4001 | 作廢失敗 |
| 4002 | 作廢狀態錯誤 |
| 4003 | 作廢發票目前不可作廢 |
| 4004 | 發票號碼註銷中 |
| 5001 | 刪除資料夾失敗 |
| 6001 | ActiveX 參數錯誤 |
| 7000 | 上傳資料有錯誤 |
| 7001 | 上傳資料參數錯誤 |
| 7002 | Server 回傳錯誤 |
| 7003 | BadRequest Error |
| 7004 | NetWork Error |
| 0003 | 字軌為使用者配號模式 |
| 0004 | 帳號停權、逾期或未開通 B2B |
| 2005 | 已關閉發票列印 |
| 2006 | 印表機未開啟 |
| 2007 | 印表機已開啟 |
| 9999 | 網路錯誤 |

## DLL 函式庫使用說明

### 1. getDllVersion

函式簽名：

```csharp
String getDllVersion();
```

功能說明：版本資訊

參數：無

回傳：

String：DLL 檔案版本，例如 1.5.1.8

### 2. initEcloud

函式簽名：

```csharp
void initEcloud(String configPath);
```

功能說明：初始DLL資料使用目錄，包含發票字軌，發票資訊。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | configPath | 資料儲存目錄 | String |  |

回傳：無

### 3. setInformation

函式簽名：

```csharp
public int setInformation(String environment, String incId, String apiKey, String secretKey, String posId);
```

功能說明：使用 API Key 與 Secret Key 設定平台連線資訊，請於 startService 之前呼叫。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | environment | 連線環境 | String | Release 使用正式環境；其他值使用測試環境，建議填 Test |
| 2 | incId | 商家代號 | String | 使用平台提供的商家代號 |
| 3 | apiKey | 平台 API Key | String | 使用平台核發的 API Key |
| 4 | secretKey | 平台 Secret Key | String | 使用平台核發的 Secret Key |
| 5 | posId | 平台機號 | String | 使用平台提供的機號 |

回傳：Int32，設定完成回傳 `0`。此回傳值表示完成本機設定；連線授權結果仍需依後續服務回應判斷。

### 4. setSalesInformation

函式簽名：

```csharp
int setSalesInformation(String store_ID, String sellerID, String bussinessID, String aes_key, String private_aes_key = "", String taxType = "1");
```

功能說明：設定賣方資訊

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | store_ID | 統一編號 | String |  |
| 2 | sellerID | 銷售店統一編號 | String |  |
| 3 | bussinessID | 總公司統一編號 | String |  |
| 4 | aes_key | 平台 AES_KEY | String |  |
| 5 | private_aes_key | 私有 AES 金鑰 | String | 選填；預設 `""` |
| 6 | taxType | 營業人課稅類型 | String | 選填；預設 `"1"` |

回傳：Int32，設定完成回傳 `0`。

### 5. setProfile

函式簽名：

```csharp
void setProfile(String storeName, String storeAddress, String storephoneNumber);
```

功能說明：營業人相關資訊店名、地址

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | storeName | 店家名稱 | String |  |
| 2 | storeAddress | 地址 | String |  |
| 3 | storephoneNumber | 電話 | String |  |

回傳：無

### 6. startService

函式簽名：

```csharp
String startService();
```

功能說明：啟動Dll服務

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 7. setTrackInformation

函式簽名：

```csharp
String setTrackInformation(int oncPullSize, int lowWaterlevel, int day);
```

功能說明：設定字軌服務參數

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | oncPullSize | 一次抓取字軌量 | int |  |
| 2 | lowWaterlevel | 最低字軌庫存量 | int |  |
| 3 | day | 抓取下一期字軌起始日 | int | 1-30 |

回傳：JSON 字串，欄位見「共同回傳欄位」。

### 8. startTrackService

函式簽名：

```csharp
String startTrackService();
```

功能說明：啟動字軌服務。

參數：無

回傳：JSON 字串，欄位見「共同回傳欄位」。

### 9. getTrackNo

函式簽名：

```csharp
String getTrackNo(String year, String period, String type = "07");
```

功能說明：讀取指定年份、期別與發票種類的字軌號碼。year 與 period 為必填，type 預設為 07。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | year | 字軌西元年份 | String | "^(20)[0-9][0-9]$"<br>Ex:2015 |
| 2 | period | 字軌期別，0–5 分別代表 1–2 月至 11–12 月 | String | "^[0-5]{1}$"<br>Ex:0 |
| 3 | type | 發票種類代碼；預設 07 | String | 選填；預設 `"07"` |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtUseYear": "2015",
  "rtUsePeriod": "0",
  "rtTrackNo": "TT10000014",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtUseYear:發票使用年份

rtUsePeriod:發票使用期別

rtTrackNo:發票號碼

### 10. startPrinterService

函式簽名：

```csharp
String startPrinterService(String printName, String port, String baudrate, String logopath, Boolean is_NocheckPrinter, String Footer, Boolean cutInvoiceDetail, Boolean printItemId, Boolean printPayMethod, Boolean printInvoiceNumber);
```

功能說明：設定印表機資訊。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | printName | 設定印表機名稱 | String |  |
| 2 | port | 印表機連接 Port | String |  |
| 3 | baudrate | 印表機鮑率 | String |  |
| 4 | logopath | 列印 LOGO 圖案 | String |  |
| 5 | is_NocheckPrinter | 是否略過印表機啟動檢查；true 略過、false 檢查連線及紙量 | Boolean | 必填 |
| 6 | Footer | 證明聯下方文字設定 | String | 必填；證明聯下方文字 |
| 7 | cutInvoiceDetail | 是否將發票明細分開裁切 | Boolean |  |
| 8 | printItemId | 是否列印商品代號 | Boolean |  |
| 9 | printPayMethod | 是否列印付款方式 | Boolean |  |
| 10 | printInvoiceNumber | 是否列印發票號碼 | Boolean |  |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 11. addInvoiceHeader

函式簽名：

```csharp
String addInvoiceHeader(String trackYear, String trackPeriod, String invoiceNumber, String invoiceDate, String invoiceTime, String invoicePrinterDatetime, String printTaxFormat, String buyerIdentifier, String buyerName, String buyerAddress, String buyerEmail, String buyerTel, String salesAmount, String freeTaxSalesAmount, String zeroTaxSalesAmount, String taxTypeEnum, String taxAmount, String totalAmount, String carrierType, String carrierString1, String carrierString2, String printMark, String randomNumber, String npoBan, String taxRate, String payMethod, String extraData, String memberCarrierIdentifier, String memberCarrierIncId, String transactionData, String customsClearanceMark, String mainRemark, String invoiceFootString, String isExchange, String zeroTaxRateReason);
```

功能說明：建立發票主體，供後續新增明細與開立使用。

參數：

| SN | Parameters | Description | Type | Restrictions                              |
| --- | --- | --- | --- |-------------------------------------------|
| 1 | trackYear | 字軌年分 | String | "^(20)[0-9][0-9]$"<br>Ex:2015             |
| 2 | trackPeriod | 字軌期別 | String | "^[0-5]{1}$"<br>Ex:0                      |
| 3 | invoiceNumber | 發票號碼 | String | "^[A-Z]{2}[0-9]{8}$<br>"<br>Ex:AA10000001 |
| 4 | invoiceDate | 發票日期 | String | yyyyMMdd                                  |
| 5 | invoiceTime | 開立發票時間 | String | HHmmss                                    |
| 6 | invoicePrinterDatetime | 列印時間 | String | Ex:2014-01-01<br>15:00:05                 |
| 7 | printTaxFormat | 税率列印格式 | String | Ex:25                                     |
| 8 | buyerIdentifier | 買方統編 | String | Ex:53567686                               |
| 9 | buyerName | 買方名字 | String | 最多 60 字元                                  |
| 10 | buyerAddress | 買方地址 | String | 最多 100 字元                                 |
| 11 | buyerEmail | 買方電子郵件 | String | 可空白；最多 80 字元，非空白時須符合電子郵件格式                |
| 12 | buyerTel | 買方手機 | String | 可空白；非空白時為 09 開頭的 10 碼手機，+886 會轉為 0        |
| 13 | salesAmount | 應税銷售額合計 | String | 非負整數字串，不可空白                               |
| 14 | freeTaxSalesAmount | 免税銷售額合計 | String | 非負整數字串，不可空白                               |
| 15 | zeroTaxSalesAmount | 零税率銷售額合計 | String | 非負整數字串，不可空白                               |
| 16 | taxTypeEnum | 課税別<br>1:應税<br>2:零税率<br>3:免税<br>4:應税(特種税率)<br>9:混合應税：免税或零税率(限收<br>銀機發票無法分辨時使用) | String | "^[12349]{1}$"<br>Ex:1                    |
| 17 | taxAmount | 税額 | String | 非負整數字串，不可空白                               |
| 18 | totalAmount | 總金額 | String | 非負整數字串；等於三類銷售額加稅額                         |
| 19 | carrierType | 載具類別號碼<br>"CQ0001"自然憑證<br>"3J0002"手機載具 | String |                                           |
| 20 | carrierString1 | 載具顯碼 | String | 最多 64 字元；手機條碼與自然人憑證需符合對應格式                |
| 21 | carrierString2 | 載具隱碼 | String | 最多 64 字元                                  |
| 22 | printMark | 是否列印紙張 | String | Y 或 N；須符合載具、捐贈與 B2B 交換的列印條件               |
| 23 | randomNumber | 隨機碼 | String | 4 碼，每碼為 A 或 0–9                           |
| 24 | npoBan | 愛心碼 | String |                                           |
| 25 | taxRate | 税率 | String | "^\\\\d+(\\\\.\\\\d+)?$"<br>Ex:0.05       |
| 26 | payMethod | 付款方式 | String |                                           |
| 27 | extraData | 其它資訊 | String |                                           |
| 28 | memberCarrierIdentifier | 會員載具載具編號 | String |                                           |
| 29 | memberCarrierIncId | 會員載具店家統編 | String |                                           |
| 30 | transactionData | 交易資訊 | String |                                           |
| 31 | customsClearanceMark | 通關註記 | String | 1非經海關出口<br>2經海關出口                         |
| 32 | mainRemark | 總備註 | String | 最多 200 字元                                 |
| 33 | invoiceFootString | 證明聯下方文字 | String | BIG5 編碼長度最多 32 bytes；空白時使用印表機設定           |
| 34 | isExchange | B2B交換 | String | True 或 false                              |
| 35 | zeroTaxRateReason | 零稅率原因<br>71:外銷貨物。<br>72:與外銷有關之勞務，或在國內提<br>供而在國外使用之勞務。<br>73:依法設立之免稅商店銷售與過境<br>或出境旅客之貨物。<br>74:銷售與保稅區營業人供營運之貨<br>物或勞務。<br>75:國際間之運輸。但外國運輸事業<br>在中華民國境內經營國際運輸業務者<br>，應以各該國對中華民國國際運輸事<br>業予以相等待遇或免徵類似稅捐者為<br>限。<br>76:國際運輸用之船舶、航空器及遠<br>洋漁船。<br>77:銷售與國際運輸用之船舶、航空<br>器及遠洋漁船所使用之貨物或修繕勞<br>務。<br>78:保稅區營業人銷售與課稅區營業<br>人未輸往課稅區而直接出口之貨物。<br>79:保稅區營業人銷售與課稅區營業<br>人存入自由港區事業或海關管理之保<br>稅倉庫、物流中心以供外銷之貨物。 | String | taxTypeEnum 為 2 時必填，範圍 71–79              |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 12. addInvoiceDetail

函式簽名：

```csharp
String addInvoiceDetail(String itemId, String description, String quantity, String unitPrice, String amount, String taxTypeEnum, String reMark = "", String unit = "");
```

功能說明：新增發票明細

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | itemId | 產品序號 | String |  |
| 2 | description | 明細產品說明 | String | 必填，去除空白後不可為空，最多 256 字元 |
| 3 | quantity | 數量 | String | 數字字串，可負數或小數 |
| 4 | unitPrice | 單價 | String | 數字字串，可負數或小數 |
| 5 | amount | 折讓未稅總金額 | String | 數字字串，可含正負號與小數 |
| 6 | taxTypeEnum | 課税別<br>1:應税<br>2:零税率<br>3:免税<br>4:應税(特種税率)<br>9:混合應税：免税或零税率(限收<br>銀機發票無法分辨時使用) | String | "^[12349]{1}$"<br>Ex:1 |
| 7 | reMark | 商品備註 | String | 選填；預設空字串，最多 40 字元 |
| 8 | unit | 單位 | String | 選填；預設空字串，最多 6 字元 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 13. toHandleInvoice

函式簽名：

```csharp
String toHandleInvoice();
```

功能說明：開始處理此發票資訊

參數：無

回傳：

JSON：

```json
{
  "rtCode": "2001",
  "rtMessage": "印表機未設定服務開啟",
  "rtData": "TT10000875,20150",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData:發票號碼,發票期別

### 14. cancelInvoice

函式簽名：

```csharp
String cancelInvoice(String trackYear, String trackPeriod, String invoiceNumber);
```

功能說明：作廢發票

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | trackYear | 字軌年分 | String | "^(20)[0-9][0-9]$"<br>Ex:2015 |
| 2 | trackPeriod | 字軌期別 | String | "^[0-5]{1}$"<br>Ex:0 |
| 3 | invoiceNumber | 發票號碼 | String | "^[A-Z]{2}[0-9]{8}$"<br>Ex:AA10000001 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

### 15. rePrinterInvoice

函式簽名：

```csharp
String rePrinterInvoice(String trackYear, String trackPeriod, String invoiceNumber);
```

功能說明：重複列印發票

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | trackYear | 字軌年分 | String | "^(20)[0-9][0-9]$"<br>Ex:2015 |
| 2 | trackPeriod | 字軌期別 | String | "^[0-5]{1}$"<br>Ex:0 |
| 3 | invoiceNumber | 發票號碼 | String | "^[A-Z]{2}[0-9]{8}$"<br>Ex:AA10000001 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 16. queryInvoice

函式簽名：

```csharp
String queryInvoice(String trackYear, String trackPeriod, String invoiceNumber);
```

功能說明：查詢本機發票內容與處理狀態。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | trackYear | 字軌年分 | String | "^(20)[0-9][0-9]$"<br>Ex:2015 |
| 2 | trackPeriod | 字軌期別 | String | "^[0-5]{1}$"<br>Ex:0 |
| 3 | invoiceNumber | 發票號碼 | String | "^[A-Z]{2}[0-9]{8}$"<br>Ex:AA10000001 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": "",
  "rtInvoice": "{\"Is_OnlyPrint\":true,\"Is_PrintDetail\":true,\"Is_PrintSELLER_INC_ID\":true,\"Is_AssignInvoiceNumber\":false,\"Print_yearPeriod\":\"106年09-10月\",\"TrackYear\":\"2017\",\"TrackPeriod\":\"4\",\"InvoiceNumber\":\"WY10905083\",\"InvoiceDate\":\"20170920\",\"InvoiceTime\":\"110059\",\"InvoicePrinterDateTime\":\"2017/09/20 11:00:59\",\"PrintTaxFormat\":\"25\",\"Buyer_Identifier\":\"0000000000\",\"Buyer_Name\":\"BuyerName\",\"Buyer_Address\":\"Address\",\"SalesAmount\":\"100\",\"FreeTaxSalesAmount\":\"0\",\"ZeroTaxSalesAmount\":\"0\",\"TaxTypeEnum\":\"1\",\"TaxAmount\":\"0\",\"TotalAmount\":\"100\",\"CarrierType\":\"\",\"CarrierString\":\"\",\"PrintMark\":\"Y\",\"RandomNumber\":\"2506\",\"TaxRate\":\"0.05\",\"PayMethod\":\"現金:100\",\"npo_ban\":\"\",\"Inc_id\":\"53567686\",\"Barcode\":\"201709WY109050832506\",\"Qr1\":\"WY10905083106092025060000000000000064000000000053567686/ySynrs0RaEm3M/FEfoLCA==:**********:2:2:1:00004:1:50:00004:1:50:\",\"Qr2\":\"**\",\"TaxTag\":\"\",\"AmountZeroFlag\":false,\"Payment_Method\":\"\",\"ExtraData\":\"信用卡末四碼：3214|買受人:BuyerName\",\"TransactionData\":\"單號:20170920000001\",\"details\":[{\"SequenceNumber\":\"1\",\"ItemId\":\"00004\",\"Description\":\"00004\",\"UnitPrice\":\"50\",\"Quantity\":\"1\",\"Amount\":\"50\",\"Unit\":\"\",\"TaxTypeEnum\":\"1\",\"TaxAmount\":\"0\",\"reMark\":\"\"},{\"SequenceNumber\":\"2\",\"ItemId\":\"00004\",\"Description\":\"00004\",\"UnitPrice\":\"50\",\"Quantity\":\"1\",\"Amount\":\"50\",\"Unit\":\"000\",\"TaxTypeEnum\":\"1\",\"TaxAmount\":\"0\",\"reMark\":\"test\"}],\"syncFlag\":false,\"SendB2BFlag\":false,\"member_carrier_identifier\":\"\",\"member_carrier_inc_id\":\"\",\"CustomsClearanceMark\":\"\"}",
  "rtState": "2"
}
```

rtCode=0000 成功

rtMessage:訊息

rtInvoice：發票 JSON 字串，需再解析一次。

rtState：0 未處理、1 傳送中、2 傳送完成、3 已傳送但資料有錯誤、4 開立完成、5 收到作廢要求、6 作廢傳送中、7 作廢失敗、8 作廢成功、9 收到註銷要求、10 註銷傳送中、11 註銷失敗。

### 17. stopServiceAll

函式簽名：

```csharp
void stopServiceAll();
```

功能說明：停止DLL所有服務

參數：無

回傳：無

### 18. queryInvoiceQueueNonUpload

函式簽名：

```csharp
String queryInvoiceQueueNonUpload(String invoiceState);
```

功能說明：查詢指定本機狀態的發票清單。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | invoiceState | 發票狀態 | String | 0 已開立未處理<br>5 收到作廢發票未處理 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": "",
  "rtInvoiceArray": "[{\"InvoiceNumber\":\"VC10004292\",\"TrackYear\":\"2015\",\"TrackPeriod\":\"1\"},{\"InvoiceNumber\":\"VC10004291\",\"TrackYear\":\"2015\",\"TrackPeriod\":\"1\"}]"
}
```

rtCode=0000 成功

rtMessage:訊息

rtInvoiceArray：發票識別資料陣列的 JSON 字串，需再解析一次。

### 19. getnowPeriodTrack

函式簽名：

```csharp
String getnowPeriodTrack();
```

功能說明：手動強制執行取當期字軌。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData：預設空字串；此函式執行字軌申領，取號請使用 getTrackNo。

### 20. queryNextTrackNo

函式簽名：

```csharp
String queryNextTrackNo(String type = "07");
```

功能說明：查詢下一張發票號碼

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | type | 發票種類代碼；預設 07 | String | 選填；預設 `"07"` |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtUseYear": "2015",
  "rtUsePeriod": "0",
  "rtTrackNo": "TT10000014",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000成功 rtMessage:訊息 rtUseYear:發票使用年份

rtUsePeriod:發票使用期別 rtTrackNo:發票號碼

### 21. printDetailON

函式簽名：

```csharp
String printDetailON();
```

功能說明：列印明細。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 22. printDetailOFF

函式簽名：

```csharp
String printDetailOFF();
```

功能說明：關閉列印明細。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 23. setPrinterInvoiceHeader_FooterWord

函式簽名：

```csharp
String setPrinterInvoiceHeader_FooterWord(String printword);
```

功能說明：設定發票下方提示文字。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | printword | 文字 | String |  |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 24. toHandleInvoiceSync

函式簽名：

```csharp
String toHandleInvoiceSync();
```

功能說明：開始處理此發票資訊等待回應

參數：無

回傳：

JSON：

```json
{
  "rtCode": "2001",
  "rtMessage": "印表機未設定服務開啟",
  "rtData": "TT10000875,20150",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData:發票號碼,發票期別

### 25. addallowancesTitle

函式簽名：

```csharp
String addallowancesTitle(String allowance_number, String buyer_identifier, String buyer_name, String allowance_date, String allowance_type, String total_amount, String tax_amount);
```

功能說明：開立折讓單主體

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | allowance_number | 折讓單號碼 | String | 英數字與連字號，至少 1 字元 |
| 2 | buyer_identifier | 買方統編 | String |  |
| 3 | buyer_name | 收件人姓名，不得空白 | String |  |
| 4 | allowance_date | 折讓日期 | String | yyyyMMdd |
| 5 | allowance_type | 折讓型態 | String | 1:買方開立折讓證明單<br>2:賣方折讓證明單通知 |
| 6 | total_amount | 總金額 | String | 非負整數字串 |
| 7 | tax_amount | 税額 | String | 非負整數字串 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 26. addallowancesItem

函式簽名：

```csharp
String addallowancesItem(String original_invoice_date, String original_invoice_number, String original_description, String quantity, String unit_price, String amount, String original_sequence_number, String allowance_sequence_number, String tax, String tax_type);
```

功能說明：開立折讓單明細

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | original_invoice_date | 原發票日期 | String | yyyyMMdd；請由呼叫端先確認日期有效 |
| 2 | original_invoice_number | 發票號碼 | String | ^[A-Z]{2}[0-9]{8}$ |
| 3 | original_description | 折讓品項名稱 | String |  |
| 4 | quantity | 數量 | String | ^\\\\d{1,}$ |
| 5 | unit_price | 折讓品項單價 | String | ^\\\\d{1,}$ |
| 6 | amount | 折讓未稅總金額 | String | ^\\\\d{1,}$ |
| 7 | original_sequence_number | 原始折讓品項序號 | String |  |
| 8 | allowance_sequence_number | 折讓品項序號 | String |  |
| 9 | tax | 折讓品項折讓稅額 | String | ^\\\\d{1,}$ |
| 10 | tax_type | 折讓品項課稅別<br>1:應稅<br>2:零稅率<br>3:免稅<br>4:應稅(特種稅率)<br>9:混合應稅與免稅<br>或零 稅率(限收銀機<br>發票無法 分辨時使<br>用) | String | ^[12349]{1}$ |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 27. PrintInvoiceON

函式簽名：

```csharp
String PrintInvoiceON();
```

功能說明：列印發票開啟。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000成功

rtMessage:訊息

### 28. PrintInvoiceOFF

函式簽名：

```csharp
String PrintInvoiceOFF();
```

功能說明：列印發票關閉。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 29. onlyPrintInvoice

函式簽名：

```csharp
String onlyPrintInvoice();
```

功能說明：僅列印發票。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtOtherMessage": "",
  "rtData": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 30. supplyPrinterInvoice

函式簽名：

```csharp
String supplyPrinterInvoice(String invoiceNumber, String invoiceDate);
```

功能說明：補印發票。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | invoiceNumber | 發票號碼 | String |  |
| 2 | invoiceDate | 發票日期 | String | yyyyMMdd |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 31. openSendB2B

函式簽名：

```csharp
String openSendB2B();
```

功能說明：設定傳送B2B

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 32. closeSendB2B

函式簽名：

```csharp
void closeSendB2B();
```

功能說明：關閉傳送B2B

參數：無

回傳：無

### 33. writeOffInvoice

函式簽名：

```csharp
String writeOffInvoice(String trackYear, String trackPeriod, String invoiceDate, String invoiceNumber);
```

功能說明:註銷發票。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | trackYear | 字軌年分 | String |  |
| 2 | trackPeriod | 字軌期別 | String |  |
| 3 | invoiceDate | 發票日期 | String | yyyyMMdd |
| 4 | invoiceNumber | 發票號碼 | String |  |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

### 34. GetInvoiceStatusWithDate

函式簽名：

```csharp
String GetInvoiceStatusWithDate(String invoiceNumber, String invoiceDate);
```

功能說明:取得發票狀態。

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | invoiceNumber | 發票號碼 | String |  |
| 2 | invoiceDate | 發票日期 | String | yyyyMMdd |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "已開立",
  "rtData": "1",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData:狀態碼

| 狀態碼 | 狀態 |
| --- | --- |
| 1 | 已開立 |
| 9 | 已開立 |
| 13 | 已開立(存證) |
| 17 | 已開立(存證) |
| 2 | 已作廢 |
| 11 | 已作廢 |
| 15 | 已作廢(存證) |
| 19 | 已作廢(存證) |
| 3 | 開立中 |
| 12 | 開立中 |
| 8 | 開立中 |
| 16 | 開立中 |
| 4 | 作廢中 |
| 14 | 作廢中 |
| 10 | 作廢中 |
| 18 | 作廢中 |
| 5 | 錯誤 |
| 6 | 已註銷 |
| 7 | 註銷中 |

網路或回應解析失敗時可能回傳 `null`；請先判斷再解析 JSON。

### 35. openPrinter

函式簽名：

```csharp
String openPrinter();
```

功能說明:開啟印表機。操作完畢需呼叫關閉印表機

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 36. closePrinter

函式簽名：

```csharp
String closePrinter();
```

功能說明:關閉印表機。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 37. resetPrinterFormat

函式簽名：

```csharp
String resetPrinterFormat();
```

功能說明:重設印表機列印格式。需開啟印表機才可使用

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 38. printerSetChineseFontStyle

函式簽名：

```csharp
String printerSetChineseFontStyle(int widthTimes, int heightTimes);
```

功能說明:設定印表機列印字體大小。需開啟印表機才可使用

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | widthTimes | 字體寬度 | int |  |
| 2 | heightTimes | 字體高度 | int |  |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 39. printerSetJustification

函式簽名：

```csharp
String printerSetJustification(int mode);
```

功能說明:設定印表機列印文字對齊方式。需開啟印表機才可使用

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | mode |  | int | 0 置左<br>1 置中<br>2 置右 |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 40. printerPrintString

函式簽名：

```csharp
String printerPrintString(String str);
```

功能說明:列印文字。需開啟印表機才可使用

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | str | 列印文字 | String |  |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 41. printerNewLine

函式簽名：

```csharp
String printerNewLine();
```

功能說明:列印換行。需開啟印表機才可使用

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 42. printerSetLineSpacing

函式簽名：

```csharp
String printerSetLineSpacing(int point);
```

功能說明:設定列印行距。需開啟印表機才可使用

參數：

| SN | Parameters | Description | Type | Restrictions |
| --- | --- | --- | --- | --- |
| 1 | point |  | int |  |

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 43. printerCut

函式簽名：

```csharp
String printerCut();
```

功能說明:印表機裁切。需開啟印表機才可使用

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 44. checkPaperStatus

函式簽名：

```csharp
String checkPaperStatus();
```

功能說明:確認印表機及紙量狀況

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "正常",
  "rtData": "0",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 狀態碼 0 正常 1 少紙 2 缺紙 3 其他錯誤

印表機服務未啟動時直接回傳字串 `"0002"`，此時不是 JSON；呼叫端應先判斷。

### 45. toOnlyUploadInvoice

函式簽名：

```csharp
String toOnlyUploadInvoice();
```

功能說明：僅上傳發票。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData: 訊息

### 46. GetWaitUploadInvoiceCount

函式簽名：

```csharp
String GetWaitUploadInvoiceCount();
```

功能說明：取得本機尚未上傳的發票數量。

參數：無

回傳：

JSON：

```json
{
  "rtCode": "0000",
  "rtMessage": "",
  "rtData": "1",
  "rtOtherMessage": ""
}
```

rtCode=0000 成功

rtMessage:訊息

rtData:未上傳發票數量

## DLL 使用範例

以下為一般應稅、無載具、無買方統編的開立流程。帳號與金鑰請替換為申請的值；日期與字軌需屬於可開立期別。

```csharp
using System;
using EcloudPOSDll;
using Newtonsoft.Json.Linq;

class Example
{
    static JObject Check(string response)
    {
        if (String.IsNullOrEmpty(response)) throw new Exception("未取得回應");
        JObject result = JObject.Parse(response);
        if ((string)result["rtCode"] != "0000")
            throw new Exception((string)result["rtMessage"]);
        return result;
    }

    static void Main()
    {
        EcloudPosDll dll = new EcloudPosDll();
        try
        {
            dll.initEcloud(@"C:\ecloud");
            dll.setInformation("Test", "YOUR_INC_ID", "YOUR_API_KEY", "YOUR_SECRET_KEY", "YOUR_POS_ID");
            dll.setSalesInformation("YOUR_STORE_ID", "YOUR_SELLER_ID", "YOUR_BUSINESS_ID", "YOUR_AES_KEY");
            dll.setProfile("測試店家", "測試地址", "0212345678");
            Check(dll.startService());
            Check(dll.setTrackInformation(5, 3, 24));
            Check(dll.startTrackService());
            Check(dll.startPrinterService("TP809", "COM4", "115200", @"C:\ecloud\logo.bmp",
                is_NocheckPrinter: false, Footer: "退貨憑電子發票證明聯正本辦理",
                cutInvoiceDetail: false, printItemId: true, printPayMethod: true, printInvoiceNumber: true));
            DateTime now = DateTime.Now;
            JObject track = Check(dll.getTrackNo(now.Year.ToString(), ((now.Month - 1) / 2).ToString()));
            Check(dll.addInvoiceHeader(
                trackYear: (string)track["rtUseYear"], trackPeriod: (string)track["rtUsePeriod"],
                invoiceNumber: (string)track["rtTrackNo"], invoiceDate: now.ToString("yyyyMMdd"),
                invoiceTime: now.ToString("HHmmss"), invoicePrinterDatetime: now.ToString("yyyy-MM-dd HH:mm:ss"),
                printTaxFormat: "25", buyerIdentifier: "", buyerName: "", buyerAddress: "",
                buyerEmail: "", buyerTel: "", salesAmount: "100", freeTaxSalesAmount: "0",
                zeroTaxSalesAmount: "0", taxTypeEnum: "1", taxAmount: "5", totalAmount: "105",
                carrierType: "", carrierString1: "", carrierString2: "", printMark: "Y",
                randomNumber: "1234", npoBan: "", taxRate: "0.05", payMethod: "現金:105",
                extraData: "", memberCarrierIdentifier: "", memberCarrierIncId: "", transactionData: "",
                customsClearanceMark: "", mainRemark: "", invoiceFootString: "",
                isExchange: "false", zeroTaxRateReason: ""));
            Check(dll.addInvoiceDetail("1001", "商品", "1", "100", "100", "1"));
            Check(dll.toHandleInvoice());
            // 需要作廢時使用完整的三個參數：
            // Check(dll.cancelInvoice((string)track["rtUseYear"], (string)track["rtUsePeriod"], (string)track["rtTrackNo"]));
        }
        finally { dll.stopServiceAll(); }
    }
}
```

