Products

Tools

Resources

Company

Support

Request Callback

GST GST Supply GST Invoicing

API Presentation - E-Invoice to IRP Proposed Handshake API

Seep Gupta at May 27, 2024

Invoice Template

Invoice – Mandatory Info...

Invoice Template

E-Invoice JSON - Objects

Header Details	This section has Tax Scheme, Version, Invoice Reference No.
Transaction Details	This section has Transaction category, type,
Document Details	This section has the Document Type, Number, Date etc
Seller Details	This section contains the Seller GSTIN, Tradename, Address etc
Buyer Details	This section contains the Buyer GSTIN, Tradename, Address etc
Dispatch Details	Contains Dispatch GSTIN, Tradename, Address etc
Ship To Details	Contains the Ship To GSTIN, Tradename, Address etc
Item Details	This section contains details of Line Items
Document Total	This section contains all total values of the document
Payment Details	This section contains Payment details and conditions
Reference Details	This section contains various References related to invoice

Types of Transactions

B2B: Business toBusiness
B2G: Business to Government
Export
Through eComm.Operators
Reverse Chargetransactions

Types of Documents

Invoices
Debit Note
Credit Note
Not to be entered
- Delivery challan
- Bill of Supply
- Job works

Invoice Reference Number (IRN)

User can upload invoice details
Unique number (IRN) is generated fore-invoice.
IRN is a HASH of (<Supplier GSTIN><Fin. Year><Doc Type> <Doc Number>)
HASH is generated usingSHA256
Example:

– HASH of “01AAAAB1234C1Z02019-20INVAB1234” is 35054cc24d97033afc24f49ec4444dbab81f542c555f9d30359dc75794e06bb e

Note: Document number will be trimmed if prefixed with 0 / -, while generating HASH

– 00234 à 234 ; /A234 à A234 ; -0123/19 à 123/19

List of APIs

Authentication (POST)
Generate IRN(POST)
Cancel IRN(POST)
Get e-Invoice by IRN (GET)
Get GSTIN details(GET)
Health Check API (GET)

AUTH API

Mandatory to get authenticated with the e-Invoice system to use any of the API
Once successfully authenticated, a token and session encryption key (SEK)is obtained
Token is valid for 6 hours, any call to the Auth. API within expiry period will return same token and SEK
To get new token within stipulated time of expiry (10 mins before expiry time), a call to the Auth. API with the parameter “ForceRefreshAccessToken” set to “True” will force the system to generate new token
SEK will be used to encrypt the payload of the subsequent POST API requests and to decrypt response payload using AES 256 (AES/ECB/PKCS7Padding) symmetric algorithm

AUTH API - Flow

AUTH API - Request

Specifications

Specifications	Parameter	Value
	URL	https://api.envoice1.gst.gov.in/v1/auth
	Content Type	Application/json
	Method	Post

Request Header Parameters	Attributes	Description
	client_id	Client-Id generated on the system
	client_secret	Client secret generated on the system

Request Payload Parameters	Data Attributes	Description
	UserName	Registered User name for API
	Password	Registered Password, the password should be encrypted with the public key provided by eInvoice System using RSA
	Password	Algorithm
	AppKey	AES key generated by the consuming system. AppKey should be encrypted using the public key provided by eInvoice system using RSA Algorithm
	ForceRefreshAccessToke	The value of this attribute to be set true, if client needs to

Other APIs - Flow

E-Invoicing API Sample JSON

- Sample JSON for generation of IRN

JSON Schema

- JSON Schema for Generate IRN API

Generate IRN API – Response Payload:

Generate IRN API

Signing Process

JSON Web Token(JWT) and JSON Web Signature (JWS) is used to sign the
JWS is a compact signature format for representing signed content using JSON data It contains Header, Payload and Signature.
Signing Algorithm
The public key to verify signature will be provided

