e-Invoice API: Overview, Onboarding, Best Practices, and Version Management

1. Introduction to e-Invoice

The implementation of ‘e-Invoicing’ or ‘electronic invoicing’ has been approved by the GST Council in a phased manner for reporting Business to Business (B2B) invoices to the GST System. This initiative started voluntarily on 1st January 2020. The National Informatics Centre (NIC) is the first Invoice Registration Portal (IRP) responsible for providing e-Invoice registration services.

To facilitate integration with the e-Invoice system, NIC has made the registration services available through API mode and other modes. This allows taxpayers and GST Suvidha Providers (GSPs) to seamlessly integrate their business systems and processes with the e-Invoice system using these APIs. Through the APIs, taxpayers and GSPs can register the invoices generated or prepared on their systems, ensuring a streamlined and efficient invoicing process.

The introduction of e-Invoicing aims to bring greater automation, transparency, and accuracy to the invoicing process, reducing the risk of errors and facilitating easier compliance with GST regulations. By leveraging APIs and integrating with the e-Invoice system, taxpayers and GSPs can take advantage of the seamless benefits of electronic invoicing.

2. Overview of e-Invoice API

E-invoice APIs are crucial in facilitating communication and data exchange between Taxpayers or GSP systems and the e-Invoice system. These APIs adhere to specific standards and formats that define the API structure exposed by the e-Invoice system. The implementation of E-Invoice APIs follows the principles of RESTful Web Services.

To access and utilize the APIs, authentication is a prerequisite. Users must initiate the authentication process by calling the Authentication API and obtaining a token. This token must be included in subsequent API calls to ensure valid and authorized access. Detailed information about the Authentication API can be found in the API documentation.

During the authentication process, it is essential to encrypt the password and AppKey using the provided public key from the e-Invoice system. This encryption adds an extra layer of security to protect sensitive information.

Successful authentication also grants the user a Session Encryption Key (SEK). This key encrypts request payloads and decrypts responses from the e-Invoice system. The encryption process employs a symmetric algorithm to ensure data confidentiality.

Specific API calls, such as “Generate – IRN” and “Get IRN Details,” return responses that include digitally signed e-Invoice and QR-Code data. This digital signature is achieved using JSON Web Token (JWT) and JSON Web Signature (JWS) with the “SHA256RSA” algorithm.

For more detailed information on the above topics, including encryption, digital signatures, and API specifics, please refer to the API documentation available on this portal. It provides comprehensive guidelines and instructions to utilize the e-Invoice APIs and leverage their capabilities effectively.

Following HTTP methods are used across the APIs

HTTP Method
GET	To fetch data from e-Invoice system
POST	To submit data to e-Invoice system

3. Benefits and Advantages of e-Invoice API

The usage of these APIs brings several benefits to both Tax Payers and GST Suvidha Providers (GSP):

1. Seamless Integration: These APIs facilitate the seamless integration of the Tax Payer’s ERP/Accounting system with the e-Invoice system. This integration ensures smooth data flow and exchange between the systems, eliminating manual intervention.
2. Efficient Record-keeping: Tax Payers can conveniently record the Invoice Registration Number (IRN) and ACK number obtained from the registration of e-Invoices at the GST System directly into their online systems. This eliminates the need for duplicate or double entries of invoices, saving time and reducing the chances of errors.
3. Data Accuracy: By passing the sales details from the Tax Payer’s computerized system to the e-Invoicing system for IRN generation, the APIs help eliminate errors that may occur during manual data entry for e-Invoices. This ensures accurate and consistent data across systems.
4. Streamlined Compliance: The e-Invoice system’s one-time entry of e-Invoices serves as input for generating E-Way Bills and the ANX-1 (Annexure of outward supplies). This streamlines the compliance process, reducing the required effort to develop these documents separately.
5. 24/7 Self-Help Service: The e-Invoice system, backed by these APIs, provides a self-help service that is available 24/7. Users can access and utilize the system conveniently, ensuring efficient and uninterrupted operations.

