API – Generate IRN

This API is used to register the invoice, credit note and debit note and get the Invoice Registration Number (IRN).

#URL

POST https://app.octagst.com/api/einvoice/generateirn

#Query Parameters

Name	Description	Type	Value	Default
qrcode	Include QR Code image in response	Optional	yes, no	no
qrcodeformat	QR code image format	Optional	PNG, JPEG, GIF	PNG
qrcodequality	QR code image quality	Optional	standard, high	high
pdf	Include e-invoive pdf and e-waybill pdf in response	Optional	yes, no	no

#Request

#Structure

Parameter	Data Type	Type	Description
Version	String(6)	Mandatory	Schema version 1.1
TranDtls	Object	Mandatory	This object contains transaction details
TaxSch	String(10)	Mandatory	Tax Scheme GST
SupTyp	String(10)	Mandatory	Supply Type B2B:B2B Supply SEZWP: SEZ supply with payment of IGST SEZWOP: SEZ supply without payment of IGST EXPWP: Export with payment of IGST EXPWOP: Export without payment of IGST DEXP: Deemed Export B2C: B2C Supply
RegRev	String	Optional	Reverse Charge Y: Yes N: No
EcmGstin	String(15)	Optional	GSTIN of E-Commerce operator
IgstOnIntra	String(1)	Optional	IGST on Intrastate Supply Y: Yes N: No
DocDtls	Object	Mandatory	This object contains document details
Typ	String	Mandatory	Document Type INV: Invoice CRN: Credit Note DBN-Debit Note
No	String(16)	Mandatory	Document No A-Z, 0-9, /, -
Dt	String(10)	Mandatory	Document Date DD/MM/YYYY
SellerDtls	Object	Mandatory	This object contains the Seller details like GSTIN, Tradename, Address etc
Gstin	String(15)	Mandatory	GSTIN
LglNm	String(100)	Mandatory	Legal Name as appearing in PAN
TrdNm	String(100)	Optional	Trade name, if available. (Business Name, other than legal name)
Addr1	String(100)	Mandatory	Address-1
Addr2	String(100)	Optional	Address-2
Loc	String(100)	Mandatory	Location (City/Town/Village)
Pin	Number(6)	Mandatory	Pin code
Stcd	String(2)	Mandatory	State Code
Ph	String(12)	Optional	Phone No
Em	String(100)	Optional	Email
BuyerDtls	Object	Mandatory	This object contains the Buyer details like GSTIN, Tradename, Address etc
Gstin	String(15)	Optional	Buyer GSTIN, required for B2B invoices
LglNm	String(100)	Mandatory	Legal Name as appearing in PAN
TrdNm	String(100)	Optional	Trade name, if available. (Business Name, other than legal name)
Addr1	String(100)	Mandatory	Address-1
Addr2	String(100)	Optional	Address-2
Loc	String(100)	Mandatory	Location (City/Town/Village)
Pin	Number(6)	Optional	Pin code
Stcd	String(2)	Optional	State Code
Ph	String(12)	Optional	Phone No
Em	String(100)	Optional	Email
DispDtls	Object	Optional	This object contains the Dispatch details like business name, Address etc
Nm	String(100)	Mandatory	Business entity name
Addr1	String(100)	Mandatory	Address-1
Addr2	String(100)	Optional	Address-2
Loc	String(100)	Mandatory	Location (City/Town/Village)
Pin	Number(6)	Mandatory	Pin code
Stcd	String(2)	Mandatory	State Code
ShipDtls	Object	Optional	This object contains the Ship To details like GSTIN, Tradename, Address etc
Gstin	String(15)	Optional	GSTIN
LglNm	String(100)	Mandatory	Legal Name as appearing in PAN
TrdNm	String(100)	Optional	Trade name, if available. (Business Name, other than legal name)
Addr1	String(100)	Mandatory	Address-1
Addr2	String(100)	Optional	Address-2
Loc	String(100)	Mandatory	Location (City/Town/Village)
Pin	Number(6)	Mandatory	Pin code
Stcd	String(2)	Mandatory	State Code
ItemList	Item[]	Mandatory	This object contains list of line items.
Item	Object	Mandatory	This object contains details of line item
SlNo	String(6)	Optional	Serial no of line item. Only digits are allowed.
PrdDesc	String(300)	Optional	Product/Item
IsServc	String(1)	Optional	Whether line item is good or service Y: Yes N: No
HsnCd	String(8)	Mandatory	HSN Code
Qty	Number(10,3)	Optional	Quantity
FreeQty	Number(10,3)	Optional	Free quantity
Unit	String(3)	Mandatory	UQC
UnitPrice	Number(12,2)	Mandatory	Unit price
TotAmt	Number(12,2)	Optional	Item gross amount (Qty * UnitPrice)
Discount	Number(12,2)	Optional	Discount
PreTaxVal	Number(12,2)	Optional	Pre Taxable Value
AssAmt	Number(12,2)	Optional	Item Taxable Value (Total Amount - Discount)
GstRt	Number(3,3)	Mandatory	GST Rate
IgstAmt	Number(12,2)	Optional	IGST Amount
CgstAmt	Number(12,2)	Optional	CGST Amount
SgstAmt	Number(12,2)	Optional	SGST Amount
CesRt	Number(3,3)	Optional	Cess Rate
CessAmt	Number(12,2)	Optional	Cess Amount
CesNonAdvlAmt	Number(12,2)	Optional	Cess Nonadvol Amount
StateCesRt	Number(3,3)	Optional	State Cess Rate
StateCesAmt	Number(12,2)	Optional	State Cess Amount
StateCesNonAdvlAmt	Number(12,2)	Optional	State Cess Nonadvol Amount
OthChrg	Number(12,2)	Optional	Other charges
TotAmt	Number(12,2)	Optional	Total Item Value (TaxableValue + Igst Amount + Cgst Amount + Sgst Amount + Cess Amount + Cess Nonadvol + State cess amount + State Cess Non advol + Other charges)
OrdLineRef	String(50)	Optional	Order line Referencee
OrgCntry	String(2)	Optional	Origin Country
OthSerialNumber	String(20)	Optional	Product Serial Number
Barcde	Number(12,2)	Optional	Bar code
Item.BchDtl	Object	Optional	This object contains details of batch
Nm	String (20)	Mandatory	Batch Name/Number
ExpDt	String(10)	Optional	Batch Expiry Date DD/MM/YYYY
WrDt	String(10)	Optional	Batch Warranty Date DD/MM/YYYY
Item.AttribDtls[]	Attribute[]	Optional	This object contains details of item attributes
Attribute	Object	Optional	This object contains details of line item
Nm	String (100)	Mandatory	Attribute Name
Val	String(100)	Mandatory	Attribute value
ValDtl	Object	Optional	This object contains details of document totals
AssVal	Number(14,2)	Optional	Total taxable value.
IgstVal	Number(14,2)	Optional	Total IGST Amount
CgstVal	Number(14,2)	Optional	Total CGST Amount
SgstVal	Number(14,2)	Optional	Total SGST Amount
CesVal	Number(14, 2)	Optional	Total Cess Amount
StCesVal	Number(14,2)	Optional	Total State Cess Amount
Discount	Number(14,2)	Optional	Invoice Discount
OthChrg	Number(14,2)	Optional	Invoice Other charges
RndOffAmt	Number(2,2)	Optional	Round off Amount
TotInvVal	Number(14,2)	Optional	Total document value
TotInvValFc	Number(14,2)	Optional	Total document value in foreign currency
PayDtl	Object	Optional	This object contains payment details
Nm	String(100)	Optional	Payee Name
Mode	String(18)	Optional	Mode of Payment
FinInsBr	String(11)	Optional	Branch or IFSC Code
PayTerm	String(100)	Optional	Payment Term
PayInstr	String(100)	Optional	Payment Instruction
CrTrn	String(100)	Optional	Credit Transfer
DirDr	String(100)	Optional	Direct Debit
CrDay	Number(4)	Optional	Credit Days
PaidAmt	Number(14,2)	Optional	Paid Amount
PaymtDue	Number(14,2)	Optional	Payment Due
AccDet	String(18)	Optional	Bank Account Details
RefDtl	Object	Optional	This object contains reference details
InvRm	String(100)	Optional	Document Remarks
InvStDt	String(10)	Mandatory	Invoice Period Start Date DD/MM/YYYY
InvEndDt	String(10)	Mandatory	Invoice Period End Date DD/MM/YYYY
PrecDocDtls[]	PrecedindDoc[]	Optional	This object contains details of preceding issued documents
PrecedindDoc	Object	Optional	This object contains preceding document details
InvNo	String(16)	Mandatory	Preceding Invoice Number
InvDt	String(10)	Mandatory	Preceding Invoice Date DD/MM/YYYY
OthRefNo	String(20)	Optional	Other Reference
ContrDtls[]	ContractRef[]	Optional	This object contains details of contract reference documents
ContractRef	Object	Optional	This object contains contract references
RecAdvRefr	String(20)	Optional	Receipt Advice No
RecAdvDt	String(10)	Optional	Receipt Advice Date DD/MM/YYYY
TendRefr	String(20)	Optional	Lot/Batch Reference No
ContrRefr	String(20)	Optional	Contract Reference Number
ExtRefr	String(20)	Optional	Any Other Reference
ProjRefr	String(20)	Optional	Project Reference
PORefr	String(20)	Optional	PO Reference Number
PORefDt	String(10)	Optional	PO Reference Date DD/MM/YYYY
AddlDtls[]	AddlDoc[]	Optional	This object contains details of additional documents
AddlDoc	Object	Optional	This object contains additional document details
Url	String(100)	Optional	Additional supporting documents URL
Docs	String(1000)	Optional	Additional supporting documents in base64
Info	String(1000)	Optional	Additional information
ExpDtl	Object	Optional	This object contains details of export invoice
ShipBNo	String(20)	Optional	Shipping Bill No
ShipBDt	String(10)	Optional	Shipping Bill Date DD/MM/YYYY
Port	String(10)	Optional	Port Code
RefClm	String(1)	Optional	Refund Claim Y: Yes N: No
ForCur	String(16)	Optional	Foreign Currency
CntCode	String(2)	Optional	Country Code
ExpDuty	Number(12,2)	Optional	Export Duty
EwbDtls	Object	Optional	This object contains EWaybill details
TransId	String(15)	Optional	Transporter Id
TransName	String(100)	Optional	Transport Name
TransMode	String(1)	Optional	Transport Mode 1: Road 2: Rail 3: Air 4: Ship
Distance	Number(4)	Mandatory	Distance
TransDocNo	String(15)	Optional	Transporter Doc No
TransDocDt	String(10)	Optional	Transporter Doc Date DD/MM/YYYY
VehNo	String(20)	Optional	Vehicle No
VehType	String(1)	Optional	Vehicle Type R: Regular O: Over-Dimensional Cargo (ODC)