SignedInvoice
"SignedInvoice": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGRzaWctbW9y ZSNyc2Etc2hhMjU2Iiwia2lkIjoiRTc4MDhFNkZGMDNFMTMyODUzMzBCMD QxQjNFMEEzQUVDNDc4MTMyMCIsInR5cCI6IkpXVCIsIng1dCI6IjU0Q09iX0Et RXloVE1MQkJzLUNqcnNSNEV5QSJ9.eyJkYXRhIjoie1wiQWNrTm9cIjpudWxsL FwiQWNrRHRcIjpudWxsLFwiVGF4U2NoXCI6bnVsbCxcIlZlcnNpb25cIjpcIjEu MDBcIixcIklyblwiOlwiYTVjMTJkY2E4MGU3NDMzMjE3NDBiMDAxZmQ3MDk 1M2U4NzM4ZDEwOTg2NWQyOGJhNDAxMzc1MGYyMDQ2ZjIyOVwiLFwiVH JhbkR0bHNcIjp7XCJDYXRnXCI6XCJCMk… XCI6bnVsbCxcIld0aFBheVwi Om51bGwsXCJTaGlwQk5vXCI6bnVsbCxcIlNoaXBCRHRcIjpcIjIwMTktMTEtMj VcIixcIlBvcnRcIjpudWxsLFwiSW52Rm9yQ3VyXCI6MCxcIkZvckN1clwiOlwiQk RUXCIsXCJDbnRDb2RlXCI6XCJCRFwifSxcIlBheUR0bHNcIjp7XCJOYW1cIjpud WxsLFwiTW9kZVwiOm51bGwsXCJGaW5JbnNCclwiOm51bGwsXCJQYXlUZXJ tXCI6bnVsbCxcIlBheUluc3RyXCI6bnVsbCxcIkNyVHJuXCI6bnVsbCxcIkRpckRy XCI6bnVsbCxcIkNyRGF5XCI6bnVsbCxcIkJhbEFtdFwiOm51bGwsXCJQYXlEdW VEdFwiOm51bGwsXCJBY2N0RGV0XCI6bnVsbH0sXCJSZWZEdGxzXCI6e1wiS W52Um1rXCI6bnVsbCxcIkludlN0RHRcIjpcIjIwMTktMTEtMjVcIixcIkludkVuZE R0XCI6XCIyMDE5LTExLTI1XCIsXCJQcmVjSW52Tm9cIjpudWxsLFwiUHJlY0lud kR0XCI6XCIyMDE5LTExLTI1XCIsXCJJbnZSZWZOb1wiOm51bGwsXCJSZWNBZ HZSZWZcIjpudWxsLFwiVGVuZFJlZlwiOm51bGwsXCJDb250clJlZlwiOm51bGw sXCJFeHRSZWZcIjpudWxsLFwiUHJvalJlZlwiOm51bGwsXCJQT1JlZlwiOm51bG x9fSIsImlzcyI6Ik5JQyJ9.CdNf2N- bAlTFg_5LqlcBk7taZAhu0obLS2Wdw4NotgO69o6Rza3lABjzwsIslPWWsp8du 2OPPTGHPT_Sya- 2oPVyImmGqU2c0kNuHNvXXmlrHitlQR1v0xe42MRFFPGeIqDczIIOLQWvxO GmH_6ad-YdHJgvMw4PpCKfiHmrLiNQeoZuO2jH- 7IXQrOmmZfdnIEbGiM_R7Tn46MD3jvQwQ8tIDs659c3PVHkm64SEgoj9itQq uGUvS4qHCIojij3-J-drcM6qPwai- 8aTNFyKvkvSJqbHg6BYEfJwFf7G0j7oE8SPjPGhUnFVLH5GcI6mImaWXq9MU oqteG0HMqezQ"	<-->	{ "alg": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", "kid": "E7808E6FF03E13285330B041B3E0A3AEC4781320", "typ": "JWT", "x5t": "54COb_A-EyhTMLBBs-CjrsR4EyA" } . { "data": "{\"AckNo\":null,\"AckDt\":null,\"TaxSch\":null,\"Version\":\"1.00\",\"Irn\":\"a5c12dca80e7 43321740b001fd70953e8738d109865d28ba4013750f2046f229\",\"TranDtls\":{\"Catg\":\"B 2B\",\"RegRev\":\"RG\",\"Typ\":\"REG\",\"EcmTrn\":\"N\",\"EcmGstin\":null},\"DocDtls\":{\ "Typ\":\"INV\",\"No\":\"sadsd\",\"Dt\":\"2019-11-25\", \"OrgInvNo\":null}, \"SellerDtls\":{ \"Gstin\":\"37BZNPM9430M1kl\", \"TrdNm\":\"TAN TEST NIC\", \"Bno\":\"TEST2\", \"Bnm\":\"TEST1\",\"Flno\":\"3RD FLOOR\", \"Loc\": \"GANDHINAGAR\“ , \"Dst\":null, \"Pin\":518001, \"Stcd\":37, \"Ph\":null,\ "Em\":null}, \"BuyerDtls\": {\"Gstin\":\"37BZNPM9430M1kl\", \"TrdNm\":\"TAN TEST NIC\", \"Bno\":\"TEST2\", \"Bnm\":\"TEST1\", \"Flno\":\"3RD FLOOR\", \"Loc\": \"GANDHINAGAR\", \"Dst\":null, \"Pin\":518001, …….\"ItemList\": [{\"PrdNm\":\"dfasf\", \"PrdDesc\":\"dfdfsdf\", \"HsnCd\":\"10\", \"Barcde\":null, \"Qty\":10, \"FreeQty\":null, \ "Unit\":\"bag\", \"UnitPrice\":0, \"TotAmt\":0, \"Discount\":0, \"OthChrg\":0, \"AssAmt\":0, \"CgstRt\":1.500, \"SgstRt\":0, \"IgstRt\":0, \"CesRt\":15.000, \"CesNonAdVal\":0, \"StateCes\": \":null, \"BalAmt\":null,\"PayDueDt\":null, \"AcctDet\":null}, \"RefDtls\":{ \"InvRmk\":null, \"InvStDt\":\"2019-11-25\", \"InvEndDt\":\"2019-11-25\", \"PrecInvNo\":null, \"PrecInvDt\":\"2019-11-25\",\"InvRefNo\":null, \"RecAdvRef\":null, \"TendRef\":null, \"ContrRef\":null, \"ExtRef\":null,\"ProjRef\":null,\"PORef\":null}}", "iss": "NIC" } . [Signature]

