Basic E-Invoice APIs

APIs

E-invoice APIs

• Generate IRN
• Generate EWB by IRN
• Cancel IRN
• Get E-invoice
• Get Invoice Details by Document Details
• Get EWB Details by IRN
• Get GSTIN Details
• Sync GSTIN

E-Way Bill APIs ( Available only in sandbox. )

• Cancel EWB
• Get EWB By Date
• Get EWB for Transporter by Date

Headers

Header Key Name	Description
Content-Type	It used to indicate the media type of the resource in the request for example: application/json for json document exchange
accept	It used to request the media type of the resource expected in the response for example: application/json for json document exchange
X-FLYNN-N-IRP-GSP-CODE	GSP Identifier: enum (“vay”)
X-FLYNN-N-IRP-GSTIN	GSTIN of the taxpayer
X-FLYNN-N-IRP-USERNAME	Portal username associated with taxpayer GSTIN for the GSP, Non-sensitive
X-FLYNN-N-IRP-PWD	Portal password associated with GSTIN and Username for the GSP, Non-Sensitive

Optionally if you want to encrypt the password in header, refer Encryption Support

optional (non-mandatory) IRP password header

The header value for X-FLYNN-N-IRP-PWD / X-FLYNN-S-IRP-PWD is optional to send each time for all kind of requests (mandatory only for authentication API). Since IRP password will only be required when establishing a new session with NIC for the user, it’s not required with every API call. User could pass an empty string here. Authenticated User’s session with NIC is valid for 6 hours. When user makes an API call, and the session about to be invalidated, EAS will try to establish a new session with NIC by making the authentication call.
If the password has been given in the header, the authentication call will be made, and a new session will be established.
In absence of password, err-unable-to-authenticate-with-empty-password will be returned by EAS.

1. User could either make an authentication call to establish a session with NIC and continue making subsequent API calls.
2. In the next call, user could add the IRP password in the header. This would internally make the authentication API call and setup a new session with NIC.

Common Errors

There could be multiple types of errors when interacting with enriched e-invoice APIs. However, the structure of the error payload would remain same.

For example, on submitting duplicate document number and document date

Http Status Code: 502

{
  "error": {
    "message": "err-irp-returned-error",
    "args": {
      "details": [
        {
          "ErrorCode": "2150",
          "ErrorMessage": "Duplicate IRN"
        }
      ],
      "data": null
    }
  }
}

400 Bad Request

{
  "error": {
    "message": "err-invalid-request-body",
    "type": "ClientRequest",
    "args": {
      "errorLocation": "TranDtls -> SupTyp is invalid"
    }
  }
}

Common Errors for v3.0 API

There could be multiple types of errors when interacting with enriched e-invoice APIs. However, the structure of the error payload would remain same.

For example, on submitting duplicate document number and document date

Http Status Code: 502

