跳轉到

e首發票 API — integration guide (English)

Start here — Swagger UI

Product.EInvoice.WebApi — Swagger UI (stage example) — full endpoint list, request/response shapes, and try-it-out.

Signing, environments, and development notes are in §2 onward. Machine-readable OpenAPI JSON (for tooling import only) is in the collapsible Advanced block at the end of §1.

Summary

Entry page for REST API integration: Swagger UI (recommended), provisioning, SHA256 signing, environments, audit behaviour, and a concise JSON field glossary aligned with the published schemas.


English text here supports technical integration only. Provisioning forms, keys, URLs, and compliance are governed by e首發票 announcements, your service provider, and your contract. Where this page differs from Chinese documentation or the Chinese OpenAPI file, resolve the ambiguity with your account contact or customer service.


Before you integrate (provisioning)

You must complete provisioning before you receive API and signing keys.

Item Description
Application Submit the “e首發票 API test application and activation consent form” with correct company name, GUI (Taiwan tax ID), and contacts. Application form (may be Chinese UI)
Keys After activation you receive API key material (including the secret used for signature). Production keys come from the service provider console or contract.
Test validity Test accounts are typically valid for 30 days (confirm with the current announcement).
Support LINE@, phone +886-7-7190888, 0800-800-402, service@einv.tw — staff can guide activation (Chinese service is normal; ask for English-speaking support if needed).

High-level steps: (1) Apply and obtain keys → (2) Explore APIs in Swagger UI and read signing rules (§1–§2) → (3) Choose scenario (invoice-number source) → (4) Develop against stage → (5) Handle errors and audit rules before production.


1. Interactive API reference (Swagger UI)

Use Swagger UI as the primary reference for endpoints, parameters, and try-it-out:

Item Description
Swagger UI (example stage) Product.EInvoice.WebApi — Swagger UI
API name Product.EInvoice.WebApi — external service API
Example base URL https://jpe-sl-einvoice-erpapi-stage.azurewebsites.net (root of the Swagger host)
Version v1
Auth Swagger may accept api_key; real calls must follow body signature rules from your provider (see §2).

Frequently used paths (short list)

Method Path Purpose
POST /Append/Invoices Batch submit already-numbered invoices (invoice mode)
POST /Update/CancelInvoices Void invoice(s)
POST /Update/AllowanceInvoice Create allowance (credit note)

Other Append / Inquire / Update endpoints are listed in Swagger. Groupings match the Chinese API page §1 endpoint table.

OpenAPI JSON vs Swagger UI

Source Count Notes
In OpenAPI JSON 3 POST /Append/Invoices, POST /Update/CancelInvoices, POST /Update/AllowanceInvoice — see Core API endpoint guides and JSON field glossary
Swagger-only (extended) 18 Listed below; approved as public endpoints. Not yet in OpenAPI JSON; coverage will expand in phases. Until then, use Swagger UI and your contract.

Swagger-only extended endpoints

The 18 Swagger-only endpoints have been approved as public endpoints. They are not yet included in the OpenAPI JSON. OpenAPI JSON coverage will be expanded in phases. Until then, Swagger UI remains the primary interactive reference, together with contractual integration agreements. Chinese mirror: Swagger-only 端點.

Group API path Purpose summary Visibility OpenAPI JSON status Documentation status Notes
Append POST /Append/Order Add single order-to-invoice record public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending Order mode
Append POST /Append/Orders Batch add order-to-invoice records public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending Order mode
Append POST /Append/Invoice Add single issued invoice payload public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending Single; batch see /Append/Invoices
Append POST /Append/PrintInvoices Order-mode issue + cloud thermal print queue public Not yet included; planned for phased completion See POST /Append/PrintInvoices Order mode + cloud print
Append POST /Append/BlankCancel Void blank invoice number public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Append POST /Append/TrackBlank Add blank invoice number public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Append POST /Append/InvoiceWithCancel Issue invoice and void in one call public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Inquire POST /Inquire/GetInvoiceIDList Query invoice number list public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Inquire POST /Inquire/GetInvoicesStatus Batch query invoice processing status public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Inquire POST /Inquire/GetInvoicesAppendStatus Batch query invoice append status public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/Invoices Batch update invoice data public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/SetBlankInvoiceID Upload blank invoice number data public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/SplitInvoiceID Set invoice number split rules public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/AllowanceInvoices Batch create allowance documents public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending Single see POST /Update/AllowanceInvoice
Update POST /Update/CancelAllowances Batch void allowance documents public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/CancelAllowance Void allowance document public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/RePrint Reprint invoice public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending
Update POST /Update/SecPrint Supplemental print public Not yet included; planned for phased completion Available in Swagger UI; dedicated guide pending

