E-invoice System – API Sandbox

National Informatics Centre

07/27/2021 E-invoice System - Highlights :: National Informatics Centre 1

Introduction to E Invoice Developer Portal
• All information required for ERP and Financial Accounting Software
developers to integrate e-Invoicing System through API
• Registration for testing the APIs on Sandbox environment
• General Information like Introduction, Overview, Benefits, Onboarding
procedure, best practices, FAQs etc.
• Announcements on latest developments etc.
• API Documentation including specifications, Sample payloads, JSON
schemas, Validation details etc.
• Master lists, Sample Codes etc.
• Online API Testing Tool

07/27/2021 API Sanbox Tool :: National Informatics Centre 2

07/27/2021 API Sanbox Tool :: National Informatics Centre 3
Registration
• Eligible Tax Payers, GSPs can register for testing the APIs on the Sandbox
• While registering, the OTP would be sent to the registered Mobile Number and eMail id.
• Credentials include Client_Id, Client_Secret, User_Id and Password
• After successfully registering, user has to login in to the portal for
• Checking the correctness of the credentials created
• To add additional accounts for eligible GSTINs by GSPs , additional GSTINs based on same PAN by
Tax Payers
• To use the online API test tool to understand the working of the APIs before actually start coding
• To get the required end points for all APIs and Public Key
• To use and understand other tools like encryption / decryption, verification of digitally signed e-
Invoice and QR code etc.
• Facility for retrieving forgotten credentials

07/27/2021 API Sanbox Tool :: National Informatics Centre 4

Registration form

07/27/2021 API Sanbox Tool :: National Informatics Centre 5

Online Test Tool
• Shows working of the APIs through step by step
• To understand the working of APIs, alter the request payloads and see
the effect of such changes
• Compare the outputs in the intermediate stages such as output after
encryption step, decryption step etc.
• Can send the encrypted payload that is generated using own code
through this tools to verify the encryption logic and similarly for
decryption etc.

07/27/2021 API Sanbox Tool :: National Informatics Centre 6

07/27/2021 API Sanbox Tool :: National Informatics Centre 7
Add GSTIN
• GSPs can add test account for any of their eligible users, users will use
GSPs Client_Id, Client_Secret and their own User_Id and Password
• Virtual ids similar to GSTINs are created for GSPs based on their PAN
to test the APIs internally. GSPs can create one account each for each
State
• Tax payers can add the accounts for other GSTINs based on their own
PAN and all users will use same Client_Id and Client_Secret
• Registration process involves verification of registered mobile number
and eMail

07/27/2021 API Sanbox Tool :: National Informatics Centre 8

07/27/2021 API Sanbox Tool :: National Informatics Centre 9
List of APIs
• Authentication (POST)
• Generate IRN (POST)
• Cancel e-Invoice (POST)
• Generate E Way Bill using IRN (POST)
• Cancel E Way Bill (POST) – Separately added only for Sandbox testing
• Get e-Invoice Details (GET)
• Get GSTIN Details (GET)

07/27/2021 API Sanbox Tool :: National Informatics Centre 10

Authentication API
• Authentication of the e-Invoice System is mandatory to use any other APIs
• Once authenticated successfully, an authentication and Session Encryption Key
(SEK) will be provided. This pair will be valid for 6 hours In production and 1
hour in sandbox environment
• Calls to this API while the token is still active will return same pair of token and
SEK
• Using the ‘ForceRefreshAccessToken’ attribute set to TRUE, one can get new
token generated forcefully during last 10 minutes of validity of token
• In the production environment, token can be generated either through e-
Invoice System or E Way Bill System and can be used to call APIs of either
system

07/27/2021 API Sanbox Tool :: National Informatics Centre 11

Authentication
• Client_Id and Client_Secret will be passed in the request header
• Consuming application has to generate App_Key which is a random 32 byte array
• Password and App_Key has to be encrypted using public key of the e-Invoice Sandbox
environment
• User_Id, encrypted Password, encrypted App_Key and flag for forcefull generation of
token will be part of request JSON
• Once authenticated successfully, auth. token and encrypted SEK will be returned in the
response
• Encrypted SEK has to be decrypted using locally generated App_Key that was sent in the
request payload using symmetric algorithm
• Subsequent POST API requests have to be encrypted using the SEK and responses of all
APIs have to be decrypted using the same valid SEK

07/27/2021 API Sanbox Tool :: National Informatics Centre 12

API Test Tool:
Authentication
• Clicking on “Get Token” will show the
page that calls the Authentication API
• All credentials except password are
automatically populated
• App_Key is created, (shown as string only
for purpose of representation)
• User has to enter the Password and scroll
down Enter password

07/27/2021 API Sanbox Tool :: National Informatics Centre 13

