Masters India
  1. Home
  2. GST
  3. GST Supply
  4. API Presentation - E-Invoice to IRP Proposed Handshake API
GSTGST SupplyGST Invoicing

API Presentation - E-Invoice to IRP Proposed Handshake API

Seep Gupta
Seep Gupta at April 03, 2023
banner1
banner1

Invoice Template

Invoice Template  

Invoice – Mandatory Info...

Invoice Template   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 – 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
E-Invoicing
 
 

Other APIs - Flow

E-Invoicing API   Sample JSON

JSON Schema

 

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 API – REQUEST
 

Cancel IRN API – Response Payload:

Cancel IRN API

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
 
Rate your experience
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
  • ★
    ★
4.60 / 5. Vote count: 102
GST Billing Software
GST Software: Pay GST to only compliant Vendors!

Check out other Similar Posts

No Data found
No Blogs to show

Table of Contents

Automate your GST Compliances with Masters India

Request Callback
Need Help in Getting Started?
Make smart decision to replace your manual work with modern solution and improve your business output
Request Callback
Continue Browsing
See All Products
Subscribe Now!
Receive GST, E way bill, e-Invoice, Accounts payable and OCR updates from our experts.
ABOUT US

  • Masters India is a GST Suvidha Provider (GSP) appointed by Goods and Services Tax Network (GSTN), a Government of India enterprise.

CONTACT US
  • Google Play Icon
  • App Store Icon
SOCIAL LINKS
  • Facebook IconLinkedIn IconTwitter IconYoutube IconMediam
Copyright © 2023 Masters India IT Solutions Pvt. Ltd.
logo
Chat with us

😄Hello. Welcome to Masters India! I'm here to answer any questions you might have about Masters India Products & APIs. What brings you to our website today?

Looking for

GST Software

E-Way Bill Software

E-Invoice Software

BOE TO Excel Conversion

Accounts Payable Software

Invoice OCR Software/APIs

GST API

GST Verification API

E-Way Bill API

E-Invoicing API

KSA E-Invoice APIs

Vehicle tracking

Vendor Verification API

Other Requirement