Skip to main content

E-Invoicing | India GST (IRP / NIC)

This is the India country pack for the ECOSIRE GCC E-Invoicing | Core Engine. It adds full India GST clearance-model (CTC) e-invoicing via the NIC Invoice Registration Portal (IRP): Schema INV-01 JSON document building, IRN generation and cancellation, standalone e-way bill generation, GSTIN master lookup, and a signed QR payload ready for invoice PDF printing — all backed by a per-submission state machine and append-only audit log.

This pack requires the core engine (ecosire_einvoice_core). Install the core engine first, then install this pack on top.

Compatibility: Odoo 17 / 18 / 19 (Community or Enterprise) Price: $349 (one-time, requires core engine $499) License: Up to 3 domain activations Category: Accounting / Localizations / EDI Authority: NIC — National Informatics Centre, Government of India

Sandbox verification required before production

The live-transmission path (NIC auth handshake, IRN generation, cancellation, e-way bill) is built to the NIC API contract. Because the NIC uses a double-layer crypto stack (RSA-wrapped AES session key + AES payload encryption + JWT response) and the exact path/schema details require a registered NIC sandbox account, live API calls are blocked with an actionable UserError until you set the Sandbox Verified flag on the configuration record. Verify on https://einv-apisandbox.nic.in before switching to production.

Mandate threshold (as of 2026)

India's e-invoicing mandate applies to all GST-registered taxpayers with annual turnover above Rs 5 crore (August 2023 phase, per CBIC Notification amendments). A future phase is expected to bring all taxpayers in. If your customer is in scope, the module is needed now.

What it does​

  • Schema INV-01 (v1.1) JSON document builder — assembles TranDtls, DocDtls, SellerDtls, BuyerDtls, ItemList (HSN/SAC, IGST/CGST/SGST/CESS), ValDtls, and optional Export/E-Way Bill sections per the NIC/GSTN standard.
  • IRN generation — submits to POST /eicore/v1.03/Invoice and receives the 64-char SHA-256 IRN, Acknowledgment Number, Acknowledgment Date, SignedQRCode (ready for printing), and SignedInvoice (JWT).
  • IRN cancellation — calls POST /eicore/v1.03/Invoice/Cancel with reason code and remarks; enforces the hard 24-hour cancellation window before any API call. After 24 hours the module blocks cancellation with a clear error and instructs the user to issue a credit note instead.
  • Get IRN Details — retrieves a previously generated IRN from GET /eicore/v1.03/Invoice/irn/{irn}.
  • Standalone E-Way Bill generation — calls POST /eiewb/v1.03/ewaybill for inter-state goods shipments above Rs 50,000 where an IRN already exists.
  • GSTIN master lookup — validates buyer/seller GSTINs against the NIC registry via GET /eivital/v1.04/Master/gstin/{gstin} and auto-fills legal name and address on the invoice.
  • Signed QR payload capture — stores the verbatim SignedQRCode string returned by the IRP on each submission record for printing on invoice PDFs.
  • Draft / Submitted / Cleared / Rejected / Cancelled state machine — each invoice has exactly one submission record tracking its IRP lifecycle with chatter posts at every transition.
  • Append-only audit log — each attempt appends a einvoice.in.audit.log row (action, note, timestamp). Non-admin users have no write or unlink access to audit rows.
  • Manual retry + scheduled cron — rejected submissions can be retried manually or automatically via the _cron_retry_rejected scheduled action (processes up to 50 per run; skips cleanly when the license is inactive).
  • B2B/B2C subtype detection — invoices for buyers with a GSTIN are classified as B2B (in-scope for IRN); invoices without a buyer GSTIN are B2C (excluded from the mandate; no IRN generated).
  • Multi-company isolation — one configuration record per company; record rules restrict data to the company in context.
  • License enforcement — every entry point (configuration write, connection test, IRN generation, cancellation, retry) is decorated with @require_license('ecosire_einvoice_in', ...).

Requirements​

RequirementDetail
Odoo17.0, 18.0, or 19.0 (Community or Enterprise)
Core engineecosire_einvoice_core installed (see core engine docs)
License moduleecosire_license_client (installed automatically)
Python packagesNo additional packages beyond what the core engine requires
ECOSIRE licenseAn active license for ecosire_einvoice_in
NIC IRP accessA registered NIC IRP account (sandbox: einv-apisandbox.nic.in; production: einvoice1.gst.gov.in) with issued aspid, IRP username/password, and the IRP RSA public key

