- ProductsProducts
- GSTUse the latest Masters India’s GST Software, GST return filing software
- E-INVOICINGGenerate and Manage E-Invoicing directly from your ERP with E-invoicing Software
- APPSFree GST Quotation, Billing, E-Way bill and GST data Mobile and Web App
- E-WAY BILLEway Bill Software by Masters India to Reduce Compliance Effort by 93.00%
- ACCOUNTS PAYABLEAccount Payable Automation to automate workflow & monitor accountability
- ToolsTools
- GST TOOLSSearch GST taxpayer by entering GST Number
- Verify GST NumberSearch GST taxpayer by entering GST Number
- Free GST Invoice GeneratorGenerate GST Compliant Invoices for FREE
- Search GST Case LawsSearch recent GST related cases
- Check GST Return StatusOnline tool to check your GST return filing status
- GST CalculatorCalculate GST on Goods and Services
- GST Number Search By Name Or PanSearch GST taxpayer number by Name or PAN
- E-Invoice Status Of GSTINFree tool to verify the e-Invoice status of a GSTIN
- HSN TOOLOnline tool to find latest HSN codes or extract Bill of Entry (BOE)
- BOE TOOLOnline tool to find latest HSN codes or extract Bill of Entry (BOE)
- ResourcesResources
- CompanyCompany
- Support
API Presentation - E-Invoice to IRP Proposed Handshake API
Sakshi Jain at July 26, 2022
Invoice Template
Invoice – Mandatory Info...
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 | |
| 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
Sample JSON
-
- Sample JSON for generation of IRN
JSON Schema
-
- JSON Schema for Generate IRN API
Generate IRN API – Response Payload:
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
How useful was this post?
Click on a star to rate it!
- ★★
- ★★
- ★★
- ★★
- ★★
Average rating 4.60 / 5. Vote count: 102
Check out other Similar Posts
No articles found