Please visit NIC eInvoice portal to get masters defined for State Codes, UQC, Currency codes, Country codes, Port codes, HSN, PIN codes.

Master Codes on NIC Portal →

#Sample

Request payload should contain the JSON encoded invoice data:

{
  "Version": "1.1",
  "TranDtls": {
    "TaxSch": "GST",
    "SupTyp": "B2B",
    "RegRev": "Y",
    "EcmGstin": null,
    "IgstOnIntra": "N"
  },
  "DocDtls": {
    "Typ": "INV",
    "No": "MAHI/10",
    "Dt": "08/08/2020"
  },
  "SellerDtls": {
    "Gstin": "29AABCT1332L000",
    "LglNm": "ABC company pvt ltd",
    "TrdNm": "NIC Industries",
    "Addr1": "5th block, kuvempu layout",
    "Addr2": "kuvempu layout",
    "Loc": "GANDHINAGAR",
    "Pin": 560001,
    "Stcd": "29",
    "Ph": "9000000000",
    "Em": "abc@gmail.com"
  },
  "BuyerDtls": {
    "Gstin": "29AWGPV7107B1Z1",
    "LglNm": "XYZ company pvt ltd",
    "TrdNm": "XYZ Industries",
    "Pos": "37",
    "Addr1": "7th block, kuvempu layout",
    "Addr2": "kuvempu layout",
    "Loc": "GANDHINAGAR",
    "Pin": 560004,
    "Stcd": "29",
    "Ph": "9000000000",
    "Em": "abc@gmail.com"
  },
  "DispDtls": {
    "Nm": "ABC company pvt ltd",
    "Addr1": "7th block, kuvempu layout",
    "Addr2": "kuvempu layout",
    "Loc": "Banagalore",
    "Pin": 518360,
    "Stcd": "37"
  },
  "ShipDtls": {
    "Gstin": "29AWGPV7107B1Z1",
    "LglNm": "CBE company pvt ltd",
    "TrdNm": "kuvempu layout",
    "Addr1": "7th block, kuvempu layout",
    "Addr2": "kuvempu layout",
    "Loc": "Banagalore",
    "Pin": 518360,
    "Stcd": "37"
  },
  "ItemList": [
    {
      "SlNo": "1",
      "IsServc": "N",
      "PrdDesc": "Rice",
      "HsnCd": "1001",
      "Barcde": "123456",
      "BchDtls": {
        "Nm": "123456",
        "Expdt": "01/08/2020",
        "wrDt": "01/09/2020"
      },
      "Qty": 100.345,
      "FreeQty": 10,
      "Unit": "NOS",
      "UnitPrice": 99.545,
      "TotAmt": 9988.84,
      "Discount": 10,
      "PreTaxVal": 1,
      "AssAmt": 9978.84,
      "GstRt": 12,
      "SgstAmt": 0,
      "IgstAmt": 1197.46,
      "CgstAmt": 0,
      "CesRt": 5,
      "CesAmt": 498.94,
      "CesNonAdvlAmt": 10,
      "StateCesRt": 12,
      "StateCesAmt": 1197.46,
      "StateCesNonAdvlAmt": 5,
      "OthChrg": 10,
      "TotItemVal": 12897.7,
      "OrdLineRef": "3256",
      "OrgCntry": "AG",
      "PrdSlNo": "12345",
      "AttribDtls": [
        {
          "Nm": "Rice",
          "Val": "10000"
        }
      ]
    }
  ],
  "ValDtls": {
    "AssVal": 9978.84,
    "CgstVal": 0,
    "SgstVal": 0,
    "IgstVal": 1197.46,
    "CesVal": 508.94,
    "StCesVal": 1202.46,
    "Discount": 10,
    "OthChrg": 20,
    "RndOffAmt": 0.3,
    "TotInvVal": 12908,
    "TotInvValFc": 12897.7
  },
  "PayDtls": {
    "Nm": "ABCDE",
    "Accdet": "5697389713210",
    "Mode": "Cash",
    "Fininsbr": "SBIN11000",
    "Payterm": "100",
    "Payinstr": "Gift",
    "Crtrn": "test",
    "Dirdr": "test",
    "Crday": 100,
    "Paidamt": 10000,
    "Paymtdue": 5000
  },
  "RefDtls": {
    "InvRm": "TEST",
    "DocPerdDtls": {
      "InvStDt": "01/08/2020",
      "InvEndDt": "01/09/2020"
    },
    "PrecDocDtls": [
      {
        "InvNo": "DOC/002",
        "InvDt": "01/08/2020",
        "OthRefNo": "123456"
      }
    ],
    "ContrDtls": [
      {
        "RecAdvRefr": "DOC/002",
        "RecAdvDt": "01/08/2020",
        "Tendrefr": "Abc001",
        "Contrrefr": "Co123",
        "Extrefr": "Yo456",
        "Projrefr": "Doc-456",
        "Porefr": "Doc-789",
        "PoRefDt": "01/08/2020"
      }
    ]
  },
  "AddlDocDtls": [
    {
      "Url": "https://einv-apisandbox.nic.in",
      "Docs": "Test Doc",
      "Info": "Document Test"
    }
  ],
  "ExpDtls": {
    "ShipBNo": "A-248",
    "ShipBDt": "01/08/2020",
    "Port": "INABG1",
    "RefClm": "N",
    "ForCur": "AED",
    "CntCode": "AE"
  },
  "EwbDtls": {
    "Transid": "12AWGPV7107B1Z1",
    "Transname": "XYZ EXPORTS",
    "Distance": 100,
    "Transdocno": "DOC01",
    "TransdocDt": "01/08/2020",
    "Vehno": "ka123456",
    "Vehtype": "R",
    "TransMode": "1"
  }
}

