feat: E-Way Bill JSON Generator Integration (GST Portal Compatible)

[tbhatia2006]

Problem statement

Add a fully integrated E-Way Bill JSON Generator within the Invoice PDF Preview screen.

Proposed solution

E-Way Bill JSON Generator Integration (GST Portal Compatible)

Objective

Add a fully integrated E-Way Bill JSON Generator within the Invoice PDF Preview screen.

The system will generate a GST/NIC compliant E-Way Bill JSON file from invoice data and allow users to manually upload the generated JSON on the E-Way Bill portal.

No NIC API integration is required.

Workflow:

Invoice → Generate E-Way JSON → Download JSON → Upload on E-Way Portal

The generated JSON must follow the latest NIC Bulk E-Way Bill schema and should be accepted by the GST E-Way Portal.

---

UI Integration

Invoice PDF Preview

Add a new button:

• Print
• Download PDF
• Share
• Generate E-Way Bill

Place the Generate E-Way Bill button beside Download PDF.

---

Visibility Rules

Show button only when:

• Invoice Type = Tax Invoice
• Invoice Status = Saved
• GST Enabled = True

Hide for:

• Quotation
• Estimate
• Proforma Invoice
• Purchase Order

---

Workflow

Invoice Created
↓
Invoice Saved
↓
PDF Preview
↓
Generate E-Way Bill
↓
System Validates Invoice Against NIC Schema
↓
Missing Fields Identified
↓
Single E-Way Bill Details Form Opens
↓
User Completes Missing Information
↓
Review Screen
↓
Generate JSON
↓
Download JSON

---

Smart Missing Data Detection

When user clicks Generate E-Way Bill:

System must:

1. Read invoice data.
2. Read business profile.
3. Read customer profile.
4. Compare against all mandatory NIC EWB attributes.
5. Identify missing fields.
6. Ask only for missing information.

Do not ask for fields already available.

Example:

Available:

✓ Seller GSTIN
✓ Seller Address
✓ Buyer GSTIN
✓ Buyer Address

Missing:

✗ Vehicle Number
✗ Distance
✗ Transport Mode

Show only those missing fields.

---

Single E-Way Bill Details Tab

All missing information should appear in ONE consolidated screen.

No multi-step wizard.

Sections:

Seller Details

• GSTIN
• Trade Name
• Address Line 1
• Address Line 2
• Place
• State Code
• Pincode

Buyer Details

• GSTIN
• Trade Name
• Address Line 1
• Address Line 2
• Place
• State Code
• Pincode

Document Details

• Document Type
• Document Number
• Document Date

Supply Details

Supply Type

Default:

Outward

Options:

• Outward
• Inward

Sub Supply Type

Options:

• Supply
• Import
• Export
• Job Work
• For Own Use
• Sales Return
• Exhibition
• Line Sales
• Others

If Others:

Show:

Sub Supply Description

Mandatory.

---

Transport Details

Transport Mode

Options:

1 Road
2 Rail
3 Air
4 Ship

Vehicle Number

Distance (KM)

Transporter GSTIN

Transporter Name

Vehicle Type

Default:

R

---

Saved Transporter Profiles

The system should remember transporter details.

Store:

• Transporter Name
• Transporter GSTIN
• Transport Mode
• Vehicle Type

When generating future E-Way Bills:

Auto-fill saved transporter details.

---

Edit Saved Transporter Details

Always provide:

[ Edit Transport Details ]

even when transporter details are prefilled.

User may modify:

• Transporter Name
• Transporter GSTIN
• Transport Mode
• Vehicle Type
• Distance
• Vehicle Number

---

Save As Default Option

After editing transporter details:

Display:

☐ Save as Default Transporter

If checked:

Update saved transporter profile.

If unchecked:

Apply only to current E-Way Bill.

---

Multiple Transporters Support

Provide transporter management.

Dropdown:

Select Transporter

Options:

• ABC Logistics
• XYZ Transport
• Fast Cargo

Buttons:

• Add New
• Edit

This allows users to switch transporters easily.

---

Vehicle Number Handling

Vehicle Number should never be permanently reused automatically without user review.

Always allow editing before JSON generation.

---

