Einvoice

The 1.x line is moving to maintenance mode. A provider-agnostic 2.0 rewrite is in progress on main; once it lands, 1.x continues on the 1-x-stable branch. If you depend on the current Tradevan client, pin ~> 1.4.

What's E-Invoice

To support the thriving e-commerce industry and lower the business costs and barriers associated with printing paper receipts, the Taiwan Executive Yuan announced plans in August 2000 to implement electronic receipts in Taiwan and launched a comprehensive project in May 2010 to promote e-invoice applications. This initiative employs innovative approaches such as allowing consumers to claim virtual receipts via multiple devices, offering automatic checking of receipt lottery numbers, and providing a variety of channels for retailers to issue receipts.

Hence, there are several e-invoice services for B2B, B2C in Taiwan as the intermediate and value-adding platform like CHT, allPay, Tradevan, Neweb, ..etc.

Supported E-Invoice Providers

Tradevan

Installation

Add this line to your application's Gemfile:

gem 'einvoice'

And then execute:

$ bundle

Or install it yourself as:

$ gem install einvoice

Usage

Configure

Einvoice.configure do |config|
  config.endpoint = ENV['EINVOICE_ENDPOINT']
  # endpoint_url will override endpoint for testing purpose
  # config.endpoint_url = ENV['EINVOICE_ENDPOINT_URL']
  config.client_id = ENV['EINVOICE_CLIENT_ID']
  config.client_secret = ENV['EINVOICE_CLIENT_SECRET']
  config.encryption_keys = ENV['ENCRYPTION_KEYS']
  config.format = "json"
  # config.ssl_verify = false # disable TLS certificate verification (default: true)
end

SSL certificate verification

By default, einvoice verifies the TLS certificate of the configured endpoint (config.ssl_verify defaults to true). If you need to disable this — for example when testing against an endpoint with an incomplete certificate chain — you can opt out:

config.ssl_verify = false

Or per-provider:

Einvoice::Tradevan::Provider.new(ssl_verify: false)

Initialize

client = Einvoice::Client.new(Einvoice::Tradevan::Provider.new)

Issue an invoice (開立電子發票)

payload = {
  companyUn: "12345678",
  orgId: "ABCDE",
  type: "I",
  saleIdentifier: "12345678_ABCDE_53b2a44e4b3c",
  transactionNumber: "53b2a44e4b3c",
  transactionDate: "20160425",
  transactionTime: "12:34:56",
  total: "20000",
  paperPrintMode: "0",
  invoiceAlarmMode: "4",
  donate: "N",
  donationUnit: nil,
  carrierType: "3J0002",
  carrierId: "TP03000001234567",
  carrierIdHidden: "TP03000001234567",
  receiverName: "John Appleseed",
  receiverAddrZip: "95014",
  receiverAddrRoad: "1 Infinite Loop - Cupertino CA",
  receiverEmail: "john@gmail.com",
  receiverMobile: "415-284-0579",
  memberId: nil,
  itemList: [
    {
      saleIdentifier: "12345678_ABCDE_53b2a44e4b3c",
      serialNumber: "0001",
      productName: "Coffee Latte",
      qty: "4000",
      price: "5",
      itemTotal: "20000",
      taxType: "T",
      tax: "952"
    }
  ]
}

result = client.issue(payload)
result.successful?
#=> true
result.data
#=>
# {
#   "saleIdentifier"=>"12345678_ABCDE_53b2a44e4b3c",
#   "issueStatus"=>"Y",
#   "failReason"=>"",
#   "invoiceNumber"=>"GX38551078",
#   "checkNumber"=>"4229",
#   "invoiceDate"=>"20160425",
#   "invoiceTime"=>"12:34:58",
#   "texclusiveAmount"=>"19048",
#   "oexclusiveAmount"=>"0",
#   "zexclusiveAmount"=>"0",
#   "tax"=>"952",
#   "inclusiveAmount"=>"20000",
#   "mainRemark"=>"",
#   "invoiceType"=>"",
#   "invoiceStatus"=>"V",
#   "allowanceNumber"=>"",
#   "allowanceDate"=>"",
#   "allowanceExclusiveAmount"=>"",
#   "allowanceTax"=>"",
#   "allowanceTotalAmount"=>"0",
#   "allowanceStatus"=>""
# }

