@paid-tw/einvoice-amego

English ｜ 繁體中文

@paid-tw/einvoice 的 Amego 轉接器。透過 Amego 電子發票 API 實作 InvoiceProvider 介面。

pnpm add @paid-tw/einvoice @paid-tw/einvoice-amego

import { createAmegoProvider } from "@paid-tw/einvoice-amego";

const invoices = createAmegoProvider({
  sellerUbn: "12345678",            // 賣方統一編號
  appKey: process.env.AMEGO_APP_KEY!,
});

await invoices.issue({ /* IssueInvoiceInput */ });

Amego 測試與正式環境共用同一個主機，環境是由你的憑證決定，而非由 URL 或 模式決定。

免帳號試用

Amego 提供共用的**測試（sandbox）**憑證。你可以直接使用匯出的 AMEGO_SANDBOX 對測試商家開立發票：

import { createAmegoProvider, AMEGO_SANDBOX } from "@paid-tw/einvoice-amego";

const invoices = createAmegoProvider(AMEGO_SANDBOX); // 統編 12345678 — never use in production

狀態

請求簽章、各端點的欄位約定，以及回應解析皆已對 Amego 線上測試環境驗證過。 Amego 各端點之間刻意不一致——這個轉接器把驗證過的真實情況封裝起來，讓你不必自己處理：

| 項目 | 細節 | | --- | --- | | 大小寫 | f0401 / *_print 使用 PascalCase；invoice_query / *_file / *_list / allowance_query 使用 snake_case | | 陣列負載 | f0501、g0401、g0501、*_status、ban_query 接受 JSON 陣列 | | 區別欄位 | invoice_query / invoice_file 需要 type: "invoice" | | 稅額拆分 | B2B 三聯式拆分未稅銷售額 + 稅額；B2C 二聯式保留含稅總額且稅額為 0；品項稅別混用 ⇒ 發票 TaxType 9 | | 折讓 | 採用未稅金額並逐行帶 Tax；不回傳號碼（你提供的 AllowanceNumber 即為 id） | | 日期 | 開立回傳 unix invoice_time；查詢回傳 invoice_date（YYYYMMDD）+ invoice_time（HH:MM:SS） |

你可以用 AMEGO_LIVE=1 自行執行線上生命週期測試（參見 src/__tests__/live.test.ts）。

韌性（選用）

createAmegoProvider({
  sellerTaxId, appKey,
  syncTime: true,                       // sync clock vs /json/time (avoids error 15)
  retry: { maxRetries: 3, baseDelayMs: 500 }, // retry transient network failures only
});

載具 / 統編 驗證

await invoices.validateMobileBarcode("/TRM+O+P"); // → boolean (registered?)
await invoices.validateBan("28080623");           // → boolean (company exists?)

validateMobileBarcode 與 ezPay 轉接器一致（CARRIER_VALIDATION 能力），因此兩個 provider 可互換使用；barcodeQuery() / banQuery() 則保留以取得完整的原始回應。

錯誤提示（選用）

光貿的帳號／串接層錯誤（IP 限制、尚未申請 API 串接、字軌用罄…）從原始訊息看不出 「接下來該做什麼」，而這些恰好都需要商家自己到光貿後台處理。amegoErrorHint() 把這類錯誤碼翻成可直接顯示給商家的 zh-TW 行動指引；不屬於此類的錯誤回傳 undefined，請退回顯示 error.message（光貿原文）：

import { amegoErrorHint } from "@paid-tw/einvoice-amego";
import { isInvoiceError } from "@paid-tw/einvoice";

try {
  await invoices.issue(input);
} catch (e) {
  const hint = amegoErrorHint(e); // 也接受 rawCode："14" / 14
  showError(hint ?? (isInvoiceError(e) ? e.message : "開立失敗"));
}

涵蓋：12／13／14／16／19／22（帳號與串接設定）、10／15／18／21 （光貿端暫時性錯誤）、3040111／3040191（字軌用罄）。其中 14「IP 錯誤」在 後台設有 IP 限制、而請求來自雲端（IP 不固定）時必然發生——提示會引導商家移除 IP 限制。

若要以程式分流（而非顯示），請改用 InvoiceError 上正規化的 reason 欄位 （如 duplicate_order／void_blocked_by_allowance），或以 amegoErrorReason(rawCode) 直接查表——不需要在呼叫端自行維護原始錯誤碼對照。

設定

| 選項 | 必填 | 說明 | | --- | --- | --- | | sellerTaxId | ✅ | 已在 Amego 註冊的賣方統一編號 | | appKey | ✅ | 用於簽署請求的 App key（僅限伺服器端） | | mode | | "TEST"（預設）或 "PRODUCTION" | | baseUrl | | 覆寫 API 主機 | | timeoutMs | | 請求逾時 | | fetch | | 注入自訂的 fetch | | debug | | 選用的請求追蹤 logger（metadata：method/url/status/耗時/error，不含請求內容） | | syncTime | | 與 /json/time 校時以避免錯誤 15（參見上方韌性範例） | | retry | | 僅針對暫時性網路錯誤重試（參見上方韌性範例） |

mode / baseUrl / timeoutMs / fetch / debug 為 @paid-tw/einvoice 的 BaseProviderConfig 共用欄位。

輸入會先經共用 schema 驗證，失敗丟出 InvoiceError（code VALIDATION）。

授權

MIT