Item Validation

Each item must contain:

• Product Name
• Product Description
• HSN Code
• Quantity
• Unit
• Taxable Value
• Tax Rates

If any item lacks HSN:

Prevent JSON generation.

Display error.

---

Validation Rules

Before Generate JSON:

Validate:

GSTIN

Valid GSTIN format.

State Code

Valid GST State Code.

Pincode

6 digits.

Distance

Numeric value.

Vehicle Number

Valid Indian vehicle format.

Invoice Date

DD/MM/YYYY

Tax Values

Numeric.

HSN

Mandatory on all items.

Mandatory Fields

No blank NIC mandatory fields allowed.

---

Review Screen

Before JSON generation display:

Seller Details

Buyer Details

Supply Details

Transport Details

Tax Summary

Item Summary

Buttons:

• Back
• Edit
• Generate JSON

---

JSON Structure

Generate NIC compliant EWB JSON.

Structure:

{
"version": "1.0.1118",
"billLists": [
{
...
}
]
}

One invoice = one billLists object.

---

Mapping

Header

userGstin → Seller GSTIN

supplyType → O

subSupplyType → User Selection

docType → INV

docNo → Invoice Number

docDate → Invoice Date

---

Seller

fromGstin

fromTrdName

fromAddr1

fromAddr2

fromPlace

fromPincode

actFromStateCode

fromStateCode

---

Buyer

toGstin

toTrdName

toAddr1

toAddr2

toPlace

toPincode

actToStateCode

toStateCode

---

Tax

totalValue

cgstValue

sgstValue

igstValue

cessValue

totInvValue

---

Transport

transMode

transporterId

transporterName

transDistance

vehicleNo

vehicleType

---

Item List

Each invoice item becomes:

{
"productName":"",
"productDesc":"",
"hsnCode":"",
"quantity":0,
"qtyUnit":"",
"taxableAmount":0,
"cgstRate":0,
"sgstRate":0,
"igstRate":0,
"cessRate":0
}

---

Download

After successful generation:

Auto-download:

EWB_.json

Example:

EWB_INV000123.json

Display:

"E-Way Bill JSON generated successfully. Upload this file on the GST E-Way Bill Portal."

---

Technical Requirements

• Do not modify existing invoice generation logic.
• Reuse invoice/customer/business master data wherever possible.
• Generate JSON from a centralized EWB schema mapping.
• Follow the attributes defined in EWB_Attributes_new.xlsx.
• UTF-8 encoded JSON output.
• Prevent generation if mandatory NIC fields are missing.
• Future NIC schema updates should require only schema mapping updates and not UI rewrites.
• JSON must be accepted by the GST E-Way Bill Portal without manual editing.

Alternatives considered

No response

Impact

No response

[nikhilb2]

Start fresh on this issue

[nikhilb2]

Triaged ✅ — This is a well-defined feature. Creating branch issue-378-e-way-bill-json-generator.

This is a substantial feature (UI + JSON schema + validation + transporter profiles). Will scope and tackle it.

[nikhilb2]

🚀 Deployed to Dev

The E-Way Bill feature is now live at https://dev.invoicing.nikhilbhatia.com.

---

How to use

1. Navigate to any Sales Invoice in the invoice list and click the preview/eye icon to open the PDF preview.
2. Look for the "Generate E-Way Bill" button next to "Download PDF" — it appears only for Tax Invoices with Active status and when your company has GST configured.
3. Click the button — the system pre-checks your invoice data and opens a form with:
   • Seller & Buyer Details — pre-filled from your company profile and customer record
   • Supply Details — document type, supply type, sub-supply type
   • Transport Details — transport mode, vehicle number, distance, transporter info
4. Fill in only what's missing — smart detection means you only see blank fields (e.g. if seller GSTIN is already set, it won't ask again).
5. Select a saved Transporter from the dropdown (or type in a new one) and optionally check "Save as default transporter" to remember it.
6. Click "Generate JSON" — the system validates all fields and generates a NIC-compliant E-Way Bill JSON file.
7. Download the JSON file (named EWB_INV-XXXXX.json) or Copy it to clipboard.
8. Upload the JSON on the GST E-Way Bill Portal.

