e – Invoice API Developer’s Portal

1. Introduction:

1.1. Background:

The implementation of electronic invoicing, known as ‘e-Invoicing,’ for reporting Business to Business (B2B) invoices to the GST System was approved by the GST Council in a phased manner, starting from January 1, 2020, voluntarily. The National Informatics Centre, as the first Invoice Registration Portal (IRP), has made e-Invoice registration services available through API mode, in addition to other methods. Taxpayers and GST Suvidha Providers (GSPs) can seamlessly integrate their business systems and processes with the e-Invoice system using these APIs to register invoices generated or prepared within their systems.

1.2. Purpose of the e-Invoice API Developer’s Portal:

The e-Invoice API Developer’s Portal serves the following purposes:

1. Understanding Interfacing Processes: Developers or system integrators of taxpayers can comprehend the interfacing processes between their business systems and the e-Invoicing system.
2. User Registration: The portal facilitates user registration to access the APIs. It provides information on obtaining credentials such as client-id, client-secret, username, and password.
3. OTP Validation: During the registration process, the company’s primary authorised signatory’s mobile number and email address (as registered with the GST common portal) are validated through OTP.
4. API Documentation: The portal provides comprehensive API documentation for application developers, including calling methods, URLs, JSON Schema of request payloads, sample payloads and responses, applied validations, and other relevant information. It also offers sample code extracts for reference and provides master data used in the system.
5. Sandbox Testing: Developers can understand and test API methods through the sandbox portal. They can simulate API usage end-to-end, generate request payloads, understand encryption and decryption processes, validate encrypted payloads, test different parameter values, and observe responses for successful and unsuccessful scenarios. The portal also provides insights into error responses, such as handling wrong credentials, missing mandatory parameters, and invalid API calls without a valid token.

By offering these functionalities, the e-Invoice API Developer’s Portal empowers developers to seamlessly integrate their systems with the e-Invoice system, test API interactions, and ensure a smooth invoicing experience.

2. API Overview:

The e-Invoice APIs serve as a means of communication and data exchange between Taxpayers or GSP systems and the e-Invoice system. These APIs are implemented as RESTful Web Services and adhere to defined standards and formats. This section provides an overview of the e-Invoice API structure and authentication process.

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

Authentication is a crucial step to access the APIs. Users must initiate the authentication process by calling the Authentication API to obtain a token. This token should be included in subsequent API calls for authentication purposes. Detailed information regarding the Authentication API can be found in the API documentation.

During the authentication process, it is necessary to encrypt the password and AppKey using the public key provided by the e-Invoice system. This encryption ensures the secure transmission of sensitive information.

Successful authentication provides a token and generates a Session Encryption Key (SEK). This SEK should be used to encrypt subsequent request payloads and decrypt responses from the e-Invoice system. Symmetric encryption algorithms are employed for payload encryption.

Specific API calls, such as “Generate – IRN” and “Get IRN Details,” return responses that include digitally signed e-Invoice and QR-Code data. JSON Web Token (JWT) and JSON Web Signature (JWS) with the “SHA256RSA” algorithm are utilized for this purpose.

For more detailed information on the above topics, including authentication, encryption, and digitally signed responses, refer to the respective API documentation available on this portal. documentation available on the portal.

Authentication Token Request Process

Process flow for other services

3. Benefits:

The utilization of these e-Invoice APIs offers several advantages to both Taxpayers and GST Suvidha Providers (GSPs):

• Seamless Integration: These APIs facilitate seamless integration of the Taxpayer’s ERP/Accounting system with the e-Invoice system. This integration allows for smooth communication and data exchange between the two systems.
• Online Recording of IRN and ACK: Taxpayers can conveniently record the Invoice Registration Number (IRN) and ACK number obtained from registering e-Invoices in the GST System directly on their systems. This eliminates the need for manual recording and reduces the chances of duplicate or double entry of invoices.
• Avoidance of Data Entry Errors: By passing the sales details from the taxpayer’s computerized system to the e-Invoicing system, the possibility of errors during data entry for e-Invoices is significantly minimized. This ensures accurate and error-free invoice information.
• Streamlined Process for E-Way Bill and ANX-1: The one-time entry of e-Invoices serves as an input for generating E-Way Bills and the ANX-1 (Annexure to Form GSTR-1). This streamlines the process, as the data from the e-Invoice system can be efficiently utilized for these purposes, reducing manual effort and enhancing efficiency.
• 24/7 Self-Help Service: The e-Invoice system provides a self-help service that is available 24/7. Taxpayers and GSPs can access the system anytime to perform various actions and obtain the necessary information.

