e-Invoice Sandbox System

The E-Invoice Sandbox System, available at https://einv-apisandbox.nic.in, serves as a comprehensive platform for developers to integrate their ERPs and financial accounting systems with the e-Invoicing operations exposed by NIC-IRP (National Informatics Centre-Invoice Registration Portal) through APIs. The system facilitates registration by eligible taxpayers and GST Suvidha Providers (GSPs) and testing of the APIs in a sandbox environment.

The portal’s home page provides easy access to essential information on the exposed APIs without requiring any login. It offers complete documentation on each API, enabling developers to understand and consume them effectively. It also includes a web-based test environment where users can gain insights into the step-by-step process of utilizing the APIs, including payload preparation, encryption, decryption, API invocation, and response handling. Users can upload their request payloads and view the corresponding results and responses, indicating success or failure.

The “Resources” section on the homepage provides additional valuable content for users. It covers topics such as understanding the Invoice Reference Number (IRN), attributes used in JSON and their technical mappings, masters for country, currency, port, and state, general master data encompassing transaction types, document types, units, modes of transport, and more. The section also offers information on common errors, sample codes in languages like JAVA, C#, and .NET, frequently asked questions, best practices for API usage, announcements, and release notes detailing the latest API versions.

Seamless integration of the e-Invoicing process with existing ERPs or financial accounting systems brings multiple benefits to taxpayers and GSPs. It eliminates the need for duplicate data entry, reducing the chances of data redundancy. Furthermore, it facilitates integration with the E-Way bill generation process. The implementation strategies can yield various other advantages.

To access the production environment, GSPs and taxpayers must fulfil specific prerequisites. This includes evaluating a summary test report based on sandbox testing, which needs to be submitted by the user after completing all the pre-production environment tests. It is essential to have a nominated project manager or technical SPOC (Single Point of Contact) to handle project-related issues. Additionally, four Indian public static IPs must be whitelisted at the NIC end for access.

e-Invoice API Overview:

Facilitating Secure Data Exchange and Authentication in E-Invoice System

In e-Invoicing, APIs play a crucial role in enabling seamless interaction and data exchange between Taxpayer/GSP (GST Suvidha Provider) systems and the e-Invoice system. These APIs ensure that all transmitted data is encrypted and exposed through SSL (Secure Sockets Layer) for enhanced security. Access to the APIs is granted only after successful token-based authentication.

The E-Invoice APIs support both the HTTP POST and GET methods. APIs that receive data for addition or updating utilize the POST method, while those providing data based on specific inputs utilize the GET method. To access the APIs, eligible users must complete a self-registration process to obtain the necessary credentials, including the client ID, client secret (for GSPs), user ID, and password (for taxpayers with GSTIN). These credentials are then used to authenticate the user with the NIC’s (National Informatics Centre) e-Invoicing API system.

Upon successful authentication, the system generates an authentication token and a Session Encryption Key (SEK), which are provided to the user. In the sandbox environment, these credentials are valid for 1 hour, while in the production environment, they remain valid for 6 hours.

The E-Invoice API utilizes two sets of credentials: Client ID and Client Secret for GSPs, and User ID and Password for taxpayers with GSTIN. If a taxpayer is authorized to access the API directly, they will receive a Client ID and Client Secret that can be used for all GSTINs associated with the same PAN (Permanent Account Number).

API credentials for the sandbox environment are available upon registration in the API sandbox portal. In contrast, API credentials for the production environment are provided after the completion of the boarding process. Detailed information regarding API credentials and procedures can be found on the website.

Please note that the specific details and processes may vary based on the region and guidelines implemented for e-Invoicing.

API Specifications:

Authentication: Secure Access to e-Invoice APIs

To access the e-Invoice APIs, users must authenticate themselves using specific credentials. These credentials need to be generated by the taxpayers, enabling them to obtain an “auth token” that remains valid for 360 minutes (6 hours). The same auth token is used for subsequent API calls. Any API requests will return the same token within the token’s validity period. However, there is an option to generate a new token forcefully within the last 10 minutes of its expiry. This can be done by calling the authentication API and setting the “ForceRefreshAccessToken” parameter to “True”.

On the same page, users have access to an informative image illustrating the exchange of requests and responses between the systems of the taxpayer and the IRP (Invoice Registration Portal). Detailed information regarding the request and response payloads, including sample JSONs, is provided to aid users in understanding the data exchange process. Additionally, FAQs related to the authentication API are available, offering additional support and clarification for users.

This authentication mechanism ensures secure and authorized access to the e-Invoice APIs, allowing taxpayers to interact seamlessly with the system and utilize the provided functionalities.

Generate IRN: Registering and Generating Invoice Reference Number

The Generate IRN API is specifically designed for registering invoices or generating the Invoice Reference Number (IRN). To successfully utilize this API, the request payload must adhere to the e-invoice JSON schema provided on the portal. Users can refer to the accompanying image, which illustrates the exchange of request headers, request payloads, and response payloads between the taxpayers and IRP systems.