Cancel an invoice (作廢電子發票)

payload = {
  type: "I",
  saleIdentifier: "12345678_ABCDE_53b2a44e4b3c",
  invoiceNumber: "GX38551078",
  invoicePaperReturned: "Y",
}

result = client.cancel(payload)
result.successful?
#=> true
result.data
#=>
# {
#   "saleIdentifier"=>"12345678_ABCDE_53b2a44e4b3c",
#   "voidStatus"=>"Y",
#   "failReason"=>"",
#   "type"=>"I",
#   "invoiceNumber"=>"GX38551078",
#   "allowanceNumber"=>""
# }

Issue an allowance (開立折讓單)

An allowance against a previously issued invoice is sent through issue with type: "A". Each item must reference the original invoice (invoiceNumber / invoiceDate) and carry its tax-exclusive amount (itemExclude).

payload = {
  companyUn: "12345678",
  orgId: "ABCDE",
  type: "A",
  allowanceIdentifier: "12345678_ABCDE_53b2a44e4b3d",
  transactionNumber: "53b2a44e4b3d",
  transactionDate: "20160426",
  paperPrintMode: "0",
  invoiceAlarmMode: "4",
  allowanceExclusiveAmount: "95",
  allowanceTax: "5",
  allowanceInclusiveAmount: "100",
  allowancePaperReturned: "N",
  invoicePaperReturned: "N",
  receiverName: "John Appleseed",
  receiverEmail: "john@gmail.com",
  itemList: [
    {
      saleIdentifier: "12345678_ABCDE_53b2a44e4b3c",
      serialNumber: "0001",
      invoiceNumber: "GX38551078",
      invoiceDate: "20160425",
      productName: "Coffee Latte",
      qty: "1000",
      price: "100",
      itemExclude: "95",
      tax: "5",
      itemTotal: "100",
      taxType: "T"
    }
  ]
}

result = client.issue(payload)
result.successful?
#=> true

Notes:

allowanceIdentifier must be prefixed with "#{companyUn}_#{orgId}_", like saleIdentifier on invoices.
allowanceExclusiveAmount + allowanceTax = allowanceInclusiveAmount.

Void an allowance (作廢折讓單)

payload = {
  type: "A",
  companyUn: "12345678",
  allowanceNumber: "ABCDE20160426001",
  allowancePaperReturned: "Y",
}

result = client.cancel(payload)
result.successful?
#=> true

Search invoice by memberId/sellTargetCode (載具/會員發票查詢)

payload = {
  companyUn: "12345678",
  invoiceStartDate: "20160401",
  invoiceEndDate: "20160425",
  carrierId: "TP03000001234567",
  memberId: "",
  sellTargetCode: "",
}

result = client.search_invoice_by_member_id(payload)
result.successful?
#=> true
result.data
#=>
# [
#   {
#     "saleIdentifier"=>"12345678_ABCDE_53b2a44e4b3c",
#     "invoiceNumber"=>"GX38551078",
#     "checkNumber"=>"4229",
#     "invoiceDate"=>"20160425",
#     "invoiceTime"=>"12:34:58",
#     "exclusiveAmount"=>"19048",
#     "tax"=>"952",
#     "total"=>"20000",
#     "status"=>"V",
#     "hasAllowance"=>"N",
#     "sellerName"=>"Starbucks",
#     "sellerUN"=>"12345678",
#     "sellerAddr"=>"1 Infinite Loop - Cupertino CA",
#     "sellerTel"=>"415-284-0579",
#     "receiverName"=>"John Appleseed",
#     "receiverAddr"=>"1 Infinite Loop - Cupertino CA",
#     "paper"=>"N",
#     "win"=>"N",
#     "donate"=>"N",
#     "carrierType"=>"CQ0001",
#     "carrierId"=>"TP03000001234567"
#   }
# ]

