ECPay B2B E-Invoice Node.js SDK

繁體中文 | English

此專案為綠界科技 (ECPay) B2B 電子發票介接 API 的 Node.js 封裝庫。 支援 TypeScript，並相容於 Runtime 如 Node.js 與 Bun。

特色

• Full TypeScript Support
• 包含所有主要的 B2B 發票操作 (開立、折讓、作廢、駁回、確認)
• 包含完整的查詢功能
• 自動處理加密 (AES) 與 URL Encoding

安裝

npm install ecpay-einvoice-b2b-node
# or
yarn add ecpay-einvoice-b2b-node
# or
pnpm add ecpay-einvoice-b2b-node
# or
bun add ecpay-einvoice-b2b-node

快速開始

1. 初始化 Client

import { EcPayClient } from 'ecpay-einvoice-b2b-node'

// 請使用綠界提供的測試或正式帳號參數
const client = new EcPayClient(
  '2000132', // MerchantID
  '09a6a814578b9487', // HashKey
  '9016149959546b48' // HashIV
)

操作範例 (Operations)

開立發票 (IssueInvoice)

import { IssueInvoice, InvType, TaxType, VatType } from 'ecpay-einvoice-b2b-node'

const issue = new IssueInvoice()
issue
  .setMerchantID('2000132')
  .setRelateNumber('ORDER' + Date.now()) // 廠商自訂編號 (唯一)
  .setCustomerIdentifier('12345678') // 買方統編
  .setCustomerName('測試買方公司')
  .setCustomerAddr('台北市南港區三重路...')
  .setCustomerEmail('[email protected]')
  .setTaxType(TaxType.Taxable)
  .setInvType(InvType.Apply) // 一般 B2B
  .setVatType(VatType.Two) // 二聯式
  .addItem({
    ItemName: '服務費',
    ItemCount: 1,
    ItemWord: '式',
    ItemPrice: 1000,
    ItemTaxType: TaxType.Taxable,
    ItemAmount: 1000,
    ItemRemark: '12月服務費',
  })

// 發送請求
try {
  const response = await client.send(issue)
  console.log('發票開立成功:', response)
} catch (error) {
  console.error('發票開立失敗:', error)
}

開立折讓 (Allowance)

當發票需要部分或全部退款時使用。

import { Allowance, TaxType } from 'ecpay-einvoice-b2b-node'

const allowance = new Allowance()
allowance
  .setMerchantID('2000132')
  .setInvoiceNumber('AB12345678') // 原發票號碼
  .setAllowanceDate('2023-12-08')
  .setBuyerIdentifier('12345678')
  .setSellerIdentifier('2000132')
  .addItem({
    ItemName: '服務費',
    ItemCount: 1,
    ItemWord: '式',
    ItemPrice: 1000,
    ItemTaxType: TaxType.Taxable,
    ItemAmount: 1000,
  })

const response = await client.send(allowance)

發票作廢 (Invalid)

import { Invalid } from 'ecpay-einvoice-b2b-node'

const invalid = new Invalid()
invalid
  .setMerchantID('2000132')
  .setInvoiceNumber('AB12345678')
  .setInvoiceDate('2023-12-08')
  .setInvalidReason('訂單取消') // 作廢原因

const response = await client.send(invalid)

上傳字軌 (AddInvoiceWordSetting)

在開立發票前，必須先設定字軌。

import { AddInvoiceWordSetting, InvoiceTerm, InvoiceHeader } from 'ecpay-einvoice-b2b-node'

const word = new AddInvoiceWordSetting()
word
  .setMerchantID('2000132')
  .setInvoiceYear(2023)
  .setInvoiceTerm(InvoiceTerm.Dec) // 12月
  .setInvoiceHeader(InvoiceHeader.General) // 字軌類別
  .setInvoiceCategory('1') // B2B
  .setInvoiceStart('AB12345600')
  .setInvoiceEnd('AB12345699')

const response = await client.send(word)

查詢範例 (Queries)

查詢發票明細 (GetIssue)

import { GetIssue } from 'ecpay-einvoice-b2b-node'

const query = new GetIssue()
query.setMerchantID('2000132').setRelateNumber('ORDER1701999999') // 使用廠商自訂編號查詢

const response = await client.send(query)
console.log(response)

查詢字軌 (GetInvoiceWordSetting)

import { GetInvoiceWordSetting, InvoiceTerm } from 'ecpay-einvoice-b2b-node'

const query = new GetInvoiceWordSetting()
query.setMerchantID('2000132').setInvoiceYear(2023).setInvoiceTerm(InvoiceTerm.Dec)

const response = await client.send(query)

支援功能列表

Operations

• IssueInvoice (開立發票)
• Allowance (開立折讓)
• Invalid (發票作廢)
• AllowanceInvalid (折讓作廢)
• Reject (發票駁回)
• IssueConfirm (開立確認)
• AllowanceConfirm (折讓確認)
• InvalidConfirm (作廢確認)
• MaintainMerchantCustomerData (維護客戶資料)
• UpdateInvoiceWordStatus (更新字軌狀態)

Queries

• GetIssue
• GetAllowance
• GetInvalid
• GetReject
• GetInvoiceWordSetting (查詢字軌)
• GetGovInvoiceWordSetting (查詢上傳結果)
• 以及對應的 Confirm 查詢

錯誤處理

所有 API 回傳錯誤或驗證失敗都會拋出 EcPayError。

import { EcPayError } from 'ecpay-einvoice-b2b-node'

try {
  // ...
} catch (e) {
  if (e instanceof EcPayError) {
    console.error('ECPay Error:', e.message)
  }
}