By leveraging these APIs, Tax Payers and GSPs can enhance operational efficiency, reduce manual effort, and improve compliance quickly. The seamless integration and automated processes contribute to a smoother invoicing experience and streamlined tax-related activities.

4. Pre-requisites for Using e-Invoice API

To utilize the API interface effectively, Tax Payers, GST Suvidha Providers (GSPs), ERPs, and E-Commerce Operators (ECOs) must fulfil the following requirements:

• Automated Invoice Generation: Tax Payers and other entities must automate their invoice generation process. This ensures seamless integration with the e-Invoice system through the APIs.
• Security Measures: Entities must ensure that the traffic originating from their systems to the e-Invoice system is free from viruses, malware, intrusions, bots, and Command & Control threats. Any malicious traffic that negatively impacts the e-Invoice system may result in the suspension or blocking of services by the National Informatics Centre (NIC).
• Compliance with IT Security Standards: Strict adherence to the Government of India’s IT security standards and regulatory requirements is necessary. GSPs and Tax Payers must comply with the IT Act 2000, its amendments (such as 43A), and any other relevant regulations.
• Eligibility Criteria: Tax Payers and E-Commerce Operators, as notified by the government, are allowed to register e-Invoices on the GST Portal. The specific category of eligible Tax Payers can be found in the laws section of the e-Invoice portal.
• Adequate Bandwidth: Entities must have sufficient bandwidth to establish a stable connection with the e-Invoice system. This ensures smooth data exchange and communication.
• Annual Turnover: Initially, access to API credentials is granted to Tax Payers with an annual turnover of 500 Crore and above in their previous financial year.
• SSL and TLS Compliance: Applications consuming the APIs should support SSL (Secure Sockets Layer) with a minimum version of TLS (Transport Layer Security) 1.2. This ensures secure communication between systems.
• Whitelisting of IP Addresses: Access to the production environment is granted by whitelisting a maximum of up to 4 Indian Static IP addresses. This adds a layer of security to the API access.
• System Modification: Entities must modify their existing automated systems to enable data exchange with the e-Invoicing system according to the defined APIs. This ensures compatibility and seamless integration.
• Backup Connectivity: It is recommended that Tax Payers, GSTs, ERPs, and ECOs consider having backup connectivity from different service providers at their locations. This helps maintain uninterrupted access to the e-Invoice system.
• Pre-production Testing: Entities should have a pre-production system for testing purposes. It is necessary to thoroughly test the modified system on the e-Invoice pre-production site, performing various activities and services to ensure proper functionality and compliance.

By fulfilling these pre-requisites, entities can ensure a smooth integration process with the e-Invoice system, enabling them to leverage the APIs’ benefits effectively.

5. Onboarding and Integration Process

To smoothly transition into using the e-Invoice system, GSPs (GST Suvidha Providers), ERPs (Enterprise Resource Planning systems), ECOs (E-Commerce Operators), and Taxpayers should follow the onboarding process outlined below:

