作廢發票

作廢一張已開立的發票（F0501），例如開立錯誤或當期內銷貨退回。

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

任何時候都可以呼叫。作廢時間以呼叫當下為準，系統會立即記錄。
財政部平台必須先收到「開立」才能接受「作廢」。若開立還在上傳中（status 為 issued 或 sent），作廢會先排隊（void.status 為 pending），等開立存證成功後由系統自動送出，你不需要重試。
重複呼叫不會重複作廢，會回傳第一次的作廢紀錄。
作廢後若要重新開立，請呼叫開立發票開一張新的（新號碼）。若必須沿用原號碼，見註銷重開。external_id 不能重複使用，請改用新的值（例如 ORDER-001-R1）。

跨期作廢：發票所屬的期別（每兩個月一期）結束後，必須經國稅局核准，並填寫 approval_number（專案作廢核准文號），否則回應 422。一般跨期的銷貨退回請改開立折讓。開立過折讓的發票，要先作廢所有折讓才能作廢。實際規定請以所轄國稅局為準。

Header

名稱	值
`X-Api-Key`、`X-Timestamp`、`X-Nonce`、`X-Signature`	簽章驗證，算法見簽章算法
`Content-Type`	`application/json`
`Accept`	`application/json`

路徑參數

參數	型別		說明
`invoiceNumber`	string	必填	要作廢的發票號碼，例如 `KZ10000000`。只能作廢自己公司的發票

請求內容

欄位	型別		說明
`reason`	string，1–20 字	必填	作廢原因，會上傳財政部，例如「客戶取消訂單」「品項開立錯誤」
`remark`	string ≤ 200	選填	備註，會上傳財政部
`approval_number`	string ≤ 60	條件必填	專案作廢核准文號。跨期作廢時必填

範例

請求內容：

{
  "reason": "客戶取消訂單",
  "remark": "訂單 ORDER-20261004-0001"
}

// 沿用目錄頁 PHP 範例的 einvoiceRequest()
[$status, $result] = einvoiceRequest('POST', '/api/v1/invoices/KZ10000000/void', [
    'reason' => '客戶取消訂單',
    'remark' => '訂單 ORDER-20261004-0001',
]);

回應

200 OK 回傳發票資料，void 欄位為作廢資訊：

{
  "data": {
    "invoice_number": "KZ10000000",
    "status": "uploaded",
    "void": {
      "voided_at": "2026-10-05 09:30:00",
      "reason": "客戶取消訂單",
      "remark": "訂單 ORDER-20261004-0001",
      "approval_number": null,
      "status": "sent"
    },
    ...
  }
}

status 仍是開立的上傳進度；作廢的上傳進度看 void.status：

void.status	意義
pending	已記錄作廢，等開立存證成功後自動送出
sent	作廢已交給 Turnkey，等待財政部平台回覆
uploaded	財政部平台已作廢成功
failed	作廢上傳失敗，原因在 `void.upload_error`，需要系統管理者處理

錯誤

狀態碼	原因
`401`／`403`／`429`	驗證失敗、IP 不在允許清單、請求過於頻繁，見錯誤回應
`404`	發票不存在，或不屬於你的公司
`422`	`reason`：未填寫或超過 20 字
`422`	`approval_number`：跨期作廢未填寫專案作廢核准文號