4. On Boarding

4.1. Prerequisites:

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

• Automated Invoice Generation: Users should have automated their invoice generation process, ensuring that invoices are generated systematically by their systems.
• Ensuring Secure Traffic: It is essential to ensure that the traffic originating from their end and destined for the e-Invoice system is free from viruses, malware, intrusions, bots, and command-and-control (C&C) threats. The National Informatics Centre (NIC) reserves the right to suspend or block the services of GSPs/Taxpayers if any malicious traffic is detected, which may adversely impact the e-Invoice system.
• Compliance with IT Security Standards: Users must adhere to all Government of India IT Security standards and regulatory requirements. GSPs and Taxpayers must comply with the IT Act 2000, including its amendments (such as 43A).
• Eligibility for e-Invoice Registration: Taxpayers and E-Commerce Operators (ECOs), as notified by the government, are permitted to register e-Invoices on the GST Portal. The e-Invoice portal’s laws section provides information on the eligible category of taxpayers.
• Adequate Bandwidth: Users must have provisions for sufficient bandwidth at their end to establish a stable connection with the e-Invoice system.
• Access for Taxpayers with Annual Turnover of 500 Crore and Above: The API credentials will be made available to taxpayers who had an annual turnover of 500 Crore or more in the previous financial year.
• SSL Support: Applications consuming APIs should support SSL (Secure Sockets Layer) with a minimum version of TLS 1.2 to ensure secure communication.
• Whitelisting of IP Addresses: Users can access the production environment by whitelisting a maximum of up to four Indian static IP addresses.
• Modification of Automated Systems: Users need to modify their automated systems to enable seamless data exchange with the e-Invoicing system, conforming to the specifications defined by the APIs.
• Backup Connectivity: It is recommended that Taxpayers, GST Suvidha Providers, ERPs, and E-Commerce Operators consider implementing backup connectivity from different service providers at their locations for added reliability.
• Pre-Production Testing: Users should have a pre-production system to conduct thorough testing. It is necessary to test the modified system on the e-Invoice pre-production site, encompassing all activities and services.

By meeting these prerequisites, users can ensure a smooth integration and interaction with the e-Invoice system through the provided APIs.

4.2. On boarding Process:

4.2.1. E-Way Bill and E-Invoice API Access Mechanism

Category	Tax payers with Turnover > 500 Crores	Tax payers with Turnover < 500 Crores
Through GSP	Yes	Yes
Through ERP	Yes	Yes
Direct API Access	Yes	No
Through ‘Direct API Access Users’	Yes	Yes
Users already having ‘E-Way Bill API Access’	Yes	Yes

To gain access to the E-Way Bill and E-Invoice APIs, GSPs, ERPs, ECOs, and Taxpayers need to follow the onboarding process outlined below:

• Nominate Project Manager and Technical SPOC: GSPs, ERPs, ECOs, and Taxpayers should appoint a Project Manager and a Technical Single Point of Contact (SPOC) to oversee all project-related matters and address any issues that may arise.
• Fulfill Pre-requisite Conditions: Ensure that all pre-requisite conditions have been met to access the production environment.
• Testing in Pre-production Environment: Conduct thorough testing of all APIs in the pre-production environment. Test various scenarios, including successful and failure cases, covering all possible scenarios, not just those provided in the test summary format.
• Test Summary Report: Prepare a comprehensive report documenting the complete test results. The report should be submitted in the specified format, which can be found Excel Icon. Only GSPs, ERPs, ECOs, or the concerned Taxpayers should submit the test report (not third parties).
• Submission of Test Report: GSPs and ERPs are required to send the test report to support[dot]einv[dot]api[at]gov[dot]in the email address. Taxpayers and ECOs should upload the test report through the portal and also submit a request for whitelisting their IP addresses.
• Verification and Whitelisting: The test report and IP whitelisting request will be verified, which may take approximately 4-5 days. Submitting the requests well in advance is advisable to avoid any inconvenience during the go-live phase. Ensure that the correct IP addresses are provided, as changing the whitelisted IPs takes additional time.
• Upload Report on Production Portal: Upload the duly filled Test Summary Report in PDF format onto the production E-Invoice Web Portal. Along with the report, submit a request for whitelisting the IPs.
• Evaluation and Confirmation: Access to the e-Invoice system will be provided once the test report has been evaluated and confirmed.
• Access via MPLS Links: Initially, users can access the e-Invoice system online. However, access will be provided through MPLS links provisioned by GSTIN in the future. A cut-off date for this transition will be communicated in due course.
• Creation of Credentials for Production Environment: Users need to create separate credentials for the production environment by visiting the production e-Invoicing self-help portal. Taxpayers with multiple 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 in the e-Invoice system.
• GSP/ERP Option: Taxpayers wishing to utilize the APIs through a GSP or ERP must select the respective GSP/ERP in the portal and create their username and password.

