Download IMS Invoices

This API allows clients to download IMS EInvoice efficiently with given data along with individual session data of supported returns. Make sure you have GST session established before making the call. We will internally manage file downloads and refresh of the session during the fetch of returns. That’s the reason this is a long-running task (or an asynchronous call). The response of the request is a reference ID.

Given a reference ID, you could fetch its status using Status API. Once the status is complete. Use Result api for getting the page count. In order to download the pages, you would need to use Pages API where you will find the actual result.

Route

/enriched/gstn/{flynn-version}/ims-invoices?section={section}&status={status}

• active ‘flynn-version’: v1.0
• method: GET

URL Parameters

Name	Description	Type
flynn-version	version of the API for example, v1.0	string

Query Parameters

Name	Description	Type	Mandatory
section	Section Type for example, B2B	string	Yes
status	Invoice status for example, A	string	No

Headers

All headers are mentioned in common GSTN headers.

Response

Status Code: 200

Successful response will an async task-id. Using this task-id you will be able to fetch the status of the request.

Sample Response Body

  {
    "status": "1",
    "data": {
      "task-id": "2a51e392-529c-4b5a-bfd8-ca14d510a68d"
    },
    "error": null,
    "info": null,
    "additionalInfo": null,
    "alert": null
  } 

Since, this is a long-running task. Result of the task is downloaded once the process is completed. To check the process status of the task, call status api. To get the result of the task, call result api.

Result API Response

Result API response is unique for each API.

Successful Response

 {
   "status": "1",
   "data": {
        "pages": 1
    },
   "error": null,
   "info": null,
   "additionalInfo": null,
   "alert": null
}     

Once you get the page count. You can download actual pages using page result api.

Page Result API Response

Successful Response

{
      "status": "1",
      "data": {
        "b2b": [
          {
            "stin": "24MAYAS0100J1JD",
            "inum": "b1",
            "inv_typ": "R",
            "action": "A",
            "ispendactnallwd": "N",
            "srcform": "R1",
            "rtnprd": "012023",
            "srcfilstatus": "Not Filed",
            "idt": "23-01-2023",
            "val": 1000,
            "pos": "24",
            "txval": 100,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "b2ba": [
          {
            "oinum": "ab2",
            "oidt": "24-02-2023",
            "stin": "24MAYAS0100J1JD",
            "rtnprd": "012023",
            "inum": "b1a",
            "action": "A",
            "ispendactnallwd": "N",
            "inv_typ": "R",
            "srcform": "R1",
            "idt": "23-01-2023",
            "val": 1000,
            "pos": "07",
            "txval": 100,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Not Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "b2bdn": [
          {
            "stin": "24MAYAS0100J1JD",
            "nt_num": "dn2",
            "action": "A",
            "inv_typ": "R",
            "srcform": "R1",
            "ispendactnallwd": "N",
            "rtnprd": "012023",
            "nt_dt": "24-02-2023",
            "val": 1000.1,
            "pos": "07",
            "txval": 1000.1,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "b2bdna": [
          {
            "stin": "24MAYAS0100J1JD",
            "ont_num": "ca2",
            "ont_dt": "24-02-2023",
            "nt_num": "dn2",
            "action": "A",
            "inv_typ": "R",
            "srcform": "R1",
            "ispendactnallwd": "N",
            "rtnprd": "012023",
            "nt_dt": "24-02-2023",
            "val": 1000.1,
            "pos": "07",
            "txval": 1000.1,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "b2bcn": [
          {
            "stin": "24MAYAS0100J1JD",
            "nt_num": "dn2",
            "action": "A",
            "inv_typ": "R",
            "srcform": "R1",
            "rtnprd": "012023",
            "ispendactnallwd": "N",
            "nt_dt": "24-02-2023",
            "val": 1000.1,
            "pos": "07",
            "txval": 1000.1,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Not Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "b2bcna": [
          {
            "stin": "24MAYAS0100J1JD",
            "ont_num": "ca2",
            "ont_dt": "24-02-2023",
            "nt_num": "dn2",
            "action": "A",
            "inv_typ": "R",
            "srcform": "R1",
            "ispendactnallwd": "N",
            "rtnprd": "012023",
            "nt_dt": "24-02-2023",
            "val": 1000.1,
            "pos": "07",
            "txval": 1000.1,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Not Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "ecom": [
          {
            "stin": "24MAYAS0100J1JD",
            "rtnprd": "012023",
            "inum": "sd3",
            "action": "A",
            "srcform": "R1",
            "ispendactnallwd": "N",
            "idt": "24-02-2023",
            "val": 1000,
            "pos": "07",
            "txval": 1000,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Not Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ],
        "ecoma": [
          {
            "stin": "24MAYAS0100J1JD",
            "oinum": "get5",
            "oidt": "24-02-2023",
            "rtnprd": "012023",
            "inum": "sd3",
            "action": "A",
            "srcform": "R1",
            "ispendactnallwd": "N",
            "idt": "24-02-2023",
            "val": 1000,
            "pos": "07",
            "txval": 1000,
            "iamt": 20,
            "camt": 20,
            "samt": 20,
            "cess": 0,
            "srcfilstatus": "Not Filed",
            "hash": "1f5fb5de9e491c24dcdee9ac01d3fa5f7889f20d3a8c923bfd2e3c7f0d0125f1"
          }
        ]
      },
      "error": null,
      "info": null,
      "additionalInfo": null,
      "alert": null
    }

Flow for integration

1. To establish GST session, first Request OTP
2. Once you get the session request ID, use authentication API to Verify OTP with GSTN
3. Now if you have successfully established a session, request to download ims invoice based on section and status Query Parameters
4. You will get async task-id to track the status of the Download ims invoice API. Use the task id to track the status
5. Once async task status states completed you can proceed to download the result - which will be give you the page count
6. Finally, to download all the pages you need to use paged result api which will yield the final result

Note: We will take care of refreshing the GST session based on Taxpayer’s preferences set on the GSTN portal (ideally, keep it to 30 days).

You can call refresh session API explicitly if you wish to extend the session and use logout api to logout of the GSTN session. If client logs out when task processing is not yet complete it will yield into failure of the download jobs and client won’t get the desired results.