Environments

  • Stage / test: Base URL and path prefix are provider-specific (examples: Swagger host above, or https://webapi.systemlead.com/terpapi in OpenAPI servers — confirm with your contract).
  • Production: URL and keys from provider console or contract only.
Advanced — machine-readable OpenAPI files (tooling import)

OpenAPI 3.0 JSON files are for Postman, codegen, or CI. Do not use them as the main reading entry — use Swagger UI above.

Asset Description
OpenAPI (JSON, English) einvoice-api-openapi.en.json — recommended English bundle
OpenAPI (JSON, Chinese) einvoice-api-openapi.json — same paths/schemas; Chinese descriptions
Coverage Issue invoice (invoice mode), void invoice, credit note (allowance)
Version 2025.03 (see info.version in the file)

Keep English and Chinese OpenAPI JSON in sync on contract changes (same paths and components.schemas; descriptions translated).


2. Signing and authentication

  • Algorithm: SHA256 signature.
  • Inputs: CompanyID (seller GUI, 8 digits), secret key from provisioning, and Timestamp (see schema SignedPayload).
  • Rules: Respect expiry for Timestamp; do not reuse the same timestamp for multiple submissions.
  • Transport: Actual verification is on the JSON body (CompanyID, Timestamp, Signature) as documented in OpenAPI, not only a header key.

3. Pre-flight checklist

  1. Field mapping from your order/ERP to invoice fields (B2B/B2C, tax type, carrier).
  2. Issue timing (payment, shipment, service completion) to reduce tax-period risk.
  3. Error handling: retries, alerts, manual fix for failures — always handle StatusCode / ResultMessage to avoid missing invoices.
  4. Lifecycle: returns, allowances, voids — who owns the process and how it matches accounting.

4. Issuance and audit (developers)

  • Audit may reject issuance: invalid data returns failure with a reason; fix and resubmit.
  • Log every response: persist StatusCode, ResultMessage for compliance and support.
  • B2B vs B2C: B — line amounts are before tax, header adds 5% VAT where applicable; C — amounts are tax-inclusive, header tax amount is 0. Mixed tax only for C (TaxType = 9, line ItemTaxType 1/2/3). See OpenAPI schemas and examples.
  • BillingNo (BillingNo): must be unique.
  • InvoiceID: send in controlled batches; avoid parallel duplicate submission for the same number range.

5. Operational and compliance notes

Topic Note
Filing timing C-type: upload within 48 hours; B-type: within 7 days (Taiwan e-invoice rules — confirm current MOF guidance).
Cancellations After shipment, cancellations may require void or allowance; cross-period rules may block void — plan allowance flows.
Allowances Amounts must match real returns; reconcile periodically.
Backups Keep invoice and allowance data for filing and audit.

6. Scenario vs API (short)

Scenario Who allocates invoice numbers? Typical API
Invoice mode Taxpayer’s own system POST /Append/Invoices (this OpenAPI bundle)
Order mode e首發票 / center Order APIs or Excel import per provider
Kiosk / payment device Usually order mode + device idempotency Provider order-mode spec

Void and allowance APIs are shared across scenarios where applicable.

Chinese scenario pages (flowcharts): Numbering model selection, Invoice-mode flow, Order-mode flow.


7. JSON field glossary (REST API)

Property names are English in JSON. Meanings below align with components.schemas in einvoice-api-openapi.en.json.

Wrapper (all POST bodies in this bundle)

JSON field English meaning Constraints / notes
CompanyID Seller GUI (uniform invoice title ID) 8-digit string; used in signature
Timestamp Epoch or provider-defined time token for signing Must be fresh; expires
Signature SHA256 hex (or provider format) Computed from GUI + secret + timestamp per spec
Data Business payload Shape depends on operation

Issue invoice (InvoiceData inside Data)

JSON field English meaning Constraints / notes
InvoiceID Full invoice number (track + serial) Max 10 chars; batch carefully
InvoiceDateTime Issue date-time ISO-like YYYY-MM-DDTHH:mm:ss
BillingNo Order / billing reference Unique per seller
InvoiceFor B2B vs B2C B or C
BuyerID Buyer GUI B2C often 0000000000
BuyerInvoiceTitle Buyer invoice title (print name) Required for B2B
BuyerName Buyer display name Required
BuyerTelNo Buyer phone SMS use
BuyerEmailAddress Buyer email Validation; bad format may be cleared / blocklisted
CheckNumber Invoice check code B2C often 9999
RandomNumber Random code on invoice B2C often 9999
PrintMark “Proof copy printed?” flag for C Y / N
TaxType Header tax category 1 taxable, 2 zero-rate, 3 exempt, 9 mixed (C only)
SalesAmount Taxable sales amount (integer) Rounded
FreeTaxSalesAmount Exempt sales total Default 0
ZeroTaxSalesAmount Zero-rate sales total Default 0
TaxAmount VAT amount B: ~5% of taxable; C: 0
TotalAmount Grand total Tax rules per B/C
CarrierType / CarrierId Carrier type / id (mobile barcode, etc.) MOF formats
NPOBAN Donation code (NPO GUI) When donating
Note Internal note / CC pattern Max length per schema
Details Line items Array of InvoiceDetailItem

Line item (InvoiceDetailItem)

JSON field English meaning Constraints / notes
DetailID Line id e.g. 0001
ProductName Description
Quantity Quantity
UnitPrice Unit price
SubTotal Line amount Quantity × UnitPrice
ItemTaxType Line tax type 1 taxable, 2 zero, 3 exempt

Issue response (InvoiceIssueResponse)

JSON field English meaning Constraints / notes
StatusCode Outcome 1 success, 0 failure
ResultMessage Human-readable result Parse on failure to avoid missed issuance

Void (CancelInvoiceData)

JSON field English meaning Constraints / notes
SellerID Seller GUI
InvoiceNumber Invoice to void
CancelDate Void timestamp
CancelReason Reason text e.g. return, order cancelled

Allowance (AllowanceData / AllowanceDetailItem)

JSON field English meaning Constraints / notes
AllowanceNumberPrefix Allowance document id prefix Unique; provider often uses time-based id
AllowanceType Direction / type Fixed 2 (seller-issued) in spec
TaxAmount Allowance VAT total Sum of taxable line taxes
TotalAmount Allowance grand total Sum of line amounts
InvoiceNumber (detail) Original invoice number
SequenceNumber Line sequence
Amount, Quantity, UnitPrice Monetary fields
ItemTaxType Line tax type
Tax Line VAT For ItemTaxType=1, typically 5% of line amount

Core API endpoint guides

Per-endpoint purpose, flow, and samples for the three paths in the English OpenAPI bundle. Field details: JSON field glossary (Chinese hub: JSON 欄位說明). Interactive reference: Swagger UI.


POST /Append/Invoices

Purpose

Invoice-mode issuance: submit pre-numbered invoice header and line items after your system allocates InvoiceID values.

When to use

  • Invoice mode (POS, ERP, custom billing) with track numbers ready
  • Issue timing and buyer/tax/line data are finalized per your contract
  • Automated or batch issuance via REST (not order-mode Excel/order APIs)

When not to use

  • Order mode (center allocates numbers) — use /Append/Order, /Append/Orders, etc. in Swagger (not in this OpenAPI JSON bundle), or Excel import
  • Before API provisioning / signing keys
  • Parallel duplicate submission for the same InvoiceID
  • Status inquiry only — use Inquire endpoints in Swagger

Call flow

  1. Provision and obtain signing key (see §Before you integrate)
  2. Build InvoiceData and Details
  3. Compute SHA256 signature; wrap CompanyID, Timestamp, Signature, Data
  4. POST /Append/Invoices
  5. Parse StatusCode, ResultMessage; on success persist InvoiceID / InvoiceNumber; on failure log and retry
flowchart LR
    A[Prepare issue data] --> B[Build JSON Data]
    B --> C[Compute signature]
    C --> D[POST /Append/Invoices]
    D --> E{StatusCode}
    E -->|1| F[Log success]
    E -->|0| G[Log ResultMessage and retry]

Request fields

Response fields

Key field Meaning
StatusCode 1 success, 0 failure
ResultMessage Outcome text — must handle failures
InvoiceID Invoice track + serial
InvoiceNumber Invoice number
InvoiceDateTime Issue date-time

Full schema: §7 Issue response.

Examples

From einvoice-api-openapi.en.json examples (sample signature is not reusable).

B2B

{
  "CompanyID": "12345678",
  "Timestamp": "1677585655",
  "Signature": "4754A5FE41749DE99E82FC5502348C69781E1026064ADF7AC",
  "Data": {
    "InvoiceID": "NX25780488",
    "InvoiceDateTime": "2025-03-17T19:43:37",
    "InvoiceFor": "B",
    "BuyerID": "87654321",
    "BuyerName": "企業買家",
    "BuyerEmailAddress": "einv@einv.tw",
    "TaxType": "1",
    "SalesAmount": 5000,
    "FreeTaxSalesAmount": 0,
    "ZeroTaxSalesAmount": 0,
    "TaxAmount": 250,
    "TotalAmount": 5250,
    "Details": [
      {
        "DetailID": "001",
        "ProductName": "商品A",
        "ItemTaxType": "1",
        "Quantity": 1,
        "UnitPrice": 5000,
        "SubTotal": 5000
      }
    ]
  }
}

B2C

{
  "CompanyID": "12345678",
  "Timestamp": "1677585655",
  "Signature": "4754A5FE41749DE99E82FC5502348C69781E1026064ADF7AC",
  "Data": {
    "InvoiceID": "NX25780489",
    "InvoiceDateTime": "2025-03-17T19:45:00",
    "InvoiceFor": "C",
    "BuyerID": "0000000000",
    "BuyerEmailAddress": "einv@einv.tw",
    "TaxType": "1",
    "SalesAmount": 2000,
    "FreeTaxSalesAmount": 0,
    "ZeroTaxSalesAmount": 0,
    "TaxAmount": 0,
    "TotalAmount": 2000,
    "Details": [
      {
        "DetailID": "001",
        "ProductName": "商品B",
        "ItemTaxType": "1",
        "Quantity": 1,
        "UnitPrice": 2000,
        "SubTotal": 2000
      }
    ]
  }
}

Error handling

  • HTTP 200 may still return StatusCode = 0 (business rejection)
  • StatusCode: 1 success, 0 failure (OpenAPI schema)
  • Full ResultMessage catalog: TODO: pending engineering Errors SSOT

POST /Update/CancelInvoices

Purpose

Void issued invoice(s) — single CancelInvoiceData object or an array for batch void.

When to use

  • Order cancelled or return within the void window
  • Correct a successfully issued invoice per tax/contract rules
  • Batch void multiple invoice numbers

When not to use

  • Cross-period cases where void is blocked — use allowance (POST /Update/AllowanceInvoice)
  • Invoice was never successfully issued
  • Partial amount adjustment — use allowance, not void
  • Order-mode invoice not yet issued — confirm status via Inquire (Swagger)

Call flow

  1. Confirm invoice number(s) and void reason
  2. Build CancelInvoiceData (object or array) in Data
  3. Sign and POST
  4. POST /Update/CancelInvoices
  5. Check StatusCode, ResultMessage (array response for batch)
flowchart LR
    A[Confirm void allowed] --> B[Build CancelInvoiceData]
    B --> C[Compute signature]
    C --> D[POST /Update/CancelInvoices]
    D --> E{StatusCode}
    E -->|1| F[Log void success]
    E -->|0| G[Log ResultMessage]

Request fields

Response fields

Key field Meaning
StatusCode 1 success, 0 failure
ResultMessage Outcome text
SellerID Seller GUI
InvoiceNumber Voided invoice number

Single object or array of objects. See §7 Issue response / void tables.

Examples

TODO: pending engineering sample payload (no void examples in OpenAPI JSON). See glossary / Swagger UI Try it out.

Error handling

  • StatusCode: 1 success, 0 failure
  • Retain ResultMessage for support and resubmission
  • Full ResultMessage catalog: TODO: pending engineering Errors SSOT

POST /Update/AllowanceInvoice

Purpose

Create allowance (credit note) against an issued e-invoice.

When to use

  • Returns, partial refunds, price adjustments
  • Cross-period when void is not allowed
  • B2B/B2C with taxable / zero / exempt / mixed lines per schema

When not to use

  • Full revoke still in void window — consider void API first
  • Original invoice not successfully issued
  • Allowance totals do not match actual returns (audit rejection)
  • Batch allowances — Swagger has /Update/AllowanceInvoices (not in this OpenAPI JSON bundle)

Call flow

  1. Confirm original invoice and allowance amounts
  2. Build AllowanceData and Details
  3. Sign and POST
  4. POST /Update/AllowanceInvoice
  5. Check StatusCode, ResultMessage; store AllowanceNumber on success
flowchart LR
    A[Confirm original invoice] --> B[Build AllowanceData]
    B --> C[Compute signature]
    C --> D[POST /Update/AllowanceInvoice]
    D --> E{StatusCode}
    E -->|1| F[Store AllowanceNumber]
    E -->|0| G[Log ResultMessage]

Request fields

Response fields

Key field Meaning
StatusCode 1 success, 0 failure
ResultMessage Outcome text
SellerID Seller GUI
AllowanceNumber Allowance document id

See §7 Allowance response in Chinese hub response tables.

Examples

TODO: pending engineering sample payload (no allowance examples in OpenAPI JSON). See glossary / Swagger UI Try it out.

Error handling

  • StatusCode: 1 success, 0 failure
  • Header tax/totals must match line sums per OpenAPI descriptions
  • Full ResultMessage catalog: TODO: pending engineering Errors SSOT

POST /Append/PrintInvoices

OpenAPI JSON: Swagger-only (public). Details in Swagger UI.
Scenario: order mode (system numbering) + cloud thermal receipt printing.

Purpose

After e首發票 issues the invoice with system-assigned numbers (order mode), the cloud prepares thermal receipt layout and print payload, and this API enqueues the job in the cloud print queue. A print server agent at the store polls the queue and sends the job to the configured thermal printer (by IP / printer ID).

Compared with POST /Append/Order, this API also triggers the print queue on success (PrintMark is set to Y by system logic; carrier fields are cleared — see Print FAQ (Chinese)).

When to use

  • Store POS or convenience retail: issue and print paper proof copy (often B2C / C-class) in one step
  • Cloud printing, thermal printers, and print server agent are already configured
  • Multiple thermal printers; route output with PrinterNo
  • Optional SalesID (book / split-track ID) so several printers can share the same numbering segment

When not to use

  • Invoice mode (you assign numbers) — use POST /Append/Invoices; reprint via POST /Update/RePrint or /Update/SecPrint
  • E-invoice / carrier only, no paper — use POST /Append/Order or /Append/Orders
  • Printers or print server not configured

Cloud print flow

sequenceDiagram
    participant SRC as Source system
    participant API as /Append/PrintInvoices
    participant SIV as Issue and numbering
    participant QUEUE as Cloud print queue
    participant AGENT as Print server agent
    participant PRINTER as Thermal printer

    SRC->>API: Order data + PrinterNo (+ optional SalesID)
    API->>SIV: Validate and issue
    SIV->>QUEUE: Enqueue formatted print job
    API-->>SRC: StatusCode / ResultMessage / invoice no.
    AGENT->>QUEUE: Poll for jobs
    QUEUE-->>AGENT: Print payload
    AGENT->>PRINTER: Print to target device

Request highlights

Field Label Required Notes
PrinterNo Printer ID Yes (cloud print) Must match backend device setup
SalesID Split-track / book ID No Optional; same value across printers to share one numbering segment
PrintMark Proof printed flag Set to Y automatically for this API
InvoiceID Invoice track + serial No Not required upfront in order mode

Top-level body is a JSON array per Swagger (one or many orders). Signing: same as §2.


8. Source and versioning

  • Derived from the same Inbox-sourced material as the Chinese API guide.
  • English OpenAPI is maintained in parallel; bump info.version and both language files together on contract changes.

F0401 and issuance checks (English)

Topic Link
Full F0401 field table (English) f0401-field-mapping.md
Invoice validation rules (English) invoice-issuance-validation.md
F0401 key fields only (English) f0401-field-reference.md

Version history

Version Date Author Changes
v1.0 2026-05-15 SystemLead Initial English integration guide; glossary; links to EN OpenAPI.
v1.1 2026-05-15 SystemLead Links to English F0401 full mapping and invoice validation pages.
v1.2 2026-06-08 SystemLead Swagger-first navigation; OpenAPI files in Advanced block; removed English YAML.
v1.3 2026-06-08 SystemLead Removed Chinese YAML; OpenAPI JSON only (EN/ZH).
v1.4 2026-06-08 AI API-P1: Core API endpoint guides (3 paths) — purpose, flow, examples, error handling.
v1.5 2026-06-08 AI API-P2a: Swagger-only extended endpoints table (18 paths).
v1.6 2026-06-08 AI API-P2b: 18 Swagger-only endpoints approved public; phased OpenAPI JSON note.
v1.7 2026-06-10 AI PrintInvoices: cloud thermal print purpose, flow, PrinterNo / SalesID, endpoint guide.