SignedQRCode
"SignedQRCode": "eyJhbGciOiJodHRwOi8vd3d3LnczLm9yZy8yMDAxLzA0L3htbGR zaWctbW9yZSNyc2Etc2hhMjU2Iiwia2lkIjoiRTc4MDhFNkZGMD NFMTMyODUzMzBCMDQxQjNFMEEzQUVDNDc4MTMyMCIsIn R5cCI6IkpXVCIsIng1dCI6IjU0Q09iX0EtRXloVE1MQkJzLUNqcnNS NEV5QSJ9.eyJkYXRhIjoie1wiU2VsbGVyR3N0aW5cIjpcIjM3QlpO UE05NDMwTTFrbFwiLFwiQnV5ZXJHc3RpblwiOlwiMzdCWk5QT Tk0MzBNMWtsXCIsXCJEb2NOb1wiOlwic2Fkc2RcIixcIkRvY1R5cF wiOlwiSU5WXCIsXCJEb2NEdFwiOlwiMjAxOS0xMS0yNVwiLFwiV G90SW52VmFsXCI6MTU0LjAwLFwiSXRlbUNudFwiOjEsXCJNYWl uSHNuQ29kZVwiOlwiMTBcIixcIklyblwiOlwiYTVjMTJkY2E4MGU 3NDMzMjE3NDBiMDAxZmQ3MDk1M2U4NzM4ZDEwOTg2NW QyOGJhNDAxMzc1MGYyMDQ2ZjIyOVwifSIsImlzcyI6Ik5JQyJ9.X4 mcdHWj1N1BCu47AP2sUqkndbTpJ_fyUHo_vRH9C4st6360mVz d7FOp4Oes3kTA6_z- a1fgro6cZaf_Lh3Tda1RK0mnJOC7U1RThhOS39C- mZyTukuZ_p6gZGujmVjtppjFa1oKGQF5PaIU16TI3pddkbaBkFPR QZFyC-OIxsN9r8Q8-pzaVnZCRJ8eVEqU3Q- XRWBGw1zpLBgyP62XW6rdg1eztQcQ2x7cgXGBAOn8AznaZjob AJ7ttfRBWwQFz9oqoyEvyDdrZYPnkGzMryc_eCZFbs8g7NrrtZnZ az9BFgIxIvFJIUwj_tYZ6PD7sN2iV-PSiKVm5-Frd8H0jA", "	<-->	{ "alg": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256", "kid": "E7808E6FF03E13285330B041B3E0A3AEC4781320", "typ": "JWT", "x5t": "54COb_A-EyhTMLBBs-CjrsR4EyA" } . { "data": "{\"SellerGstin\":\"37BZNPM9430M1kl\", \"BuyerGstin\":\"37BZNPM9430M1kl\", \"DocNo\":\"sadsd\", \"DocTyp\":\"INV\", \"DocDt\":\"2019-11-25\", \"TotInvVal\":154.00, \"ItemCnt\":1, \"MainHsnCode\":\"10\", \"Irn\":\"a5c12dca80e743321740b001fd70953e8738d109865d28ba401 3750f2046f229\"}", "iss": "NIC" } . [Signature]

CANCEL API - REQUEST

Cancel IRN API – Response Payload:

API Users

Presently, enabled for Tax Payers with TO > Rs 500Crores
These Tax Payers and GSPs will get access for API
GSPs will get Client Id and Client Secret
Tax Payers, using GSPs interface, will get API User Name and Password
Tax Payers, using direct APIs, will get Client Id, Client Secret, API User Name and Password
Group of Tax Payers, having one PAN, can use one Client Id and Client Secret
IRN can be generated only for Tax payers with TO > Rs 500Crores

Sandbox Access – On-boarding

Separate URL will be provided
Online Registration by GSP and Identified TaxPayers
Client Id and Client Secret can be generated by tax payers and GSPs online by Mobile and email Id OTP authentication
GSPs can use dummy GSTIN for testing
Online API username and password can be generated
Online testing facility like JSON validation, encryption, decryption, signing will be available

Production – On-Boarding

Online Registration for GSPs and Identified TaxPayers
Online Generation of Client ID and Client Secret
Online generation of API User Name and Password by Tax Payers
Online linking of API user (GSTIN) with GSPs and Tax Payer Group (PAN based)
Security Auditing (through CERT-In empanelled agency, by GSP/Tax Payer on application and system
White listing of static IPs
Indian Static IPs are only allowed

Best Practices of API Interface

Understanding of the invoicing system of the company by the developers
Don’t generate Token for each time
Store Token, SEK and Expiry time and use till expiry
Validate the data before submission, as per the JSON Schema and business rules
Re-generate Token before 10 minutes of expiry
Don’t hard code SSL Certificate with API interface
Check response and status and act

About the Author

Seep Gupta

Content Writer

I am a freshly graduated first generation lawyer and a freelancer from India. I have written high quality articles and SEO based Word Press blogs in varying and diverse niches. My driving forc Read more...

Rate your experience