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-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

← e-Invoice API Configuration Domain Migration – Octa GST →