e首發票 API — integration guide (English)
Summary
Entry page for REST API integration: provisioning, OpenAPI 3.0 (English bundle), Swagger UI, SHA256 signing, environments, audit behaviour, and a concise JSON field glossary aligned with the published schemas.
Legal notice
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) Read OpenAPI + signing → (3) Choose scenario (invoice-number source) → (4) Develop against Swagger / stage → (5) Handle errors and audit rules before production.
1. OpenAPI specification (English bundle)
The machine-readable contract is OpenAPI 3.0. Two human languages are published as separate files so overseas teams can pin the English bundle without mixing locales in one file.
Keep English and Chinese OpenAPI files in sync when the contract changes (same openapi, paths, components.schemas structure; descriptions translated).
Primary paths (frequently used)
| 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 exist on the production Swagger surface; use Swagger for the full list and try-it-out forms.
Swagger UI (interactive)
| 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). |
Append / Inquire / Update groupings in Swagger match the tables in the Chinese API page §1.
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.
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
- Field mapping from your order/ERP to invoice fields (B2B/B2C, tax type, carrier).
- Issue timing (payment, shipment, service completion) to reduce tax-period risk.
- Error handling: retries, alerts, manual fix for failures — always handle
StatusCode / ResultMessage to avoid missing invoices.
- 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.yaml.
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 |
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)
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. |