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.octa.in/api/einvoice/generateirn?qrcode={value}&pdf={value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
qrcode | Specify yes to include QR Code PNG image in response | Optional | yes/no |
pdf | Specify yes to include e-invoive pdf and e-waybill pdf in response | Optional | yes/no |
# 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 Export |
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 | 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) | 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 |
BchDtls{...} 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 |
AttribDtls[] Item->AttribDtls | Object | 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[] | Object | 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[] | Object | 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[] | Object | 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",
"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 |
IrnStstus | 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 |
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.octa.in/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.octa.in/api/einvoice/getirn?gstin={value}&irn={value}&qrcode={value}&pdf={value}
# Query Parameters
Name | Description | Type | Value |
---|---|---|---|
gstin | It specifies GSTIN of seller GSTIN | Mandatory | |
irn | It specifies Invoice reference number | Mandatory | |
qrcode | It specifies whether to include QRCode PNG image in response or not | Optional | yes/no |
pdf | It specifies whether to include eInvoive pdf and eWayBill pdf in response or not | Optional | yes/no |
# 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 – Get IRN by Doc
This API is used to get details of e-Invoice for given document.
# URL
GET https://bills.octa.in/api/einvoice/getirnbydoc?gstin={value}&doctype={value}&docno{value}&docdate{value}&qrcode={value}&pdf={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 | It specifies whether to include QRCode PNG image in response or not | Optional | yes/no |
pdf | It specifies whether to include eInvoive pdf and eWayBill pdf in response or not | Optional | yes/no |
# 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 e-Waybill by IRN
This API is used to generate e-waybill for a given IRN.
# URL
POST https://bills.octa.in/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.octa.in/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.octa.in/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.octa.in/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 – 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-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