#Response

Response payload will contain the success status along with IRN information.

#Structure

Parameter	Data Type	Description
Success	Boolean	true in case of success
AckNo	String	Acknowledgement number
AckTime	String	Acknowledgement Date & time DD/MM/YYYY HH:MM:SS
Irn	String	Invoice reference number generated
IrnStatus	String	IRN Status ACT: Active CNL: Cancelled
SignedInvoice	String (Binary data in Base64 URL encoding)	Signed invoice data as received from IRP
SignedQRCode	String (Binary data in Base64 URL encoding)	Signed QR code as received from IRP
EwbStatus	String	EWB Status ACT: Active CNL: Cancelled
EwbNo	String	e-waybill Number(present only if e-waybill is generated along with e-invoice)
EwbTime	String	e-waybill generation Date & time DD/MM/YYYY HH:MM:SS
EwbValidTill	String	e-waybill validity Date & time DD/MM/YYYY HH:MM:SS
QRCodeImagePng	String (Binary data in Base64 encoding)	e-Invoice QR code PNG image
QRCodeImageJpeg	String (Binary data in Base64 encoding)	e-Invoice QR code JPEG image
QRCodeImageGif	String (Binary data in Base64 encoding)	e-Invoice QR code GIF image
EinvoicePdf	String (Binary data in Base64 encoding)	e-Invoice PDF file
EwbPdf	String (Binary data in Base64 encoding)	e-waybill PDF file
Errors	Error[]	List of errors, will be present only when Success is false