Search invoice detail (發票開立明細查詢)

result = client.search_invoice_detail("GX38551078")
result.successful?
#=> true
result.data
#=>
# {
#   "saleIdentifier"=>"12345678_ABCDE_53b2a44e4b3c",
#   "invoiceNumber"=>"GX38551078",
#   "checkNumber"=>"4229",
#   "invoiceDate"=>"20160425",
#   "invoiceTime"=>"12:34:58",
#   "exclusiveAmount"=>"19048",
#   "tax"=>"952",
#   "total"=>"20000",
#   "status"=>"I",
#   "hasAllowance"=>"N",
#   "sellerName"=>"Starbucks",
#   "sellerUN"=>"12345678",
#   "sellerAddr"=>"1 Infinite Loop - Cupertino CA",
#   "sellerTel"=>"415-284-0579",
#   "receiverName"=>"John Appleseed",
#   "receiverAddr"=>"1 Infinite Loop - Cupertino CA",
#   "receiverPhone"=>"415-284-0579",
#   "paper"=>"Y",
#   "win"=>"N",
#   "donate"=>"N",
#   "carrierType"=>"CQ0001",
#   "detailList"=>[
#     {
#       "saleIdentifier"=>"12345678_ABCDE_53b2a44e4b3c",
#       "serialNumber"=>"0001",
#       "productName"=>"Coffee Latte",
#       "qty"=>"4000",
#       "price"=>"5",
#       "total"=>"20000",
#       "taxType"=>"T"
#     }
#   ]
# }

Send card info to customer (電子發票載具歸戶/中獎通知作業)

payload = {
  companyUn: "12345678",
  sellTargetCode: "xxx",
  invoiceStartYM: "201604",
  invoiceEndYM: "201604",
  receiverEmail: "john@gmail.com",
  receiverMobile: "",
}

result = client.send_card_info_to_cust(payload)
result.successful?
#=> true
result.data

Get invoice mark info (電子發票字軌號碼配額取號/分配作業)

payload = {
  companyUn: "12345678",
  orgId: "ABCDE",
  uniFiedNumber: "12345678",
  bookType: "API",
  period: "201604",
}

result = client.get_invoice_mark_info(payload)
result.successful?
#=> true
result.data
#=>
# [
#   {
#     "unifiedNumber"=>"12345678",
#     "bookNumber"=>"API_M1",
#     "bookType"=>"API",
#     "period"=>"201604",
#     "duration"=>"201604",
#     "mark"=>"GX",
#     "start"=>"38551050",
#     "end"=>"38551249"
#   }
# ]

Get donate unit list (受贈機關/社福團體愛心碼清單查詢)

client.get_donate_unit_list("12345678")

Get invoice content (電子發票內容查詢)

payload = {
  invoiceNumber: "GX38551078",
  sellTargetCode: "",
  invoiceStartDate: "",
  invoiceEndDate: "",
}

result = client.get_invoice_content(payload)
result.successful?
#=> true
result.data
#=>

Development

After checking out the repo, run bin/setup to install dependencies. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/abookyun/einvoice.

License

The gem is available as open source under the terms of the MIT License.

einvoice

Development

Runtime

Einvoice

What's E-Invoice

Supported E-Invoice Providers

Installation

Usage

Configure

SSL certificate verification

Initialize

Issue an invoice (開立電子發票)

Cancel an invoice (作廢電子發票)

Issue an allowance (開立折讓單)

Void an allowance (作廢折讓單)

Search invoice by memberId/sellTargetCode (載具/會員發票查詢)

Search invoice detail (發票開立明細查詢)

Send card info to customer (電子發票載具歸戶/中獎通知作業)

Get invoice mark info (電子發票字軌號碼配額取號/分配作業)

Get donate unit list (受贈機關/社福團體愛心碼清單查詢)

Get invoice content (電子發票內容查詢)

Development

Contributing

License