• Nominate Project Manager and Technical SPOC: GSPs, ERPs, ECOs, and Taxpayers should appoint a Project Manager and Technical Single Point of Contact (SPOC) to oversee all project-related matters and address any issues that may arise during the onboarding process.
• Fulfill Pre-requisite Conditions: Ensure that all pre-requisite conditions have been met before gaining access to the production environment.
• Conduct Testing in Pre-production: Thoroughly test all APIs in the pre-production environment, considering both successful and failure cases for all possible scenarios. Testing should be done by integrating the APIs with the Taxpayer’s ERP or Accounting application, not through the NIC online testing tool.
• Prepare Test Summary Report: After testing, file a comprehensive Test Summary Report documenting the test results in the provided format (Excel Icon). The report should summarise tests conducted using a single client ID. Only GSPs, ERPs, ECOs, or concerned Taxpayers should submit the test report, not third parties.
• Submit Test Report and Whitelisting Request: GSPs and ERPs should send the Test Summary Report to support.einv.api@gov.in, while Taxpayers and ECOs should upload the report through the portal. Along with the information, request whitelisting of IP addresses if required.
• Verification and Whitelisting Process: The Test Summary Report and whitelisting request will undergo verification, which may take approximately 4-5 days. Submitting the requests well in advance is advisable to avoid any inconvenience during the go-live phase. Please ensure the correct IP addresses are provided, as changing them after whitelisting may take longer.
• Upload Report and Request Whitelisting on Production Portal: Upload the duly filled Test Summary Report in PDF format onto the production e-Invoice Web Portal. Alongside the report, submit a request for whitelisting the IP addresses.
• Access to e-Invoice System: Access to the e-Invoice system will be granted once the Test Summary Report has been evaluated and confirmed.
• Transition to MPLS Links: Initially, users can access the e-Invoice system online. However, in the future, access will be provided through MPLS (Multiprotocol Label Switching) links provisioned by GSTIN (Goods and Services Tax Identification Number). The cut-off date for this transition will be communicated in due course.
• Create Credentials for Production Environment: Users must create separate credentials for the production environment by visiting the production e-Invoicing self-help portal. This step is necessary to access the system effectively.
• Multiple GSTINs under the Same PAN: A Taxpayer with multiple GST registrations (GSTINs) under the same PAN can use the same client-id and client secret for their primary business place. However, they must create separate usernames and password credentials for each registration/GSTIN within the e-Invoice system.
• GSP/ERP Usage: Taxpayers who use the APIs through a GSP or ERP should select the respective GSP or ERP in the portal and create their username and password credentials.

By following these steps, GSPs, ERPs, ECOs, and Taxpayers can successfully onboard the e-Invoice system and gain access to its functionalities and APIs.

6. Required Documentation for e-Invoice API

• 4 Indian Public Static IPs: Provide a maximum of 4 Indian Public Static IPs that need to be whitelisted at the NIC (National Informatics Centre) end. These IPs will allow authorized access to the e-Invoice system.
• Summary Test Report: Prepare a comprehensive summary test report detailing the successful tests conducted on the sandbox environment. Include all relevant information regarding the test scenarios, results, and any observations or issues encountered during testing.
• Contact Details of Project Manager and Technical SPOC: Include the contact details of the Project Manager and Technical Single Point of Contact (SPOC) in the test report. Provide their names, email addresses, and phone numbers for effective communication and coordination during the on-boarding process.

These documents are essential for a smooth on-boarding process and to ensure that the necessary IPs are whitelisted, and the relevant stakeholders are engaged for effective project management and technical support.

7. Obtaining API Credentials

The E-Invoice API requires two sets of credentials:

• Client Id and Client Secret: These credentials are provided to Service Providers such as GSPs (GST Suvidha Providers), ERPs (Enterprise Resource Planning systems), and ECOs (E-Commerce Operators). These credentials allow authorized access to the API.
• User Id and Password: Each taxpayer can create their own User Id and Password for their specific GSTIN (Goods and Services Tax Identification Number). These credentials are used to generate Invoice Registration Numbers (IRNs) for their invoices.

If a taxpayer wishes to access the API directly, as notified by the NIC IRP (Invoice Registration Portal), they will be provided with Client Id and Client Secret. The same set of Client IDs and Client Secret can be used for all GSTINs associated with the taxpayer’s PAN (Permanent Account Number). This means that the Client Id and Client Secret can be used across multiple sisters concerned GSTINs that share the same PAN.

It is essential to manage and protect these API credentials securely, as they provide access to the e-Invoice system and ensure the integrity and confidentiality of the data exchanged between the taxpayer’s plans and the e-Invoice system.

8. API Credentials for Sandbox Environment:

To obtain the API credentials for the sandbox environment, GSPs (GST Suvidha Providers), ERPs (Enterprise Resource Planning systems), ECOs (E-Commerce Operators), and notified taxpayers to need to register on the sandbox portal. The following steps outline the registration process:

• Visit the ‘API sandbox portal’ and click the login link. Then, click on the Register button to initiate the registration process.
• Select the appropriate category from the options provided – GSP, ERP, ECO, or Taxpayer. Enter the PAN (Permanent Account Number) or GSTIN (Goods and Services Tax Identification Number) associated with your registration on the GST Common Portal.
• Provide the registered mobile number and email ID used during the GSP or GSTIN registration on the GST Common Portal.
• The system will verify the provided details and send an OTP (One-Time Password) to the registered mobile number.
• Enter the OTP to validate the registration details.
• the system will generate the Client Id and Client Secret once the details are verified successfully.
• The Client Id and Secret will be sent to the registered mobile number.

For taxpayers, they can directly create a username and password for their specific GSTIN.

For GSPs, they have the option to generate dummy GSTINs based on the state and their PAN. They can create usernames and passwords for these GSTINs. GSPs can generate multiple usernames and passwords for the same PAN with different states.

These credentials can be used for API testing in the sandbox environment. They can also be used to log in to the API developer application, providing an opportunity to understand the API interface steps and perform necessary verifications.

10. API Credentials for Production Environment

GSPs (GST Suvidha Providers) and notified taxpayers already accessing the E-way Bill APIs on the production environment can use the same Client Id, Client Secret, Username, and Password for e-invoice APIs.

GSPs who do not have API credentials in the E-way Bill System will be provided with the credentials after completing the onboarding process. GSPs, being service providers, will not be provided with username and password credentials.

ERPs (Enterprise Resource Planning systems), ECOs (E-Commerce Operators), and taxpayers must log in to the einvoice1 portal and request the Client credentials by submitting four static IP addresses and a summary test report.

After scrutinising and verifying the test report, the IP addresses will be whitelisted, and the taxpayers will be notified. They can then obtain the Client Credentials through the portal.

Notified taxpayers can create a username and password credentials on the e-invoice production portal after logging in. This option is available in the user management section and requires OTP authentication.

Suppose the sister concern of the notified taxpayer already has access to the API system. In that case, the taxpayer can connect through them by registering with the same company when creating the username and password.

If the notified taxpayer does not directly access the API and wishes to connect through a GSP or ERP, they can choose the GSP or ERP through which they want to connect to the API system when creating the username and password.

These user credentials should be used to access the e-invoice system and generate the Invoice Registration Number (IRN) directly from the taxpayer’s system.

11. Important Considerations for e-Invoice API Usage

• Taxpayers registered for the API system should keep their username and password private from their service provider.
• If a taxpayer desires, they can create separate username and password credentials with multiple GSPs or ERPs. It’s important to note that the username and password will be different for each GSP/ERP.
• The taxpayer should use the user credentials created with a specific GSP/ERP when requesting an Invoice Registration Number (IRN) through that particular GSP/ERP. In other words, the taxpayer can interchange these “user credentials” or “Auth Token” between GSPs/ERPs.
• The taxpayer can freeze or block the user credentials created with any GSP/ERP if they no longer wish to continue using them.
• The taxpayer can also change the password of the user credentials whenever necessary.
• It is the responsibility of the taxpayer to generate the IRN request from their system and send it to the service provider (GSP/ERP).
• The service provider (GSP/ERP) should not store the request and response data of the taxpayer in their system.

12. Best Practices for Implementing e-Invoice API:

• API Interface for Tax Payer Automated system: Ensure the taxpayer’s automated system seamlessly integrates with the e-Invoice system. Send the required data to the “Generate IRN” API and store the received IRN, digitally signed e-Invoice, and QR Code for future reference.
• Store the response values: It is recommended to store the response values, including the ACK Number, ACK Date, IRN, and Signed-Invoice, along with the request record. This will help avoid dependency on the GST system for retrieving this data in the future.
• Validate the JSON Schema and data before requesting: Validate the request payload JSON against the provided Schema and ensure the data is validated correctly. This will ensure faster and more accurate service to the end user.
• Check the response status and act accordingly: Handle the response status and data/error appropriately in the interface. If an error status is received with an error list, make the necessary modifications or corrections at the user or system level and resubmit the request.
• Don’t request the token for every transaction: Store the authentication token, SEK, and expiry time provided by the e-Invoice system during the authentication process. Use the stored values for subsequent transactions instead of requesting them for each transaction. This will improve transaction speed and prevent the API service from being blocked for the taxpayer.
• Re-generate the token before expiry: The authentication token is valid for 6 hours. It is advised to request a new token approximately 10 minutes before the expiry of the current token. This allows time to check and resubmit any failed requests during that period.
• Don’t store the e-invoice system’s SSL Certificate: Avoid storing or hardcoding the e-Invoice system’s SSL Certificate in the application for API integration. The SSL certificate of the e-Invoice system is updated regularly for security purposes, and it is best to rely on the system’s SSL certificate verification mechanism instead.

