列印證明聯
取得電子發票證明聯(5.7 公分感熱紙格式)的 HTML,以及一維條碼、兩個 QR Code 的內容。
POSThttps://invoice.workat.studio/api/v1/invoices/{invoiceNumber}/print
依《電子發票實施作業要點》附件一(115/04/22)的格式一(寬 5.7 公分)產生,條碼內容依《電子發票證明聯一維及二維條碼規格說明》V1.9。回應同時提供:
html:排版完成、條碼以 SVG 內嵌的 HTML,可直接用瀏覽器或列印程式送到 58mm 熱感印表機barcode、qr_left、qr_right與各欄位:若你使用 ESC/POS 指令自行排版,可直接使用這些內容
只有開立時「列印證明聯」的發票才能呼叫(回應中
print 為 true,例如打統編、沒有載具也沒有捐贈)。
存入手機條碼等載具或捐贈的發票,依規定不列印證明聯,呼叫會回應 409。
格式
format | 格式 | 適用 |
|---|---|---|
thermal(預設) | 格式一:寬 5.7 公分感熱紙,一維條碼 + 兩個 QR Code | 所有可列印的發票 |
a4 | 格式二:A4(21 × 29.7 公分),品項多時自動分頁 | 限買受人為營業人(打統編)的發票(作業要點第五章) |
a4_half | 格式二:半張 A4(21 × 14.85 公分),品項多時自動分頁(第一頁有合計區,之後各頁只有明細) |
格式二依作業要點附件一圖 2 的版面:沒有一維條碼與 QR Code,以表格列出交易明細,下方為銷售額合計、營業稅(勾選應稅/零稅率/免稅)、總計與中文大寫, 右下為「營業人蓋統一發票專用章」欄。賣方資料依公司設定:在該欄條列名稱、統一編號、地址,或印上統一發票專用章,或兩者都有。
規則
- 第二次以後列印會自動加註「補印」(作業要點附件一、壹、一、(八)),回應的
reprint為true。 - 買受人為營業人(打統編)時,二維條碼下方一定會接續列印交易明細,含銷售額與稅額。
- 買受人為一般消費者時,預設不印交易明細;帶
"details": true會在裁切線下方加印。 - 已作廢的發票不可列印。
- 最上方的營業人識別標章可以是圖片、圖片 + 文字或文字,由系統管理者為每間公司設定;未設定時印公司名稱。
- 證明聯背面的兌獎說明、網址 QR Code 與領獎收據欄位,通常由感熱紙廠商預印,本 API 不輸出。
Header
| 名稱 | 值 |
|---|---|
X-Api-Key、X-Timestamp、X-Nonce、X-Signature | 簽章驗證,算法見簽章算法 |
Content-Type | application/json |
Accept | application/json |
請求內容
| 欄位 | 型別 | 說明 | |
|---|---|---|---|
format | string | 選填 | thermal(預設)、a4、a4_half,見格式 |
details | boolean | 選填 | 格式一時,一般消費者的發票是否加印交易明細,預設 false。打統編的發票一律列印,忽略此欄位 |
不需要任何欄位時,請求內容送 {}(簽章時內容雜湊以 {} 計算)。
回應
200 OK
{
"data": {
"invoice_number": "KZ10000000",
"format": "thermal",
"reprint": false,
"print_count": 1,
"with_details": false,
"logo_text": "沃克貓工作室",
"logo_has_image": false,
"period_label": "115年09-10月",
"invoice_number_label": "KZ-10000000",
"datetime": "2026-10-05 10:30:00",
"random_number": "7887",
"total": 325,
"seller_ban": "85426409",
"buyer_ban": null,
"format_code": null,
"non_deductible": false,
"barcode": "11510KZ100000007887",
"qr_left": "KZ10000000115100578870000013600000145000000008542640 9…:**********:2:2:1:綠茶:10:25:拿鐵:1:75",
"qr_right": "**",
"qr_items": 2,
"html": "<!DOCTYPE html>…"
}
}
回應欄位
| 欄位 | 說明 |
|---|---|
reprint | 是否為補印(第二次以後列印) |
print_count | 含本次在內的列印次數 |
logo_text | 證明聯最上方「營業人識別標章」的文字;只放圖片時為 null |
logo_has_image | 標章是否有圖片。HTML 已內嵌圖片;自行排版(ESC/POS)時,圖片請預先存入印表機 |
period_label | 年期別,例「115年09-10月」 |
invoice_number_label | 證明聯上的發票號碼,例「KZ-10000000」 |
format_code | 買受人為營業人、一般稅額計算時為 25(印「格式 25」);其餘為 null |
non_deductible | 買受人為營業人、特種稅額計算時為 true(印「不得扣抵」) |
barcode | 一維條碼(Code 39)內容 19 碼:年期別 5 碼 + 發票號碼 10 碼 + 隨機碼 4 碼 |
qr_left | 左方 QR Code 內容。前 77 碼為:號碼、民國日期、隨機碼、銷售額與總計(各 8 碼 16 進位)、買方與賣方統編、加密驗證資訊 24 碼;之後為品目資訊(UTF-8) |
qr_right | 右方 QR Code 內容,以 ** 開頭 |
qr_items | 兩個 QR Code 共記載的品目筆數(品目過多時,超出容量的不記載) |
html | 完整的證明聯 HTML |
格式二(a4、a4_half)沒有 period_label、datetime、barcode、qr_*,改為:
date(交易日期)、sales_amount、zero_tax_sales_amount、free_tax_sales_amount、tax_amount(特種稅額計算時為 null)、
total_in_words(中文大寫,例「壹萬貳仟陸佰元整」)、seller_mode(list 條列/stamp 蓋章/both)。
自行排版時,左方 QR Code 須使用 V6(41×41)以上、容錯等級 L 以上,兩個 QR Code 左右並列、上緣對齊、大小一致,編碼區 1.5 公分以上,四周留白 0.2 公分以上;一維條碼高度 0.5 公分以上。
錯誤
| 狀態碼 | 原因 |
|---|---|
401/403/429 | 驗證失敗、IP 不在允許清單、請求過於頻繁,見錯誤回應 |
404 | 發票不存在,或不屬於你的公司 |
422 | format 不是支援的值 |
409 | 發票已存入載具或捐贈,依規定不列印證明聯 |
| 發票已作廢 | |
| 格式一:公司尚未設定 QR Code 金鑰(請聯絡系統管理者) | |
| 格式二:買受人不是營業人 | |
| 格式二:公司設定為蓋發票章,但尚未上傳 |