查詢發票

以發票號碼查詢發票內容與上傳狀態。

GEThttps://invoice.workat.studio/api/v1/invoices/{invoiceNumber}

常用於追蹤上傳進度：開立後定期查詢，直到 status 變成 uploaded（存證成功）或 failed（失敗）。

Header

名稱	值
`X-Api-Key`、`X-Timestamp`、`X-Nonce`、`X-Signature`	簽章驗證，算法見簽章算法。GET 沒有請求內容，內容雜湊為空字串的 SHA256
`Accept`	`application/json`

路徑參數

參數	型別		說明
`invoiceNumber`	string	必填	發票號碼，2 碼大寫英文 + 8 碼數字，例如 `KZ10000000`

只查得到這把 API 金鑰所屬公司的發票。查詢其他公司的發票號碼，一律回應 404。
發票號碼每期重新配發，跨年度可能重複；遇到重複時回傳最新開立的那一張。

範例

// 沿用目錄頁 PHP 範例的 einvoiceRequest()
[$status, $result] = einvoiceRequest('GET', '/api/v1/invoices/KZ10000000', null);

簽章用的路徑為 /api/v1/invoices/KZ10000000，內容雜湊為空字串的 SHA256：e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。

回應

200 OK

{
  "data": {
    "invoice_number": "KZ10000000",
    "invoice_date": "2026-10-04",
    "invoice_time": "18:35:50",
    "random_number": "7887",
    "status": "uploaded",
    "external_id": "ORDER-20261004-0001",
    "seller_ban": "85426409",
    "buyer_ban": null,
    "buyer_name": "7887",
    "carrier_type": "3J0002",
    "carrier_id": "/ABC+123",
    "npoban": null,
    "print": false,
    "tax_type": "1",
    "sales_amount": 325,
    "tax_amount": 0,
    "total_amount": 325,
    "items": [
      { "sequence": 1, "description": "綠茶", "quantity": 10, "unit_price": 25, "amount": 250 },
      { "sequence": 2, "description": "拿鐵", "quantity": 1,  "unit_price": 75, "amount": 75 }
    ]
  }
}

上傳失敗時

status 為 failed 時，會多一個 upload_error 欄位，說明 Turnkey 或財政部平台回報的錯誤：

{
  "data": {
    "invoice_number": "KZ10000000",
    "status": "failed",
    "upload_error": {
      "code": "E201",
      "message": "E0201 / 訊息重複"
    },
    ...
  }
}

上傳失敗需要由系統管理者依錯誤原因處理。發票號碼已經確定，不要為了同一筆交易重新開立一張新發票。

回應欄位

欄位	型別	說明
`invoice_number`	string	發票號碼，2 碼英文 + 8 碼數字，例如 `KZ10000000`
`invoice_date`	string	開立日期 `YYYY-MM-DD`（台灣時間）
`invoice_time`	string	開立時間 `HH:MM:SS`（台灣時間）
`random_number`	string	4 碼防偽隨機碼。消費者查詢發票、列印證明聯時會用到
`status`	string	開立的上傳進度：`issued` / `sent` / `uploaded` / `failed`，註銷重開進行中為 `cancelling`（見發票狀態）
`void`	object\|null	未作廢為 `null`；已作廢時為 `{voided_at, reason, remark, approval_number, status, upload_error?}`，`status` 為作廢的上傳進度 `pending` / `sent` / `uploaded` / `failed`（見作廢發票）
`cancellation`	object	只在 `status` 為 `cancelling` 時出現：`{cancelled_at, reason, status, upload_error}`，`status` 為註銷的上傳進度（見註銷重開）
`upload_error`	object	只在 `status` 為 `failed` 時出現：`{"code": "…", "message": "…"}`，為 Turnkey 或財政部平台回報的錯誤
`external_id`	string\|null	開立時帶入的冪等鍵
`seller_ban`	string	賣方統編（即 API 金鑰所屬公司）
`buyer_ban`	string\|null	買方統編；B2C 為 `null`
`buyer_name`	string	買方名稱
`carrier_type`	string\|null	載具類別
`carrier_id`	string\|null	載具號碼
`npoban`	string\|null	捐贈碼；未捐贈為 `null`
`print`	boolean	是否需要列印電子發票證明聯
`tax_type`	string	課稅別：`1` 應稅、`2` 零稅率、`3` 免稅、`9` 混稅
`sales_amount`	integer	應稅銷售額。B2C 為含稅金額；B2B 為未稅金額；沒有應稅品項為 0
`zero_tax_sales_amount`	integer	零稅率銷售額
`free_tax_sales_amount`	integer	免稅銷售額
`tax_amount`	integer	稅額。B2C 一律為 0
`total_amount`	integer	總計（消費者實付金額）
`items[]`	array	明細：`sequence`、`description`、`quantity`、`unit_price`、`unit`、`amount`、`tax_type`、`remark`。B2B 發票應稅品項的金額為換算後的未稅金額

錯誤

狀態碼	原因
`401`／`403`／`429`	驗證失敗、IP 不在允許清單、請求過於頻繁，見錯誤回應
`404`	發票號碼格式不正確、不存在，或不屬於你的公司