#Error

Parameter	Data Type	Description
Code	String	Error Code
Message	String	Error message

#Sample – Success

{
  "Success": true,
  "AckNo": "112010000002315",
  "AckTime": "27/11/2020 17:23:45",
  "IrnStatus": "ACT",
  "Irn": "11f8ef741fe294d4a14aad0b12457e62775d0fdc41a0dcf05b74fbb2ddc47acb",
  "SignedInvoice": "eyJhbGc...gumxIpg",
  "SignedQRCode": "eyJhbGc...oOZvxpw",
  "EwbStatus": "ACT",
  "EwbNo": "191008688443",
  "EwbTime": "27/11/2020 17:23:45",
  "EwbValidTill": "29/11/2020 17:23:45",
  "QRCodeImagePng": "gy72zt...3AAAAAElFTkSuQmCC",
  "QRCodeImageJpeg": null,
  "QRCodeImageGif": null,
  "EinvoicePdf": "i7gahsd...GY899RfTkSueba781Fg",
  "EwbPdf": "utwf19...34566AAAElFTkSuQmCC"
}

#Sample – Failure

If the API request fails for some reasons, the response payload will contain the failure status and a list of errors.

{
  "Success": false,
  "Errors": [
    {
      "Code": "ERR_CODE_1",
      "Message": "ERR MESSAGE 1"
    },
    {
      "Code": "ERR_CODE_n",
      "Message": "ERR MESSAGE n"
    }
  ]
}