By following these steps, users can successfully onboard and gain access to the E-Way Bill and E-Invoice APIs, enabling seamless integration with the e-Invoice system.

4.3. Documents Required for API Access:

To obtain API access for E-Way Bill and E-Invoice, the following documents are required:

1. 4 Indian Public Static IPs: Provide a maximum of 4 Indian Public Static IPs for whitelisting at the NIC (National Informatics Centre) end. These IPs will be authorized to communicate with the e-Invoice system.
2. Summary Test Report: Prepare a summary report documenting the successful tests conducted in the sandbox environment. The report should include details of the tested scenarios, results, and any relevant observations.
3. 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. This information will help coordinate and resolve any project-related matters or technical issues.

Ensure that these documents are submitted as part of the onboarding process to facilitate the evaluation and approval of API access.

5. API Credentials

The E-Invoice API utilizes two sets of credentials: Client ID and Client Secret, and User ID and Password. Here are the details regarding these credentials:

1. 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). They enable these entities to access the E-Invoice API on behalf of their clients. If a taxpayer wishes to access the API directly, as specified by the NIC IRP (Invoice Registration Portal), they will be assigned a Client ID and Client Secret. These credentials can be used for all GSTINs associated with the taxpayer’s PAN (Permanent Account Number).
2. User ID and Password: Each taxpayer generates 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.

5.1. API Credentials for Sandbox:

To obtain API credentials for the sandbox environment, GSPs, ERPs, ECOs, and notified taxpayers to need to register on the sandbox portal. Follow the steps below to obtain the Client ID and Client Secret:

1. Access the ‘API sandbox portal’ and click on the login link.
2. On the login page, click on the Register button.
3. Select the appropriate category – GSP, ERP, ECO, or Taxpayer – and enter the PAN or GSTIN.
4. Provide the registered mobile number and email ID used during GSP or GSTIN registration on the GST Common Portal.
5. Verify the details and enter the OTP sent to the registered mobile number.
6. Upon successful verification, the system will generate the Client ID and Client Secret, which will be sent to the registered mobile number.
7. Taxpayers can directly create a username and password for their specific GSTIN.
8. For GSPs, they can generate dummy GSTINs based on the state and PAN and create usernames and passwords for these GSTINs. Multiple usernames and passwords can be generated for the same PAN with different states.
9. The obtained credentials can be used for API testing. They can also be used to log in to the API developer application to understand the API interface steps and verification process.

By following these steps, users can obtain the necessary API credentials for the sandbox environment.

5.2. API Credentials for Production:

• GSPs and notified taxpayers already accessing the E-way Bill APIs in the production environment can use the same Client ID and Client Secret, as well as 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 upon completion of the onboarding process. As service providers, GSPs will not be given username and password credentials.
• ERPs, ECOs, and taxpayers must log in to the einvoice1 portal and request the Client credentials by submitting four static IPs and a summary test report. After the report is scrutinized, verified, and the IPs are whitelisted, the credentials will be provided through the portal.
• Notified taxpayers can create their username and password credentials on the e-invoice production portal after logging into the system. This can be done in the user management section and will require OTP authentication.
• If a notified taxpayer’s sister concern already has access to the API system, they can connect through that company by registering with them and creating a username and password.
• If a notified taxpayer does not access the API directly and wishes to connect through a GSP or ERP, they can choose the GSP or ERP while creating their username and password.
• These user credentials must be used to access the e-invoice system and generate the IRN directly from the taxpayer’s system.

5.3. Important Points

Here are some essential points to consider regarding API credentials and usage:

• Taxpayers should keep their usernames and password private from their service providers.
• Taxpayers can create separate username and password credentials with multiple GSPs or ERPs. Each set of credentials will be different for each GSP/ERP.
• When requesting an IRN through a specific GSP/ERP, the taxpayer should use the user credentials created with that particular GSP/ERP. The user credentials or Auth Token can be interchanged and used between GSPs/ERPs.
• Taxpayers can freeze or block the user credentials created with any GSP/ERP if they no longer wish to continue using their services.
• Taxpayers can change the password of their 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 taxpayers in their system.

Please note that these points are intended to provide general guidance, and it’s essential to refer to the specific guidelines and policies provided by the e-Invoice system and follow the best practices for secure and authorized usage of API credentials.

6. Best Practices

Here are some best practices to consider when using the API interface for taxpayer-automated systems:

• Store the response values: After making API calls, store the response values such as ACK Number, ACK Date, IRN, and Signed-Invoice. These values and the corresponding request records should be saved for future reference. This will help avoid dependencies on the GST system for retrieving this data in the future.
• Validate the JSON Schema and data: Before requesting to generate the IRN, ensure that the request payload JSON is validated against the provided Schema and that the data is validated according to the specified validation steps. This will help ensure faster and more accurate service to end users.
• Check the response status: Each API call will provide a response status and data or error information. It is essential to have an interface in place to handle these responses appropriately. If the status indicates an error and provides an error list, take the necessary steps to modify or correct the data at the user or system level before resubmitting the request.
• Avoid requesting a token for every transaction: During the authentication process, the e-invoice system provides a token, SEK, and expiry time. It is recommended to store these values in the taxpayer’s system and reuse them for each transaction instead of requesting a new token for every transaction. This will speed up the transaction process and prevent the API service from being blocked for that particular taxpayer.
• Re-generate the token before expiry: The authentication token provided by the e-invoice system is valid for a certain period, typically 6 hours. Requesting a new token approximately 10 minutes before the current token’s expiry is advisable. This will ensure seamless authentication and prevent any interruptions during the transaction process. Additionally, check for any failed requests during that time and resubmit them if necessary.
• Avoid storing the e-invoice system’s SSL certificate: The e-invoice system periodically changes its SSL certificate for security reasons. It is important not to store or hardcode the SSL certificate in the application used for the API interface. Instead, rely on the system’s ability to manage SSL certificates dynamically to maintain proper security measures.

By following these best practices, taxpayers can enhance the efficiency, security, and reliability of their interactions with the e-invoice system through the API interface.

7. API Version management in E Invoice System

In the E-Invoice system, version management is essential to handle changes and updates. Here is an overview of how version management is handled in the E-Invoice system:

1. Schema Version: This refers to the version of the schema used for the IRN (Invoice Reference Number) request payload. The schema version number, such as 1.1, is mentioned in the “version” attribute of the generated IRN request payload. The schema version is updated based on government notifications and changes in the schema rules.
2. API Version: This refers to the version of the API system itself. The API version number, such as 1.03, is used in the API endpoints and documentation. The API version is updated based on various factors such as government notifications, process changes, user feedback, technical requirements, and performance enhancements.

It’s important to note that there is no direct synchronization between the Schema Version and API Version numbers. However, they may depend on each other. For example, a change in the request schema may require a change in the application version, but the reverse is not necessarily true.

API Version Management:
a. Continuation of the Same API Version: Minor changes that do not affect the request and response JSON, relaxations in validations, the addition of optional fields for enhanced functionality, or changes in phrases or attributes in responses will not affect the API version number. These changes will be communicated in the release notes under the same API version number, with the date of effect in the sandbox environment.

b. Introduction of a New API Version: If there are changes in the request and response JSON schema, new validations, changes in request URL parameters, or changes in the request and responses of other APIs, a new API version number will be released. The new version number will be reflected in the API URLs and documentation. This change will apply to all APIs, even if some have yet to change.

The API version numbers may increment, such as 1.09, 1.10, 1.11, and so on. In case of significant changes, a new primary version number may be introduced, such as 2.00, followed by 2.01, 2.02, and so on.

During the transition to a new API version, the current and new versions may run simultaneously on the production environment for a limited period (usually 7-8 days) to allow stakeholders to adapt to the changes and perform necessary testing.

These changes, whether they involve version number updates or not, will be made available on the Sandbox environment for stakeholders to adapt and test. The date when the APIs will be available in the Production environment will be announced through the portal.

In general, only one API version will be active in the Production environment. However, during the release of a new API version, both the current and new versions may coexist for a limited period.