Detailed information regarding the request and response payloads, including sample JSONs, is provided to assist users in understanding the required data structure. Additionally, a JSON schema is made available for reference. The API consumer must also consider the validations outlined in the documentation when developing the application that consumes this API.

A set of frequently asked questions (FAQs) related to the generated IRN process is provided to support users further. These FAQs address common concerns and provide additional guidance for API consumers.

By utilizing the Generate IRN API, taxpayers can effectively register their invoices and obtain the necessary Invoice Reference Numbers, facilitating seamless compliance with e-invoicing regulations.

Cancel IRN: Cancelling an e-Invoice.

The Cancel IRN API enables users to cancel an e-Invoice by providing the corresponding Invoice Reference Number (IRN). This API utilizes the POST method for communication. Please refer to the link for comprehensive information regarding the request and response payloads, sample JSONs (Request and Response), JSON schema, validations, and frequently asked questions (FAQs).

By invoking the Cancel IRN API, taxpayers can cancel an e-Invoice within the specified time frame. The detailed documentation and resources available through the link will assist users in understanding the necessary payload structure, validation requirements, and the overall process of cancelling an e-Invoice.

Get E-Invoice Details: Retrieving E-Invoice Information

The Get E-Invoice Details API allows users to retrieve the details of an e-Invoice by providing the corresponding Invoice Reference Number (IRN). This API utilizes the HTTP GET communication method.

To obtain the e-Invoice details, users must include the IRN value as an attribute in the request. The request header should contain the necessary attributes, similar to the case of POST APIs. The response JSON is encrypted using the Session Encryption Key (SEK). The plain text JSON will be revealed upon decrypting the encrypted payload, containing the IRN details, signed invoice, and signed QR code.

The Get E-Invoice Details API lets users access comprehensive information about a specific e-Invoice, including the relevant IRN details and the associated signed invoice and QR code.

Generate E-Way Bill Details: Creating E-Way Bills

The Generate E-Way Bill Details API enables users to generate an e-way bill using the Invoice Registration Number (IRN) as the reference. It should be noted that e-way bills cannot be generated for cancelled IRNs.

To utilize this API, users can click on the provided link to access detailed information regarding the request and response payloads, sample JSONs (Request and Response), JSON schema, and validations. Following the provided documentation, users can successfully generate e-way bills based on the IRNs associated with their invoices.

Get GSTIN Details: Retrieving Taxpayer Information

The Get GSTIN Details API allows users to retrieve taxpayer details based on a given GSTIN (Goods and Services Tax Identification Number). This API utilizes the HTTP GET method for data retrieval.

Users can access the provided link to view detailed information regarding the request and response payloads and sample JSONs for the GETGSTIN API. Additionally, FAQs related to this API are available to provide additional assistance to users seeking taxpayer information.

API Testing Tool 

Registration and Login Process for e-Invoicing Sandbox Environment

To test the API integration with their system, eligible users must register in the NIC-IRP e-Invoicing sandbox environment. Follow these steps for registration and login:

1. Visit the website of the e-Invoicing sandbox environment of NIC-IRP (https://einv-apisandbox.nic.in) and click on the “Register Here” button.
2. Fill in the required values in the registration form. If you are a taxpayer, provide your GSTIN (Goods and Services Tax Identification Number). Provide your PAN number if you are a GSP (GST Suvidha Provider). Once entered, the trade name associated with the provided information will be automatically displayed.
3. Enter the mobile number and email IDs registered with the GSTN. To ensure the validity of these details, click on the “Validate” button.
4. After successful validation, click the “Send OTP” link. An OTP (One-Time Password) will be sent to your registered mobile number and email IDs.
5. Additional fields will be displayed once the OTP is received, including the client ID, client secret, user ID, and password. Enter the required information.
6. After entering the necessary details, complete the registration process.
7. The generated client ID, client secret, user ID, and password will be used to access the APIs for testing purposes.
8. You can now log in to the system using the provided credentials.

By following these steps, you can register and log in to the e-Invoicing sandbox environment of NIC-IRP, allowing you to test the API integration with your system.

Add GSTIN

On the homepage of the e-Invoicing sandbox environment of NIC-IRP, you will find the option to “Add Test GSTIN” in the top right corner. Follow these steps to add a GSTIN:

1. Click on the “Add Test GSTIN” option on the homepage.
2. If an eligible taxpayer logs into the system, you can create additional user accounts for counterparts registered in other states using the same PAN. You can create accounts for other eligible taxpayers if you are a GSP.
3. The process for adding a GSTIN is similar to the registration process. Enter the required details as prompted.
4. Once the information is entered, click the appropriate buttons or links to proceed with the GSTIN addition process.
5. After successfully adding the GSTIN, you will see a list of already registered GSTINs displayed on the screen.

Following these steps, you can add a GSTIN to your account in the e-Invoicing sandbox environment. This allows you to manage multiple GSTINs and perform testing with foreign counterparts or taxpayers.

Get Token

To obtain a token for authentication, follow these steps:

1. On the homepage of the e-Invoicing sandbox environment, click on the “Get Token” option.
2. By clicking “Get Token,” developers can understand the steps in successfully calling the authentication API. This process is mandatory and helps verify the client id’s and client secret’s correctness.
3. The URL and other credentials will be automatically populated, except for the password, which needs to be entered.
4. To view the request payload, including the password and app key, click the “Sample JSON” link. The payload will be displayed in the “Payload – plain Text” box.
5. Click on the ” Encrypt payload ” link to encrypt the password and app key using the IRP public key for the actual request payload, and click on the “Encrypt payload” link. The encrypted payload will be populated in the “Payload – encrypted” box. Developers can also copy and paste their code-generated payload during the development phase into this box for testing purposes.
6. Click on the “Generate Token” button. This will send the request to the server, retrieve the response, and populate the encrypted response JSON in the “Response – Encrypted” box.
7. To decrypt the response, click the “Decrypt Response” link. The SEK (Session Encryption Key) in the response will be decrypted using the app key, and the entire JSON response will be displayed in the “Response – Plain Text” box.

By following these steps, developers can obtain a token for authentication by calling the respective API and testing the functionality within the e-Invoicing sandbox environment.

Post Method

To understand how APIs that use the HTTP POST method work, follow these steps:

1. Click on the “Post Methods” link on the homepage. This will allow you to explore the functionality of APIs that use the POST method.
2. Select any API from the dropdown list. The respective API’s endpoint will appear in the box below. The parameters of the request header, including the authentication token, will be shown for reference. The decrypted SEK (Session Encryption Key), represented as a byte array, will be displayed as a string.
3. Click “Sample JSON” to populate the sample request JSON in the “Payload – plain text” box. Ensure that the document number is unique, the date is set to today or yesterday, and the seller’s GSTIN and pin code match the logged-in user. You can modify the values of various attributes to test and analyze how the validations work.
4. Click “Encrypt Payload” to encrypt the request JSON using the SEK. The encrypted payload will be populated in the “Payload – Encrypted” box. You can also paste your encrypted payload here to test the encryption process.
5. Click on the “Generate IRN” button. This will call the generated IRN API and post the encrypted payload. The response, i.e., the encrypted JSON, will be displayed in the “Response – Encrypted” box. The same response will be decrypted using the SEK and shown in the “Response – Plain Text” box. You can see the acknowledgement number, date, and IRN in the response.
6. If E-Way Bill generation is part of the request, the response will include E-Way Bill details, a signed invoice, and a signed QR code. Other POST APIs work similarly, with differences in the endpoint and the request payload in the “Request – plain text” box.

Following these steps, you can explore and test the functionality of APIs that use the HTTP POST method within the e-Invoicing sandbox environment.

Get Method

To understand how APIs that use the HTTP GET method work, follow these steps:

1. Click on the “Get Methods” link on the homepage. This will allow you to explore the functionality of APIs that use the GET method.
2. Choose one API from the dropdown list similar to the APIs you explored using the POST method. For example, you can choose the “Get e-invoice by IRN” API. If you have an already generated IRN, you can paste it in the box below. The complete URL will be displayed, including the IRN as the parameter value. The header parameters, authentication token, and SEK will also be shown.
3. Click on the “Get Request Response” button. This will call the Get IRN details API. The “Response – Encrypted” box will display the encrypted JSON response. You can decrypt the response using the SEK, and the decrypted response will be shown in the “Response – Plain Text” box.
4. Other GET APIs work similarly, with differences in the endpoint and how the required attributes are passed in the URL.

In the right-side menu, you’ll find the following options:

1. “Get public key”: This link provides the public key for encrypting the password and app key when authenticating in the sandbox environment.
2. “API Endpoints”: This section lists all the endpoints for the published APIs.
3. “Encrypt/Decrypt”: This tool allows you to verify and compare your encryption and decryption outputs with the outputs generated by the tool. You need to provide the SEK used and the string to be encrypted or decrypted.
4. “Validate JSON”: This option helps you validate the JSON created by your end-user application against the schema.

By following these steps and utilizing the options in the right-side menu, you can explore and test the functionality of APIs that use the HTTP GET method within the e-Invoicing sandbox environment.

To access further details and explore the features of the e-Invoicing sandbox environment, please visit the website https://einv-apisandbox.nic.in. This website will provide comprehensive information, resources, and tools related to e-Invoicing APIs, including registration, authentication, API specifications, testing tools, and more. You can refer to the website for detailed documentation, examples, and any updates related to the e-Invoicing APIs.