Installation​

  1. Install and configure the GCC E-Invoicing | Core Engine first.
  2. Download this pack's ZIP from your ECOSIRE Dashboard and extract it to your addons directory: 
    unzip ecosire-einvoice-in-*.zip -d /opt/odoo/addons/
    sudo systemctl restart odoo
  3. In Odoo go to Apps, click Update Apps List.
  4. Search for ECOSIRE E-Invoicing | India GST (IRP / NIC) and click Install (the core engine and ecosire_license_client are installed automatically if not already present).
  5. After installation, activate your ECOSIRE license at Settings > ECOSIRE License before using any e-invoicing feature.

Configuration and Credentials​

Step 1: Activate your ECOSIRE license​

Navigate to Settings > ECOSIRE License. Enter your license key and click Activate. All India IRP entry points — including configuration writes — are blocked until the license is active.

Step 2: Obtain NIC IRP credentials​

You need credentials from the NIC Invoice Registration Portal. There are two routes:

Direct API access (taxpayer):

  1. Register your GST-registered entity at einvoice1.gst.gov.in.
  2. Request API credentials. NIC issues an aspid, a GSTIN-based username, and a password.
  3. Download the IRP RSA public key (PEM format) from the portal's documentation section — this key is used to encrypt the App Key during authentication. Do not hardcode it; fetch the current key from the portal.

Via GSP (GST Suvidha Provider): If you route through a GSP (ClearTax, IRIS GST, Cygnet Infotech, Masters India, etc.), obtain the aspid, credentials, and any GSP-specific base URL from your GSP. The module configuration accepts the same credential fields regardless of whether you access NIC directly or via a GSP.

Sandbox first