{
    "status": "0",
    "data": null,
    "error": {
    "message": "err-irp-returned-error",
    "type": "Irp",
    "args": {
        "details": [
            {
            "ErrorCode": "2150",
            "ErrorMessage": "Duplicate IRN"
            }
        ]
    }
},
"info": [
    {
        "InfCd": "DUPIRN",
        "Desc": {
            "AckNo": 162310048475409,
            "AckDt": "2023-07-10 14:01:00",
            "Irn": "3acec8e1fd2e860a076ebc1c3b7c738466ccd1461d2ac7982916e6247ec38ce2"
        }
    }
],
"additionalInfo": {
    "details": {
        "AckNo": "162310048475409",
        "AckDt": "2023-07-10 14:01:00",
        "Irn": "3acec8e1fd2e860a076ebc1c3b7c738466ccd1461d2ac7982916e6247ec38ce2",
        "SignedInvoice": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE1MTNCODIxRUU0NkM3NDlBNjNCODZFMzE4QkY3MTEwOTkyODdEMUYiLCJ4NXQiOiJGUk80SWU1R3gwbW1PNGJqR0w5eEVKa29mUjgiLCJ0eXAiOiJKV1QifQ.eyJkYXRhIjoie1wiQWNrTm9cIjoxNjIzMTAwNDg0NzU0MDksXCJBY2tEdFwiOlwiMjAyMy0wNy0xMCAxNDowMDo0N1wiLFwiSXJuXCI6XCIzYWNlYzhlMWZkMmU4NjBhMDc2ZWJjMWMzYjdjNzM4NDY2Y2NkMTQ2MWQyYWM3OTgyOTE2ZTYyNDdlYzM4Y2UyXCIsXCJWZXJzaW9uXCI6XCIxLjFcIixcIlRyYW5EdGxzXCI6e1wiVGF4U2NoXCI6XCJHU1RcIixcIlN1cFR5cFwiOlwiQjJCXCIsXCJSZWdSZXZcIjpcIk5cIixcIklnc3RPbkludHJhXCI6XCJOXCJ9LFwiRG9jRHRsc1wiOntcIlR5cFwiOlwiSU5WXCIsXCJOb1wiOlwiUkFNSVJOSU5WMDY5XCIsXCJEdFwiOlwiMjEvMDYvMjAyMVwifSxcIlNlbGxlckR0bHNcIjp7XCJHc3RpblwiOlwiMjRBQUFQSTMxODJNMDAyXCIsXCJMZ2xObVwiOlwiSktMIFB2dC4gTHRkXCIsXCJUcmRObVwiOlwiSktMIFB2dC4gTHRkXCIsXCJBZGRyMVwiOlwiS2lsbGEgTm9cXHUwMDI3cyAyOS8xNi8yLDI1LjM3LzUsNiwxNSAsXCIsXCJBZGRyMlwiOlwiIERpc3RyaWN0IEd1cnVncmFtICxWaWxsYWdlIFRhaiBOYWdhciAsSGFyeWFuYVwiLFwiTG9jXCI6XCJCYW5nYWxvcmVcIixcIlBpblwiOjM5NTAwMyxcIlN0Y2RcIjpcIjI0XCIsXCJQaFwiOlwiOTAwMDIwNzAyOFwifSxcIkJ1eWVyRHRsc1wiOntcIkdzdGluXCI6XCIyOUFBQVBJMzE4Mk0wMDBcIixcIkxnbE5tXCI6XCJUZXN0IE9yZyBQdnQgTHRkLCBLaW5nc3dheSBCdWlsZGluZ1wiLFwiVHJkTm1cIjpcIlRlc3QgT3JnIFB2dCBMdGQsIEtpbmdzd2F5IEJ1aWxkaW5nXCIsXCJQb3NcIjpcIjI5XCIsXCJBZGRyMVwiOlwiU2hlZCBOby4xMCwgVmlzaW9uIFJlYWx0ZWNoIFByaXZhdGUgTGltaXRlZCwgS2hhc3JhIDc3LzEzIFxcdTAwMjYgNzcvMTFcIixcIkFkZHIyXCI6XCJTYW1wbGEga2hhcmtob2RhIHJvYWQsT3BwIFRDSSBIVUwgV2FyZWhvdXNlLCBUZWhzaWwgU0FNUExBLFZpbGxhZ2UtSGFzc2FuZ2FyaFwiLFwiTG9jXCI6XCJSb2h0YWtcIixcIlBpblwiOjU2MDAyNSxcIlBoXCI6XCI5MDAwMjA3MDI3XCIsXCJTdGNkXCI6XCIyOVwifSxcIkl0ZW1MaXN0XCI6W3tcIkl0ZW1Ob1wiOjAsXCJTbE5vXCI6XCIxXCIsXCJJc1NlcnZjXCI6XCJOXCIsXCJQcmREZXNjXCI6XCJQQVRBTkpBTEkgU0FVTkRBUllBIEFMT0VWRVJBIEdFTCAxNTBNTCBcIixcIkhzbkNkXCI6XCIzNDAxMzA5MFwiLFwiUXR5XCI6NDIwLFwiRnJlZVF0eVwiOjAsXCJVbml0XCI6XCJQQ1NcIixcIlVuaXRQcmljZVwiOjY1LjIxLFwiVG90QW10XCI6MjczODguMixcIkRpc2NvdW50XCI6MCxcIlByZVRheFZhbFwiOjEsXCJBc3NBbXRcIjoyNzM4OC4yLFwiR3N0UnRcIjoxOCxcIklnc3RBbXRcIjo0OTI5Ljg4LFwiQ2dzdEFtdFwiOjAsXCJTZ3N0QW10XCI6MCxcIkNlc1J0XCI6MCxcIkNlc0FtdFwiOjAsXCJDZXNOb25BZHZsQW10XCI6MCxcIlN0YXRlQ2VzUnRcIjowLFwiU3RhdGVDZXNBbXRcIjowLFwiU3RhdGVDZXNOb25BZHZsQW10XCI6MCxcIk90aENocmdcIjoyNC4yNCxcIlRvdEl0ZW1WYWxcIjozMjM0Mi4zMixcIkF0dHJpYkR0bHNcIjpbe1wiTm1cIjpcIlBBVEFOSkFMSSBTQVVOREFSWUEgQUxPRVZFUkEgR0VMIDE1ME1MIFwiLFwiVmFsXCI6XCIyNzM4OC4yMFwifV19XSxcIlZhbER0bHNcIjp7XCJBc3NWYWxcIjoyNzM4OC4yLFwiQ2dzdFZhbFwiOjAsXCJTZ3N0VmFsXCI6MCxcIklnc3RWYWxcIjo0OTI5Ljg4LFwiQ2VzVmFsXCI6MCxcIlN0Q2VzVmFsXCI6MCxcIkRpc2NvdW50XCI6MCxcIk90aENocmdcIjowLFwiUm5kT2ZmQW10XCI6MCxcIlRvdEludlZhbFwiOjMyMzQyLjMyfSxcIlJlZkR0bHNcIjp7XCJJbnZSbVwiOlwiSW52b2ljZSBSZW1hcmtzXCIsXCJEb2NQZXJkRHRsc1wiOntcIkludlN0RHRcIjpcIjIxLzA2LzIwMjFcIixcIkludkVuZER0XCI6XCIzMS8xMi8yMDIxXCJ9fSxcIkV3YkR0bHNcIjp7XCJUcmFuc05hbWVcIjpcIkFCQ0FTXCIsXCJEaXN0YW5jZVwiOjB9fSIsImlzcyI6Ik5JQyBTYW5kYm94In0.XU5mOngrmg8hs7PvMWdJH41cSv4E-Jrf5tFeS8oJeF9nfinTqdKHWxq-qf3uPhheUbBOCqmRyVF7ZECjtP4NIJl3PjcbLcxbiLjxqmF8_gx9kPDwAkIpJR4F2B4DIFefBb0pecd8K43Ejzss1S33gwrc6mwVkHk7O4_gxTBgC2xf4ImAqNeGK-g270KRTG5J6YMoGzICyrQJNP76gIDVbDpZ333FohBNy0-AJMqeyAsCHkn6DPr4frBBLMHhnPjQ2qiHGp3FaQjEM_HMDiM5Q2hWzzORVUd59KMwsZpz92OYvXLaVelpShblWt5jN4oAy87WVyxPQYpPO_w4skCXiw",
        "SignedQRCode": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjE1MTNCODIxRUU0NkM3NDlBNjNCODZFMzE4QkY3MTEwOTkyODdEMUYiLCJ4NXQiOiJGUk80SWU1R3gwbW1PNGJqR0w5eEVKa29mUjgiLCJ0eXAiOiJKV1QifQ.eyJkYXRhIjoie1wiU2VsbGVyR3N0aW5cIjpcIjI0QUFBUEkzMTgyTTAwMlwiLFwiQnV5ZXJHc3RpblwiOlwiMjlBQUFQSTMxODJNMDAwXCIsXCJEb2NOb1wiOlwiUkFNSVJOSU5WMDY5XCIsXCJEb2NUeXBcIjpcIklOVlwiLFwiRG9jRHRcIjpcIjIxLzA2LzIwMjFcIixcIlRvdEludlZhbFwiOjMyMzQyLjMyLFwiSXRlbUNudFwiOjEsXCJNYWluSHNuQ29kZVwiOlwiMzQwMTMwOTBcIixcIklyblwiOlwiM2FjZWM4ZTFmZDJlODYwYTA3NmViYzFjM2I3YzczODQ2NmNjZDE0NjFkMmFjNzk4MjkxNmU2MjQ3ZWMzOGNlMlwiLFwiSXJuRHRcIjpcIjIwMjMtMDctMTAgMTQ6MDA6NDdcIn0iLCJpc3MiOiJOSUMgU2FuZGJveCJ9.nPB1EinAtoKAK15tsV2rxuutNLZxA4bK0xc8Adm5xo9bWdZWGrm-5S32vvJDZDz19BHC08CM7NyQr7-L_D4iqaiK2kE9mFSgYJtG8XFm1e2dS3a1_yoajVrWZPLYDjJ9Kw0AGeV5f-wdTf-jrKI0CdAah8C2kCsJHhrzC6pkaCdPVqy7n2IoBEO7i2Sjxx3WJuyMWJiy19uYskDpYrseZGPOHP_zHtTCMEulZLB6cnArz1traREaG-rTfD6nOihSWF3ajQCf1UQ5_Kq-wnhg2gJUGgnSoNQnVU8QS4GGHqMXFYuXVaVej1lfd9z4gu_KRPqwDBrTvSjxxG6Yr2ND7w",
        "Status": "ACT",
        "EwbNo": null,
        "EwbDt": null,
        "EwbValidTill": null,
        "Remarks": null
    }
},
"alert": null
}

400 Bad Request

{
  "status": "0",
  "data": null,
  "error": {
    "message": "err-invalid-request-body",
    "type": "ClientRequest",
    "args": {
      "errorLocation": "TranDtls -> SupTyp is invalid"
    }
  },
  "info": null,
  "additionalInfo": null,
  "alert": null
}