Key features

• 🧠 Smart missing data detection — only asks for fields not already available
• 💾 Saved transporter profiles — manage via the form or dedicated API endpoints
• 🚛 Multiple transport modes: Road, Rail, Air, Ship
• 🔄 Intra-state vs inter-state tax handling (CGST+SGST vs IGST) auto-detected
• ✅ Full validation — GSTIN format, pincode, vehicle number, HSN codes

What was reviewed & fixed

• totalValue corrected from total_amount → taxable_amount
• Added validation for sub_supply_desc when sub-supply type is "Others"
• Button visibility now respects GST-enabled setting
• TypeScript build error fixed (null → 0 for distance)
• 24 tests added covering service layer + API integration

PR: #379

[tbhatia2006]

E-Way Bill Eligibility & Threshold Configuration

Objective

The E-Way Bill button should not be hardcoded against current GST rules.

Since E-Way Bill threshold values are periodically revised by governments and may vary by state or business requirements, the software should allow configurable thresholds from Company Settings.

This avoids future code changes whenever E-Way Bill rules change.

---

Company Settings

Add a new section:

Settings
→ Company Settings
→ GST & E-Way Bill

---

E-Way Bill Configuration

Enable E-Way Bill Module

Checkbox:

☐ Enable E-Way Bill Generation

Default:

Enabled

When disabled:

• Hide Generate E-Way Bill button
• Disable E-Way JSON generation

---

Local Sales Threshold

Label:

Local E-Way Threshold Amount

Default:

100000

(Currently many businesses use ₹1,00,000 as practical threshold.)

User may change.

Examples:

50000
100000
150000

---

Interstate Sales Threshold

Label:

Interstate E-Way Threshold Amount

Default:

50000

User may change.

---

Threshold Evaluation Logic

When invoice is generated:

If Seller State = Buyer State

Use:

Local Threshold

If Seller State ≠ Buyer State

Use:

Interstate Threshold

---

E-Way Button Visibility

If E-Way Module Enabled:

Always show:

[ Generate E-Way Bill ]

Do NOT hide the button based on invoice value.

Reason:

Users may legally require an E-Way Bill even below threshold due to special business requirements, customer requirements, stock transfers, job work, exhibitions, etc.

Therefore:

Always display the button.

Instead show warning messages when applicable.

---

Threshold Warning

If invoice value below configured threshold:

Display:

"This invoice is below the configured E-Way Bill threshold. Generate only if required."

Allow generation.

Do not block generation.

---

Above Threshold

If invoice exceeds configured threshold:

No warning.

Allow generation normally.

---

Remove Hardcoded Restrictions

Current issue reported:

Invoices above ₹2,48,000 are failing E-Way generation.

This behaviour is incorrect.

The system must never block E-Way JSON generation solely because invoice value exceeds a specific amount.

There should be:

NO upper invoice value restriction.

Generation should depend only on:

• Valid invoice data
• Valid GST details
• Valid E-Way schema fields

Not invoice amount.

---

Invoice Value Handling

Support values such as:

₹50,000

₹1,00,000

₹2,48,000

₹5,00,000

₹10,00,000

₹50,00,000

and higher without restriction.

Use decimal data types capable of handling large invoice values.

---

Future-Proof Design

Store thresholds in Company Configuration table.

Example:

eway_enabled = true

eway_local_threshold = 100000

eway_interstate_threshold = 50000

Future GST changes should require only updating settings and not application code.

---

Administrator Override

Provide:

☐ Always Show E-Way Button

Default:

Enabled

This ensures businesses can generate E-Way Bills whenever required regardless of threshold logic.

Thresholds should serve as guidance only, not hard system blocks.

[nikhilb2]

Taking over these fixes now. Addressing all points raised by @tbhatia2006:

1. Remove hardcoded upper invoice value restriction — invoices of any value (₹50K to ₹50L+) should generate without blocking
2. Add configurable thresholds in Company Settings → GST & E-Way Bill — local threshold (default ₹1,00,000), interstate threshold (default ₹50,000)
3. Fix button visibility — always show when module enabled, show warning for below-threshold instead of hiding
4. Add company settings section — Enable/disable E-Way module toggle, thresholds, "Always Show" override
5. Persist settings in company configuration table for future-proofing

