Octa

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 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(15) Mandatory Document No
Alphanumeric, /, -
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[] 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 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(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 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
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 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
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 Date
DD/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 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
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 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

# 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 & 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 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 reason
1: Duplicate
2: 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 time
DD/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: Invoice
CRN: Credit note
DBN: 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 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)
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 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
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 reason
1: Duplicate
2: Order Cancelled
3: Data entry mistake
4: 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 time
DD/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: Invoice
CRN: Credit note
DBN: 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

← Domain Migration – Octa GST →