13. API Version Management in the e-Invoice System:

API version management in the E-Invoice system involves managing two different version numbers: Schema Version and API Version. Here are the key points to understand:

1. Schema Version: This refers to the version of the schema used for the IRN (Invoice Reference Number) request payload. The current schema version is 1.1, which should be mentioned in the “version” attribute of the generated IRN request payload. The schema version is updated based on relevant government notifications that introduce changes to the schema structure.

2. API Version: This represents the version of the API system itself. The API version is updated based on various factors, including changes in rules, user feedback, technical requirements, and performance enhancements. Currently, the API version being used is 1.03. The API version number is visible in the API endpoints and related documentation.

It’s important to note that there is no direct synchronization between the Schema and API versions. While changes in the schema may require corresponding modifications in the consuming application, the reverse is not necessarily true. In other words, changes in the application version may only sometimes result in changes to the schema version.

Overall, these version numbers serve different purposes and are managed independently, but they may have dependencies on each other. Keeping track of the latest versions and incorporating the necessary changes in the application ensures compatibility with the evolving E-Invoice system.

API version management in the E-Invoice system follows the following guidelines:

1. No Change in API Version Number: If there are minor changes in the application that do not impact the request and response JSON, relaxations in validations, addition of optional fields, or minor changes in phrases or response attributes, the API version number remains the same. These changes are communicated in the release notes under the existing API version number and the date of effect in the sandbox environment.
2. New API Version Number: In cases where there are changes in the request and response JSON schema (addition/deletion/relocation of attributes, changes in mandatory status, data type changes, allowed data ranges, etc.) or changes in request URL parameters, the introduction of new validations, or differences in the request and responses of other APIs, a unique API version number is assigned. The latest version number will appear in the URL and documentation.

It’s important to note that when a new API version number is introduced, it applies to all the APIs within the system, regardless of whether they have changed. This ensures consistency and compatibility across the system.

Following this versioning approach, the E-Invoice system can effectively manage updates and enhancements while maintaining backward compatibility with existing applications. Developers can refer to the documentation and release notes to stay informed about the changes associated with each API version.

Example:

In the E-Invoice system, the version numbers may follow a sequential pattern such as 1.09, 1.10, 1.11, and so on. Minor changes and enhancements can be introduced within the same version number, while major changes will result in a new version number. For example, if significant changes are made, a new version like 2.00 will be released, followed by subsequent versions like 2.01, 2.02, and so on.

During the testing phase on the Sandbox environment, the latest API version will be made available for stakeholders to adapt to the changes and perform thorough testing. The release of the APIs on the Production environment will be announced through the portal, taking into account the urgency of implementing the changes.

Normally, only one API version will be running on the Production environment. However, during the transition period when a new API version is released, there might be a brief overlap where both the previous and new versions are operational on Production for approximately 7-8 days. This allows stakeholders to smoothly transition and adapt to the changes before fully migrating to the new version.

By following this versioning approach and providing a transition period, the E-Invoice system ensures that stakeholders have sufficient time and resources to update their applications and integrate with the latest API versions effectively.

Version No.	End Points
1.03	• https:///eivital/v1.03/ • https:///eicore/v1.03/ • https:///eiewb/v1.03/
1.04	• https:///eivital/v1.04/ • https:///eicore/v1.04/ • https:///eiewb/v1.04/