Skip to content

Download GST EInvoice#

This API allows clients to download GST 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 Download API for getting the result.

Route

/enriched/gstn/{flynn-version}/einvoice/download

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

URL Parameters#

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

Headers#

All headers are mentioned in common GSTN headers.

Request#

Body consists of the following payload and has GSTIN and username of the authenticating user

Sample Request Body

{
    "retPeriod": "082023",
    "supplyType": "B2B",
    "gstin": "29HJKPS9689A8Z4",
    "supplierGstin": "29HJKPS9689A8Z4",
    "recipientGstin": null
}

Note: One of supplierGstin or recipientGstin is mandatory

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 download api.

Download API Response#

Download API response will return a ZIP.

result.json content on Successful Response

    {
    "status": "1",
    "data": [
            {
        "status": "1",
        "data": "file-1.json",
        "error": null,
        "info": null,
        "additionalInfo": null,
        "alert": null
        }
    ],
    "error": null,
    "info": null,
    "additionalInfo": null,
    "alert": null
    }

Where, data node contains the data received via GSTN for the mentioned supply type for a return period. For more details on the schema (of the attribute data) please check with GSTN Developer Documentation.

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 GST returns based on your requirements
  4. You will get async task-id to track the status of the GST Returns Download Bulk request. Use the task id to track the status
  5. Once async task status states completed you can proceed to download the Download

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.