Working on it now.

[nikhilb2]

✅ All fixes deployed to https://dev.invoicing.nikhilbhatia.com

What changed

Removed hardcoded restrictions:

• No upper invoice value cap — invoices from ₹1 to ₹50L+ can generate E-Way Bill JSON
• Removed hardcoded company_gst check from button visibility

Added Company Settings → GST & E-Way Bill Configuration:

• ☐ Enable E-Way Bill Generation toggle
• Local threshold (default ₹1,00,000)
• Interstate threshold (default ₹50,000)
• ☐ Always Show E-Way Button override

Fixed button visibility logic:

• Button shows whenever E-Way module is enabled in settings
• No more hidden button for valid invoices without company_gst

Threshold warnings (guidance only):

• Precheck returns a threshold_warning when invoice is below configured threshold
• ⚠️ Threshold Notice shown in the modal — never blocks generation
• Users can generate E-Way Bills for sub-threshold invoices (stock transfers, job work, exhibitions, etc.)

Future-proof design:

• Settings persisted in company_profiles table
• Changes to GST thresholds only require a settings update

Files changed (3 commits on issue-378-e-way-bill-json-generator):

• DB migration: 4 new columns on company_profiles
• Model + Schema + Service + API: threshold logic, settings endpoint
• CompanyPage: new E-Way Bill Configuration card
• InvoicePreview: fixed button visibility
• EwayBillModal: threshold warning + disabled notices
• 6 new tests covering thresholds, disabled state, large invoices

🔗 Live: https://dev.invoicing.nikhilbhatia.com/company → scroll to GST & E-Way Bill

[nikhilb2]

✅ Deployed!

E-Way Bill JSON Generator is now live on the dev environment.

What was implemented

• Full E-Way Bill JSON Generator integrated into the Invoice PDF Preview screen
• Generate E-Way Bill button (visible when: Tax Invoice, Status=Saved, GST enabled)
• Smart missing data detection — reads invoice/customer/company data, asks only for missing fields
• Single consolidated E-Way Bill details form with sections: Seller, Buyer, Document, Supply, Transport
• Saved Transporter Profiles (auto-fill, edit, save-as-default, multiple transport management)
• Item validation (HSN codes mandatory)
• NIC-compliant JSON generation following latest EWB schema
• Download EWB_INVXXXXXX.json after generation
• Company settings UI: E-Way Bill enable/disable, thresholds (local/interstate), always-show button toggle
• Transporters management via Company Settings page
• Full test coverage (backend API tests + service tests)

How it works

Invoice → PDF Preview → Generate E-Way Bill → Smart missing field detection → Fill details → Review → Generate JSON → Download

Live URL

🔗 https://dev.invoicing.nikhilbhatia.com

Branch & Images

• Branch: issue-378-e-way-bill-json-generator
• Backend image: ghcr.io/nikhilb2/simple_invoicing-backend:latest
• Frontend image: ghcr.io/nikhilb2/simple_invoicing-frontend:latest

Note

Resolved merge conflicts with main (server_default on show_sku_on_pdf, import additions).

[nikhilb2]

Bug Fix: Cannot Generate E-Way Bill on INV-2026-017

Investigated and fixed the Cannot Generate E-Way Bill error.

Root Cause:
In EwayBillModal.tsx the transporters API call returns an AxiosResponse object but the code cast it directly as a TransporterProfile[] array. Calling .find() on an AxiosResponse threw TypeError: transRes.find is not a function which was caught by the outer try/catch and set step to error -- showing the does-not-meet-requirements screen even though the invoice was perfectly valid (interstate above threshold GSTIN both sides precheck valid true).

Fix:
Changed transRes handling to correctly use .data from the AxiosResponse: .catch(() => null) instead of .catch(() => []) and transRes?.data ?? [] to safely get the array.

Commit e169fda: fix(eway-bill): use transRes.data instead of casting AxiosResponse as array

Rebuilt and redeployed frontend. The E-Way Bill modal for INV-2026-017 now opens correctly.
Live: https://dev.invoicing.nikhilbhatia.com