開立發票

開立一張電子發票（F0401），並交給 Turnkey 上傳財政部。

呼叫成功時，發票已經合法開立、號碼已確定，系統會在背景交給 Turnkey 上傳財政部。上傳結果請用查詢發票的 status 追蹤。

Header

請求內容

基本與買方

載具、捐贈、列印

課稅與備註

明細 items[]

至少 1 項、最多 9,999 項。

載具、捐贈、列印的規則

這三者依財政部規定互相限制，不符合時回應 422：

金額計算

系統依財政部規定自動計算，金額四捨五入到整數元：

範例：B2B 含稅總計 1,000 元 → 銷售額 952、稅額 48。若你的系統提供的是未稅價，請帶 "prices_include_tax": false，系統會改為 未稅 1,000 → 稅額 50、總計 1,050。

混稅

同一張發票同時有應稅與免稅（或零稅率）的品項時，tax_type 填 9，每一項明細各自填 tax_type。 至少要有一項應稅、一項免稅或零稅率。系統依課稅別分組，各組以上表的方式計算後加總：

• sales_amount：應稅品項的銷售額（B2C 含稅、B2B 未稅）
• free_tax_sales_amount／zero_tax_sales_amount：免稅／零稅率品項的合計
• tax_amount：只有 B2B 的應稅品項有稅額
• total_amount = 三種銷售額 + 稅額

{
  "external_id": "ORDER-20261004-0005",
  "tax_type": "9",
  "items": [
    { "description": "便當",   "quantity": 1, "unit_price": 100, "tax_type": "1" },
    { "description": "雞蛋",   "quantity": 1, "unit_price": 60,  "tax_type": "3" }
  ]
}

回應中 sales_amount 為 100、free_tax_sales_amount 為 60、total_amount 為 160。實際哪些品項為免稅請依營業稅法並洽詢國稅局。

範例

以下為請求內容（JSON）。實際送出時需加上簽章 Header，完整程式見PHP 範例或bash 範例。

B2C：存入手機條碼

{
  "external_id": "ORDER-20261004-0001",
  "carrier_type": "3J0002",
  "carrier_id": "/ABC+123",
  "items": [
    { "description": "綠茶", "quantity": 10, "unit_price": 25 },
    { "description": "拿鐵", "quantity": 1,  "unit_price": 75 }
  ]
}

B2C：捐贈

{
  "external_id": "ORDER-20261004-0002",
  "npoban": "8999",
  "items": [{ "description": "會員月費", "quantity": 1, "unit_price": 299 }]
}

B2C：列印紙本證明聯

{
  "external_id": "ORDER-20261004-0003",
  "buyer_name": "王小明",
  "items": [{ "description": "商品", "quantity": 2, "unit_price": 150 }]
}

沒有載具也沒有捐贈，print 會自動為 true。

B2B：打統編

{
  "external_id": "ORDER-20261004-0004",
  "buyer_ban": "22099131",
  "buyer_name": "台灣積體電路製造股份有限公司",
  "items": [{ "description": "顧問服務費", "quantity": 1, "unit_price": 10500, "unit": "式" }]
}

回應中 sales_amount 為 10000、tax_amount 為 500、total_amount 為 10500。

回應

201 Created 新開立一張發票。200 OK 相同 external_id 已開立過，回傳原本那張。

{
  "data": {
    "invoice_number": "KZ10000000",
    "invoice_date": "2026-10-04",
    "invoice_time": "18:35:50",
    "random_number": "7887",
    "status": "sent",
    "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,
    "zero_tax_sales_amount": 0,
    "free_tax_sales_amount": 0,
    "tax_amount": 0,
    "total_amount": 325,
    "items": [
      { "sequence": 1, "description": "綠茶", "quantity": 10, "unit_price": 25, "unit": null, "amount": 250, "tax_type": "1", "remark": null },
      { "sequence": 2, "description": "拿鐵", "quantity": 1,  "unit_price": 75, "unit": null, "amount": 75, "tax_type": "1", "remark": null }
    ]
  }
}

回應欄位

錯誤

發生 409、422 時不會消耗發票號碼，修正後可直接重送。