Always configure and test on the NIC sandbox (https://einv-apisandbox.nic.in) before switching to production. The sandbox provides test GSTINs and accepts the same Schema INV-01 payload. Registration for sandbox credentials is done through einvoice1.gst.gov.in.

Step 3: Enter credentials in Odoo​

Navigate to India E-Invoicing > Configuration (or Accounting > Configuration > India IRP). One configuration record is created per company.

FieldValue to enter
EnvironmentSandbox (start here) or Production
ASP ID (aspid)The aspid header value issued by NIC or your GSP
IRP UsernameYour GSTIN-based IRP API username
IRP PasswordYour IRP API password (stored encrypted, never displayed in logs)
App KeyThe AES session key you generate per-session (RSA-encrypted with the IRP public key before transmission)
IRP RSA Public Key (PEM)Paste the IRP-provided RSA public key used to encrypt the App Key
Taxpayer GSTIN15-character GSTIN of the API user (your company's GSTIN)

Click Test Connection to attempt the NIC authentication handshake. On success, tick Sandbox Verified to enable live transmission.

Sandbox Verified gate

The Sandbox Verified checkbox on the configuration record is the only gate that enables live API calls. Until it is ticked, every submission attempt raises a clear UserError explaining the requirement. This prevents accidental production calls before your integration is validated end-to-end.

Step 4: Check company and partner data​

Before generating IRNs in production, verify:

  • Company GSTIN: Set the company's VAT/GSTIN at Settings > Companies > [Your Company] > Tax ID.
  • Buyer GSTIN: For B2B customers, set the partner's VAT/GSTIN on the contact record. Partners without a GSTIN are treated as B2C and are excluded from the IRN mandate.
  • HSN/SAC codes: Every product line must carry an HSN or SAC code. The INV-01 builder includes these in each ItemList entry; invoices with missing HSN codes will fail the IRP's validation.

Usage​

Generating an IRN​

  1. Open a confirmed (posted) customer invoice or credit note in Odoo.
  2. Click Generate India IRN from the invoice action bar.
  3. The module builds the Schema INV-01 JSON payload (you can inspect it in the linked submission record under INV-01 Payload), marks the submission as Submitted, and calls the NIC IRP.
  4. On success the submission moves to Cleared and the following fields are populated on both the submission and the invoice:
    • IRN — the 64-char SHA-256 hash
    • Ack No. / Ack Date — the acknowledgment number and date returned by the IRP
    • Signed QR Code — the verbatim SignedQRCode string for printing on the invoice PDF
    • Signed Invoice (JWT) — the full signed invoice for archiving
    • E-Way Bill No. / Valid Till — if transport details were present in the payload
  5. If the IRP rejects the document, the submission moves to Rejected with the IRP error code and message captured in Last Error.

Retrying a rejected submission​

Open the rejected submission record and click Retry. The module resets the state to Draft and re-submits. Alternatively, the _cron_retry_rejected scheduled action retries up to 50 rejected submissions automatically.

Cancelling an IRN​

Open the cleared submission. If the IRN was generated within the last 24 hours, the Cancellable indicator is true and the Cancel IRN button is available.

  1. Select a Cancellation Reason: 1 - Duplicate, 2 - Data Entry Mistake, 3 - Order Cancelled, or 4 - Others.
  2. Optionally enter Cancellation Remarks (maximum 100 characters).
  3. Click Cancel IRN.

If the 24-hour window has passed, the module raises a clear error and instructs you to issue a credit note instead. This is a hard NIC business rule — the IRP blocks cancellation requests after 24 hours.

E-Way Bill generation​

For inter-state goods shipments above Rs 50,000 where an IRN already exists and the E-Way Bill was not generated inline with the IRN:

  1. Open the cleared submission record.
  2. Populate the transport details fields (vehicle number, transporter GSTIN, distance).
  3. Click Generate E-Way Bill to call POST /eiewb/v1.03/ewaybill. The E-Way Bill number and validity are stored on the submission.

E-Way Bills can also be generated inline at IRN time by including the EwbDtls section in the INV-01 payload — the module populates this automatically when transport details are present on the invoice.

Viewing the audit log​

Every submission attempt, state transition, retry, and cancellation appends an immutable row to the Audit Log tab on the submission form. Rows include the action name, a note, and the timestamp. Non-admin users cannot edit or delete audit rows.

Troubleshooting / FAQ​

IssueSolution
"License is not active" on any actionActivate your ECOSIRE license at Settings > ECOSIRE License before using India IRP features
"Sandbox not verified" UserErrorTick Sandbox Verified on the India IRP configuration record after completing a successful test connection on the NIC sandbox
Connection test fails — auth errorVerify aspid, IRP username/password, GSTIN, and the IRP RSA public key PEM on the configuration record; check that your NIC API credentials have not expired
"Buyer GSTIN is required for B2B e-invoices"Set the VAT/GSTIN field on the customer contact in Odoo; invoices for buyers without a GSTIN are treated as B2C and excluded from IRN generation
"Supplier GSTIN is required"Set the company's Tax ID (GSTIN) at Settings > Companies
"Invoice date is required"The posted invoice must have an invoice date; this maps to DocDtls.Dt in INV-01
IRN rejected — error code 2150 (duplicate IRN)The IRP has already registered this invoice number; retrieve the existing IRN using Get IRN Details instead of generating a new one
IRN rejected — error code 2176 (invalid GSTIN)The buyer's GSTIN is not active in the GSTN registry; use the GSTIN lookup feature to verify the buyer's status before re-submitting
"IRN is past the 24-hour cancellation window"Issue a credit note in Odoo; the NIC IRP cannot cancel IRNs after 24 hours of generation
E-Way Bill not generated with IRNTransport details (vehicle number, transporter GSTIN) were missing from the invoice at IRN time; use Generate E-Way Bill on the cleared submission to add it separately
B2C invoice — no IRN generatedThis is correct behavior: India's e-invoicing mandate covers B2B and B2G only; customers without a GSTIN are B2C and are not submitted to the IRP
Cron not retrying rejected submissionsConfirm the _cron_retry_rejected scheduled action is active (Settings > Technical > Automation > Scheduled Actions); also verify the ECOSIRE license is active, as the cron skips when unlicensed

API Reference​

FieldValue
Auth methodNIC two-step: AppKey RSA-encrypted with IRP public key → session token; AES-256 payload encryption per call
Sandbox base URLhttps://einv-apisandbox.nic.in
Production base URLhttps://einvoice1.gst.gov.in
Auth endpointGET /eivital/v1.04/Auth (REPORTED — verify at NIC sandbox)
IRN generatePOST /eicore/v1.03/Invoice (REPORTED)
IRN cancelPOST /eicore/v1.03/Invoice/Cancel (REPORTED)
IRN detailsGET /eicore/v1.03/Invoice/irn/{irn} (REPORTED)
E-Way BillPOST /eiewb/v1.03/ewaybill (REPORTED)
GSTIN lookupGET /eivital/v1.04/Master/gstin/{gstin} (REPORTED)
Document formatJSON — Schema INV-01 Version 1.1 (REPORTED current; verify at IRP portal)
Key config fieldsaspid, username, password, app_key, irp_public_key, gstin
Token lifetime~6 hours (REPORTED)
Cancellation window24 hours (confirmed hard NIC rule)

Note on "REPORTED" endpoints: All NIC API paths are sourced from publicly available NIC documentation references. The NIC portal requires in-India network access or registered credentials for authoritative verification. Before going live, cross-reference every endpoint against the NIC API Technical Specification PDF at einvoice1.gst.gov.in/Others/Docs.

Support​

Last updated on