e-Invoice API Specifications
# Introduction
This document specifies the JSON API supported by Octa Bills Server application in order to automate the e-invoicing workflows such as generation, retrieval and cancellation of e-invoices.
# Abbreviations & References
Term | Description |
---|---|
IRN | Invoice Reference Number |
IRP | Invoice Registration Portal. Currently NIC is the only authorised IRP. |
API | Application Programmer Interface |
Base64 encoding | Method of encoding binary data in printable string |
Base64 URL encoding | Method of encoding binary data in printable string using URL safe characters |
e-Invoice Sandbox (NIC) | NIC portal of e-invoice application development |
# Authentication
API authentication is done using the http basic
authentication. This is done using the Authorization
http header in the request. This header can be constructed as follows:
- The username and password are combined with a single colon
:
. - The resulting string is encoded in byte array using UTF-8 encoding.
- The resulting string is encoded in base64 string.
- The resulting string is prefixed with the authorisation method
Basic
.
For example, if username is ramesh
and password is elephant@123
then http header would be:
Authorization: Basic cmFtZXNoOmVsZXBoYW50QDEyMw==
Key Id
and Key Secret
generated on Octa Cloud Portal are used as username and password respectively. Refer this guide to generate Key Id
and Key Secret
on Octa Cloud.
# 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://bills.octagst.com/api/einvoice/generateirn
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
qrcode | Specify yes to include QR Code image in response | Optional | yes , no (Default) |
qrcodeformat | Specify QR code image format | Optional | PNG (Default), JPEG , GIF |
qrcodequality | Specify QR code image quality | Optional | standard , high (Default) |
pdf | Specify yes to include e-invoive pdf and e-waybill pdf in response | Optional | yes , no (Default) |
# Request Payload
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"
}
}
Parameter | Data Type | Type | Description |
---|---|---|---|
Version | String(6) | Mandatory | Schema version1.1 |
TranDtls {...} | Object | Mandatory | This object contains transaction details |
TaxSch | String(10) | Mandatory | Tax SchemeGST |
SupTyp | String(10) | Mandatory | Supply TypeB2B :B2B SupplySEZWP : SEZ supply with payment of IGSTSEZWOP : SEZ supply without payment of IGSTEXPWP : Export with payment of IGSTEXPWOP : Export without payment of IGSTDEXP : Deemed ExportB2C : B2C Supply |
RegRev | String | Optional | Reverse ChargeY : YesN : No |
EcmGstin | String(15) | Optional | GSTIN of E-Commerce operator |
IgstOnIntra | String(1) | Optional | IGST on Intrastate SupplyY : YesN : No |
DocDtls {...} | Object | Mandatory | This object contains document details |
Typ | String | Mandatory | Document TypeINV : InvoiceCRN : Credit NoteDBN -Debit Note |
No | String(15) | Mandatory | Document NoAlphanumeric, /, - |
Dt | String(10) | Mandatory | Document DateDD/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 | |
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 | |
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[] | Object | Mandatory | This object contains list of line items. ItemList: Array[Item{...}-1, Item{...}-2,...] |
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 serviceY : YesN : No |
HsnCd | String(8) | Mandatory | HSN Code |
Qty | Number(10,3) | Optional | Quantity |
FreeQty | Number(10,3) | Optional | Free quantity |
Unit | String(2) | 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.BchDtls{...} | Object | Optional | This object contains details of batch |
Nm | String (20) | Mandatory | Batch Name/Number |
ExpDt | String(10) | Optional | Batch Expiry DateDD/MM/YYYY |
WrDt | String(10) | Optional | Batch Warranty DateDD/MM/YYYY |
Item.AttribDtls[] | Attribute[] | Optional | This object contains details of item attributes AttribDtls: Array[Attribute-1, Attribute-2,...] |
Attribute{...} | Object | Optional | This object contains details of line item |
Nm | String (100) | Mandatory | Attribute Name |
Val | String(100) | Mandatory | Attribute value |
ValDtls{...} | Object | Optional | This object contains details of document totals |
AssVal | String(6) | Optional | Serial no of line item. Only digits are allowed. |
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 |
PayDtls{...} | 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 |
RefDtls{...} | Object | Optional | This object contains reference details |
InvRm | String(100) | Optional | Document Remarks |
InvStDt | String(10) | Mandatory | Invoice Period Start DateDD/MM/YYYY |
InvEndDt | String(10) | Mandatory | Invoice Period End DateDD/MM/YYYY |
PrecDocDtls[] | PrecedindDoc[] | Optional | This object contains details of preceding issued documents Array[PrecedindDoc]:0..1 RefDtls.PrecDocDtls |
PrecedindDoc{...} | Object | Optional | This object contains preceding document details |
InvNo | String(16) | Mandatory | Preceding Invoice Number |
InvDt | String(10) | Mandatory | Preceding Invoice DateDD/MM/YYYY |
OthRefNo | String(20) | Optional | Other Reference |
ContrDtls[] | ContractRef[] | Optional | This object contains details of contract reference documents Array[ContractRef]:0..1 RefDtls.ContrDtls |
ContractRef{...} | Object | Optional | This object contains contract references |
RecAdvRefr | String(20) | Optional | Receipt Advice No |
RecAdvDt | String(10) | Optional | Receipt Advice DateDD/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 DateDD/MM/YYYY |
AddlDtls[] | AddlDoc[] | Optional | This object contains details of additional documents Array [AddlDoc]: 0..1 |
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 |
ExpDtls{...} | Object | Optional | This object contains details of export invoice |
ShipBNo | String(20) | Optional | Shipping Bill No |
ShipBDt | String(10) | Optional | Shipping Bill DateDD/MM/YYYY |
Port | String(10) | Optional | Port Code |
RefClm | String(1) | Optional | Refund ClaimY : YesN : 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 Mode1 : Road2 : Rail3 : Air4 : Ship |
Distance | Number(4) | Mandatory | Distance |
TransDocNo | String(15) | Optional | Transporter Doc No |
TransDocDt | String(10) | Optional | Transporter Doc DateDD/MM/YYYY |
VehNo | String(20) | Optional | Vehicle No |
VehType | String(1) | Optional | Vehicle TypeR : RegularO : 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.
# Success Response
Response payload will contain the success status along with IRN information.
{
"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"
}
Response object:
Parameter | Data Type | Description |
---|---|---|
Success | Boolean | true in case of success |
AckNo | String | Acknowledgement number |
AckTime | String | Acknowledgement Date & timeDD/MM/YYYY HH:MM:SS |
Irn | String | Invoice reference number generated |
IrnStatus | String | IRN StatusACT : ActiveCNL : 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 StatusACT : ActiveCNL : Cancelled |
EwbNo | String | e-waybill Number(present only if e-waybill is generated along with e-invoice) |
EwbTime | String | e-waybill generation Date & timeDD/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
object:
Parameter | Data Type | Description |
---|---|---|
Code | String | Error Code |
Message | String | Error message |
# Failure Response
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"
}
]
}
# API – Cancel e-Invoice
This API is used to cancel IRN.
# URL
POST https://bills.octagst.com/api/einvoice/cancelirn?gstin={value}`
# Query Parameters
Name | Description |
---|---|
gstin | It specifies GSTIN of seller |
# Request Payload
{
"Irn": "34e60bdd02a8bdee4be4a4bc8d510ae0b8cc248b02009e5b875aced4fda57c76",
"CnlRsn": "2",
"CnlRem": "Wrong HSN codes reported"
}
Parameter | Data Type | Type | Description |
---|---|---|---|
Irn | String(64) | Mandatory | Invoice reference number |
CnlRsn | String(1) | Mandatory | Cancel reason1 : Duplicate2 : Data entry mistake |
CnlRem | String(100) | Mandatory | Cancel remarks |
# Success Response
Response payload will contain the success status along with IRN information.
{
"Success": true,
"Irn":"a5c12dca80e743321740b001fd70953e8738d109865d28ba4013750f2046f229",
"CancelTime": "29/11/2020 09:34:11",
}
Parameter | Data Type | Description |
---|---|---|
Success | Boolean | true in case of success |
Irn | String | Invoice reference number which is cancelled |
CancelTime | String | IRN cancellation timeDD/MM/YYYY HH:MM:SS |
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Get IRN
This API is used to get details of e-Invoice for a given IRN.
# URL
GET https://bills.octagst.com/api/einvoice/getirn?gstin={value}&irn={value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
irn | It specifies Invoice reference number | Mandatory | |
qrcode | Specify yes to include QR Code image in response | Optional | yes , no (Default) |
qrcodeformat | Specify QR code image format | Optional | PNG (Default), JPEG , GIF |
qrcodequality | Specify QR code image quality | Optional | standard , high (Default) |
pdf | Specify yes to include e-invoive pdf and e-waybill pdf in response | Optional | yes , no (Default) |
# Success Response
Response payload will contain the success status along with IRN information.
{
"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"
}
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Get IRN by Doc
This API is used to get details of e-Invoice for given document.
# URL
GET https://bills.octagst.com/api/einvoice/getirnbydoc?gstin={value}&doctype={value}&docno{value}&docdate{value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
doctype | It specifies document type | Mandatory | INV : InvoiceCRN : Credit noteDBN : Debit note |
docno | It specifies document number | Mandatory | |
docdate | It specifies document date | Mandatory | DD/MM/YYYY |
qrcode | Specify yes to include QR Code image in response | Optional | yes , no (Default) |
qrcodeformat | Specify QR code image format | Optional | PNG (Default), JPEG , GIF |
qrcodequality | Specify QR code image quality | Optional | standard , high (Default) |
pdf | Specify yes to include e-invoive pdf and e-waybill pdf in response | Optional | yes , no (Default) |
# Success Response
Response payload will contain the success status along with IRN information.
{
"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"
}
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Generate e-Waybill by IRN
This API is used to generate e-waybill for a given IRN.
# URL
POST https://bills.octagst.com/api/einvoice/generateewbbyirn?gstin={value}&pdf={value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
pdf | It specifies whether to include eWayBill pdf in response or not | Optional | yes/no |
# Request Payload
{
"Irn": "eb68a55abbf1a31ae19a6c9d82a0b22ba37785b6b76949585e5f928fea4042cb",
"TransId": "24ACPPM5624F1ZK",
"TransName": "Golden Transport",
"TransMode": "1",
"Distance": 300,
"TransDocNo": "RS021",
"TransDocDt": "29/11/2020",
"VehNo": "RJ016789",
"VehType": "R",
"ExpShipDtls": {
"Addr1": "Sidiginamola Village",
"Addr2": "Ballari",
"Loc": "Ballari",
"Pin": 583138,
"Stcd": "29"
}
}
Parameter | Data Type | Type | Description |
---|---|---|---|
TransId | String(15) | Optional | Transporter Id |
TransName | String(100) | Optional | Transport Name |
TransMode | String(1) | Optional | Transport Mode1 : Road2 : Rail3 : Air4 : Ship |
Distance | Number(4) | Mandatory | Distance |
TransDocNo | String(15) | Optional | Transporter Doc No |
TransDocDt | String(10) | Optional | Transporter Doc DateDD/MM/YYYY |
VehNo | String(20) | Optional | Vehicle No |
VehType | String(1) | Optional | Vehicle TypeR : RegularO : Over-Dimensional Cargo (ODC) |
ExpShipDtls {...} | Object | Optional | This object contains the shiping details If the dispatching address and/or shipping address have not been passed during generation of IRN, then the respective addresses can be passed here. |
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 |
# Success Response
Response payload will contain the success status along with e-waybill information.
{
"Success": true,
"EwbStatus": "ACT",
"EwbNo": "191008688443",
"EwbTime": "27/11/2020 17:23:45",
"EwbValidTill": "29/11/2020 17:23:45",
"EwbPdf": "utwf19...34566AAAElFTkSuQmCC"
}
Parameter | Data Type | Description |
---|---|---|
Success | Boolean | true in case of success |
EwbStstus | String | EWB StatusACT : ActiveCNL : Cancelled` |
EwbNo | String | e-waybill Number(present only if e-waybill is generated along with e-invoice) |
EwbTime | String | e-waybill generation Date & timeDD/MM/YYYY HH:MM:SS |
EwbValidTill | String | e-waybill validity Date & time DD/MM/YYYY HH:MM:SS |
EwbPdf | String (Binary data in Base64 encoding) | e-waybill PDF file |
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Cancel e-Waybill
This API is used to cancel ewayBill.
# URL
POST https://bills.octagst.com/api/einvoice/cancelewb?gstin={value}
# Query Parameters
Name | Description |
---|---|
gstin | It specifies GSTIN of seller |
# Request Payload
{
"ewbNo": "791008693652",
"cancelRsnCode": "2",
"cancelRmrk": "Wrong HSN codes reported"
}
Parameter | Data Type | Type | Description |
---|---|---|---|
ewbNo | String(64) | Mandatory | e-Waybillnumber |
cancelRsnCode | String(1) | Mandatory | Cancel reason1 : Duplicate2 : Order Cancelled3 : Data entry mistake4 : Others |
cancelRmrk | String(50) | Mandatory | Cancel remarks |
# Success Response
Response payload will contain the success status.
{
"Success": true,
"CancelTime": "29/11/2020 09:34:11",
}
Parameter | Data Type | Description |
---|---|---|
Success | Boolean | true in case of success |
CancelTime | String | EWB cancellation timeDD/MM/YYYY HH:MM:SS |
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Get EWB By IRN
This API is used to get details of e-waybill for a given IRN.
# URL
GET https://bills.octagst.com/api/einvoice/getewbbyirn?gstin={value}&irn={value}&pdf={value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
irn | It specifies Invoice reference number | Mandatory | |
pdf | It specifies whether to include eWayBill pdf in response or not | Optional | yes/no |
# Success Response
Response payload will contains the success status along with e-Waybill information.
{
"Success": true,
"EwbStatus": "ACT",
"EwbNo": "191008688443",
"EwbTime": "27/11/2020 17:23:45",
"EwbValidTill": "29/11/2020 17:23:45",
"EwbPdf": "utwf19...34566AAAElFTkSuQmCC"
}
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Get GSTIN
This API is used to get details of GSTIN.
# URL
GET https://bills.octagst.com/api/einvoice/getgstin?gstin={value}&partygstin={value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
partygstin | It specifies GSTIN whose details to be fectched | Mandatory |
# Success Response
Response payload will contains the success status along with IRN information.
{
"Success": true,
"Gstin": "24ACPPM5624F1ZK",
"TradeName": "SHASTRI TROLLY WORKS",
"LegalName": "MANHARBHAI VISHNUBHAI MISTRI",
"AddrBnm": "TALUKDARI HOSTEL",
"AddrBno": "SHASTRI TROLLY WORKS",
"AddrFlno": "",
"AddrSt": "ASHRAM ROAD",
"AddrLoc": "NADIAD",
"StateCode": 24,
"AddrPncd": 387002,
"TxpType": "REG",
"Status": "ACT",
"BlkStatus": null
}
"Status" will have values as 'ACT' (Active) or 'CNL' (Cancelled) or 'INA' (Inactive) or 'PRO' (Provision).
The "blkStatus" indicates the status of blocking of generation of E Way Bill and will have following values i) 'U' or '' for Unblocked ii) 'B' for blocked - E Way Bill generation is not allowed for tax payers who have not filed the returns for last two months
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Get Doc IRN Info
This API is used to get IRN details of already generated e-invoice.
# URL
GET https://bills.octagst.com/api/einvoice/getdocirninfo?gstin={value}&doctype={value}&docno{value}&docdate{value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
doctype | It specifies document type | Mandatory | INV : InvoiceCRN : Credit noteDBN : Debit note |
docno | It specifies document number | Mandatory | |
docdate | It specifies document date | Mandatory | DD/MM/YYYY |
qrcode | Specify yes to include QR Code image in response | Optional | yes , no (Default) |
pdf | Specify yes to include e-invoive pdf and e-waybill pdf in response | Optional | yes , no (Default) |
# Success Response
Response payload will contain the success status along with IRN information.
{
"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",
"EinvoicePdf": "i7gahsd...GY899RfTkSueba781Fg",
"EwbPdf": "utwf19...34566AAAElFTkSuQmCC"
}
# Failure Response
If API request fails for some reason, 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"
}
]
}
# API – Generate Payment QR Code
This API is used to generate the dynamic QR code for B2C invoices to support online UPI payment.
# URL
POST https://bills.octagst.com/api/einvoice/generatepaymentqrcode
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
qrcode | Specify yes to include QR Code image in response | Optional | yes , no (Default) |
qrcodeformat | Specify QR code image format | Optional | PNG (Default), JPEG , GIF |
qrcodequality | Specify QR code image quality | Optional | standard , high (Default) |
pdf | Specify yes to include e-invoive pdf and e-waybill pdf in response | Optional | yes , no (Default) |
# Request Payload
Request payload should contain the JSON encoded invoice data. This payload is similar to the Generate IRN
API with the only differece of supply type which has to be set to B2C
.
{
//...
"TranDtls": {
"SupTyp": "B2C",
//...
},
//...
"BuyerDtls": {
"Gstin": null,
//...
},
//...
}
# Success Response
Response payload will contain the success status along with IRN information.
{
Success: true,
QRCodeImagePng: "iVBORw0KGgoAAAANSUhEUgAAAHIAAAB...IPwEIVCUYnlSs/gAAAABJRU5ErkJggg==",
PaymentQrCode: "upi://pay?pa=blowbits@ybl&pn=BLOWBITS%20SOLUTIONS%20LLP&tn=SELLER:08AASFB9647G1ZU%20NO:B2C1617260496%20DT:01-04-2021%20Taxable:%e2%82%b95000%20IGST:%e2%82%b9900&am=5900&cu=INR&mode=01"
}
Response object:
Parameter | Data Type | Description |
---|---|---|
Success | Boolean | true in case of success |
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 |
PaymentQrCode | String (Binary data in Base64 encoding) | Contents of dynamic QR code |
Errors | Error[] | List of errors, will be present only when Success is false |
Error
object:
Parameter | Data Type | Description |
---|---|---|
Code | String | Error Code |
Message | String | Error message |
# Failure Response
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"
}
]
}
# API – Error Codes
# Octa Bills Errors:
Error Code | Desription |
---|---|
OCTA-001 | Invalid seller GSTIN |
OCTA-002 | Invalid seller legal name |
OCTA-003 | Invalid seller trade name |
OCTA-004 | Invalid seller address-1 |
OCTA-005 | Invalid seller address-2 |
OCTA-006 | Invalid seller location |
OCTA-007 | Invalid seller pincode |
OCTA-008 | Invalid seller state code |
OCTA-009 | Invalid Seller phone no |
OCTA-010 | Invalid Seller email |
OCTA-011 | Invalid tax scheme |
OCTA-012 | Invalid supply type |
OCTA-013 | Invalid document type |
OCTA-014 | Invalid document no |
OCTA-015 | Invalid document date |
OCTA-016 | Invalid reverse charge |
OCTA-017 | Invalid place of supply |
OCTA-018 | Invalid IGST on intra state supply |
OCTA-019 | Invalid Ecommerce GSTIN |
OCTA-020 | Invalid remarks |
OCTA-021 | Invalid buyer GSTIN |
OCTA-022 | Invalid buyer legal name |
OCTA-023 | Invalid buyer trade name |
OCTA-024 | Invalid buyer address-1 |
OCTA-025 | Invalid buyer address-2 |
OCTA-026 | Invalid buyer location |
OCTA-027 | Invalid buyer pincode |
OCTA-028 | Invalid buyer state code |
OCTA-029 | Invalid buyer phone no |
OCTA-030 | Invalid buyer email |
OCTA-031 | Invalid dispatch entity name |
OCTA-032 | Invalid dispatch address-1 |
OCTA-033 | Invalid dispatch address-2 |
OCTA-034 | Invalid dispatch location |
OCTA-035 | Invalid dispatch pincode |
OCTA-036 | Invalid dispatch state code |
OCTA-037 | Invalid ShipTo GSTIN |
OCTA-038 | Invalid ShipTo legal name |
OCTA-039 | Invalid ShipTo trade name |
OCTA-040 | Invalid ShipTo address-1 |
OCTA-041 | Invalid ShipTo address-2 |
OCTA-042 | Invalid ShipTo location |
OCTA-043 | Invalid ShipTo pincode |
OCTA-044 | Invalid ShipTo state code |
OCTA-045 | Invalid shipping bill no |
OCTA-046 | Invalid shipping bill date |
OCTA-047 | Invalid port code |
OCTA-048 | Invalid country code |
OCTA-049 | Invalid currency code |
OCTA-050 | Invalid document value in foreign currency |
OCTA-051 | Invalid claim refund |
OCTA-052 | Invalid discount |
OCTA-053 | Invalid other charges |
OCTA-054 | Invalid round off amount |
OCTA-055 | Invalid document value |
OCTA-056 | Invalid item no |
OCTA-057 | Invalid item description |
OCTA-058 | Invalid HSN |
OCTA-059 | Invalid quantity |
OCTA-060 | Invalid free quantity |
OCTA-061 | Invalid unit price |
OCTA-062 | Invalid item gross value |
OCTA-063 | Invalid item discount |
OCTA-064 | Invalid pre tax value |
OCTA-065 | Invalid item taxable value |
OCTA-066 | Invalid GST rate |
OCTA-067 | Invalid item IGST |
OCTA-068 | Invalid item CGST |
OCTA-069 | Invalid item SGST |
OCTA-070 | Invalid cess rate |
OCTA-071 | Invalid cess amount |
OCTA-072 | Invalid Cess Non Advol |
OCTA-073 | Invalid state cess rate |
OCTA-074 | Invalid state cess amount |
OCTA-075 | Invalid state Cess Non Advol |
OCTA-076 | Invalid item other charges |
OCTA-077 | Invalid item total |
OCTA-078 | Invalid barcode |
OCTA-079 | Invalid product serial no |
OCTA-080 | Invalid order line reference |
OCTA-081 | Invalid origin country |
OCTA-082 | Invalid item attributes |
OCTA-083 | Invalid batch name/number |
OCTA-084 | Invalid batch expiry date |
OCTA-085 | Invalid batch warranty date |
OCTA-086 | Invalid transporter id |
OCTA-087 | Invalid transporter name |
OCTA-088 | Invalid distance |
OCTA-089 | Invalid transport mode |
OCTA-090 | Invalid transport document no |
OCTA-091 | Invalid transport document date |
OCTA-092 | Invalid vehicle number |
OCTA-093 | Invalid vehicle type |
OCTA-094 | Invalid payee name |
OCTA-095 | Invalid bank account no |
OCTA-096 | Invalid branch IFSC code |
OCTA-097 | Invalid payment mode |
OCTA-098 | Invalid payment terms |
OCTA-099 | Invalid payment instructions |
OCTA-100 | Invalid credit transfer terms |
OCTA-101 | Invalid direct debit terms |
OCTA-102 | Invalid credit days |
OCTA-103 | Invalid amount paid |
OCTA-104 | Invalid amount due |
OCTA-105 | Invalid document period start date |
OCTA-106 | Invalid document period end date |
OCTA-107 | Invalid preceding document no |
OCTA-108 | Invalid preceding document date |
OCTA-109 | Invalid preceding document other reference |
OCTA-110 | Invalid receipt advice no |
OCTA-111 | Invalid receipt advice date |
OCTA-112 | Invalid contract reference no |
OCTA-113 | Invalid tender batch/lot reference no |
OCTA-114 | Invalid other reference no |
OCTA-115 | Invalid project reference no |
OCTA-116 | Invalid PO reference no |
OCTA-117 | Invalid PO reference date |
OCTA-118 | Invalid supporting document URL |
OCTA-119 | Invalid supporting document contents |
OCTA-120 | Invalid supporting document additional information |
OCTA-121 | Invalid UQC (unit quantity code) |
OCTA-151 | Business GSTIN not found |
OCTA-152 | Invalid GSTIN |
OCTA-153 | Invalid IRN |
OCTA-154 | IRN already cancelled |
OCTA-155 | e-Waybill not allowed |
OCTA-156 | Active e-Waybill found |
OCTA-157 | Invalid e-Waybill no |
OCTA-158 | e-Waybill not found |
OCTA-159 | Invalid reason code |
OCTA-200 | API account not configured |
OCTA-201 | Network session failed |
OCTA-202 | Http session error |
OCTA-203 | Application error |
OCTA-204 | GSP error |
OCTA-205 | GSTN error |
OCTA-206 | GSTN IRP error |
OCTA-207 | GSTN e-Waybill error |
OCTA-208 | Network error |
OCTA-300 | Invalid request |
# NIC Errors:
Please visit NIC eInvoice developer site to know more about API errors. https://einv-apisandbox.nic.in/api-error-codes-list.html