API Test Tool:
Authentication
• Clicking on “Sample JSON” will populate
sample JSON in “Payload – Plain text” box
• Password shown is only symbolic
• Clicking on “Encrypt Payload” will encrypt
the password entered in the “Password”
field, encrypt the “App Key” generated
internally, creates the actual payload to
be posted and populates “Payload –
Encrypted” text area
• User generated payload can be pasted in
the “Payload – Encrypted” text area for
testing

(1) Click to get

Sample JSON

(2) Click to get Encrypted payload

07/27/2021 API Sanbox Tool :: National Informatics Centre 14

API Test Tool:
Authentication
• Clicking on “Generate Token” will post the
request to the Auth. API end point and
populates the response in the “Response
– Encrypted” text area
• If the call is successful, status will be
equal to 1
• SEK in response is encrypted using the
App_Key that was sent as part of request
(1) Click to Call the API and post request
• Clicking on “Decrypt Response” will
decrypt the SEK and populate the
response JSON in “Response – Plain Text”
text area
• One can paste the response received
using own code, paste the JSON, change
App_Key to test decryption algorithm
(2) Click to decrypt the SEK in response

07/27/2021 API Sanbox Tool :: National Informatics Centre 15

API Test Tool: Generate IRN
• API for generating the IRN
• Request payload should conform to the notified schema and all
validations published
• If the payload contains valid E Way Bill request payload, E Way Bill
also gets generated along with IRN
• If E Way Bill payload has issues, IRN will be generated and error
details related to E Way Bill are provided in the response
• Request and Response payloads are encrypted using the SEK with
symmetric algorithm

07/27/2021 API Sanbox Tool :: National Informatics Centre 16

API Test Tool:
Generate IRN
• Select the “Generate Einvoice” from the
dropdown
• End point will be populated, Header
parameters are assigned automatically

07/27/2021 API Sanbox Tool :: National Informatics Centre 17

API Test Tool:
Generate IRN
• Clicking “Sample Json” loads the sample
(2) Modify as
JSON in “Payload – Plain text” text area. required
• Required changes in the JSON to satisfy
validations to be made.
• Clicking on “Encrypt Payload” will encrypt (1) Click to get
the payload using available SEK and Sample JSON
populate the payload in “Payload –
(4) Call the API
Encrypted” text area. (3) Click to get Encrypted payload

• Clicking on “Generate IRN” will post the

request payload to the respective
endpoint, populates the response in
“Response – Encrypted” text area, the
encrypted response is decrypted using
the SEK and populated in “Response –
Plain text” text area

07/27/2021 API Sanbox Tool :: National Informatics Centre 18

API Test Tool: Other POST APIs
• Other POST APIs can be tested the similar way
• The request payload and endpoints differ

07/27/2021 API Sanbox Tool :: National Informatics Centre 19

API Test Tool: Get e-
Invoice Details
1. API to get the e-Invoice details
2. IRN to be pasted in “Enter Irn Number”
textbox
3. Request URL along with the required
parameter is created in “Request Url”
box
4. Required header parameters are
automatically populated
5. Clicking on the “Get Request Response”
would call the API and get the response

07/27/2021 API Sanbox Tool :: National Informatics Centre 20

API Test Tool: Get e-
Invoice Details
1. “Data” attribute in response JSON
contains encrypted data
2. Decrypting the encrypted data using SEK
with symmetric algorithm get the
response in plain text and populates
“Response – Plain Text” text area
3. Response in plain text contains
1. Acknowledge number – unique number
generated by system
2. IRN generation date
3. IRN
4. Signed Invoice
5. Signed QR Code
6. Status
7. E Way Bill details (if generated as part of
IRN generation)

07/27/2021 API Sanbox Tool :: National Informatics Centre 21

Other Utilities
• The Public Key required for encrypting
the password, App_Key and to verify
signed e-Invoice and signed QR code
• Endpoints for all APIs
• Facility to Encrypt plain text data and
decrypt encrypted data using the SEK
provided
• Tool to Check the syntax of JSONs
• Verification of Signed e-Invoice data and
Signed QR Code

07/27/2021 API Sanbox Tool :: National Informatics Centre 22

API Documentation
• Detailed documentation on each of the
APIs can be accessed from the home page
itself
• The documentation include
• Overview
• Descriptions of the Request and
Response payloads
• Samples for Request and Response
payloads
• Schema for the request payloads in case
of POST APIs
• Validations and FAQs , as applicable

07/27/2021 API Sanbox Tool :: National Informatics Centre 23

 Thank you
support.einv.api@gov.in, support.web.api@gov.in
https://einv-apisandbox.nic.in, https://einvoice1.gst.gov.in/

07/27/2021 API TestingTool :: National Informatics Centre 24