Download GST Returns Bulk#
This API allows clients to download GST returns efficiently with giving to and from return-periods along with individual session data of supported returns. You can request only few sub-documents to make call more efficient. Currently, we support GSTR-1, 2A, 2B and 3B for the downloads. Make sure you have GST session established before making the call. We will internally manage large 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 Results 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}/download-gst-returns
- active ‘flynn-version’: v3.0
- method: POST
URL Parameters#
| Name | Description | Type |
|---|---|---|
| flynn-version | version of the API for example, v3.0 |
string |
Headers#
All headers are mentioned in common GSTN headers.
Tip
The only valid value for the header key accept is application/json.
Also, since no request body is sent, header key Content-type is optional.
Request#
Body consists of the following payload and has GSTIN and username of the authenticating user
Sample Request Body
[
{
"fromRetPeriod":"012019",
"toRetPeriod":"012019",
"returns":{
"gstr1":{
"b2b":true,
"b2ba":true,
"b2cl":true,
"b2cla":true,
"b2cs":true,
"b2csa":true,
"cdnr":true,
"cdnra":true,
"cdnur":true,
"cdnura":true,
"exp":true,
"expa":true,
"at":true,
"ata":true,
"txp":true,
"txpa":true,
"e_invoices_b2b":true,
"e_invoices_cdnr":true,
"e_invoices_cdnur":true,
"e_invoices_exp":true,
"nil_rated":true,
"hsn_summary":true,
"doc_issued":true,
"summary":true
},
"gstr2a":{
"b2b":true,
"b2ba":true,
"cdn":true,
"cdna":true,
"isd":true,
"impg":true,
"impgsez":true,
"amdhist":true,
"tds":true,
"tcs":true
},
"gstr2b":{
"alldetails":true
},
"gstr3b":{
"details":true
},
"cmp":{
"details":true
}
},
"parameters":{
"gstr1":{
"b2b":{
"optionalParameters":{
"actionRequired":"true",
"counterPartyGstin":"33GSPTN0791G1Z5",
"from":"01-01-2017"
}
},
"b2ba":{
"optionalParameters":{
"actionRequired":"true",
"counterPartyGstin":"33GSPTN0791G1Z5"
}
},
"b2cl":{
"optionalParameters":{
"stateCode":"23"
}
},
"b2cla":{
"optionalParameters":{
"stateCode":"23"
}
},
"cdnr":{
"optionalParameters":{
"actionRequired":"true",
"from":"01-01-2017"
}
},
"cdnra":{
"optionalParameters":{
"actionRequired": "true"
}
},
"e_invoices_b2b":{
"optionalParameters":{
"from":"01-01-2017"
}
},
"e_invoices_cdnr":{
"optionalParameters":{
"from":"01-01-2017"
}
},
"e_invoices_cdnur":{
"optionalParameters":{
"from":"01-01-2017"
}
},
"e_invoices_exp":{
"optionalParameters":{
"from":"01-01-2017"
}
}
},
"gstr2a":{
"b2b":{
"optionalParameters":{
"counterPartyGstin":"33GSPTN0791G1Z5",
"from":"01-01-2017"
}
},
"b2ba":{
"optionalParameters":{
"counterPartyGstin":"33GSPTN0791G1Z5"
}
},
"cdn":{
"optionalParameters":{
"counterPartyGstin":"33GSPTN0791G1Z5",
"from":"01-01-2017"
}
},
"cdna":{
"optionalParameters":{
"counterPartyGstin":"33GSPTN0791G1Z5"
}
},
"isd":{
"optionalParameters":{
"counterPartyGstin":"33GSPTN0791G1Z5"
}
},
"impg":{
"optionalParameters":{
"from":"01-01-2017"
}
},
"impgsez":{
"optionalParameters":{
"from":"01-01-2017"
}
},
"amdhist":{
"mandatoryParameters":{
"portCode":"INBLR4",
"billOfEntryNumber":"8108363",
"dateOfBill":"01-04-2020"
}
}
}
}
},
{
"fromRetPeriod": "082020",
"toRetPeriod": "082020",
"returns": {
"gstr1": {
"b2b": true
}
},
"parameters": {
"gstr1": {
"b2b":{
"optionalParameters":{
"actionRequired":"true",
"counterPartyGstin":"33GSPTN0791G1Z5",
"from":"01-01-2017"
}
}
}
}
},
{
"fromRetPeriod":"102018",
"toRetPeriod":"112019",
"returns": {
"gstr2a": {
"amdhist": true
}
},
"parameters":{
"gstr2a":{
"amdhist":{
"mandatoryParameters":{
"portCode":"INBLR4",
"billOfEntryNumber":"8108363",
"dateOfBill":"01-04-2020"
}
}
}
}
}
]
Note#
-
For each document section, set to false if user don’t need data.
-
If user wants to download gstr-2a
AMDHISTdata, then user needs to passmandatoryParametersin the request body as below -
Sample Request Body of AMDHIST (Mandatory Parameters)
{
"fromRetPeriod":"102018",
"toRetPeriod":"112019",
"returns": {
"gstr2a": {
"amdhist": true
}
},
"parameters":{
"gstr2a":{
"amdhist":{
"mandatoryParameters":{
"portCode":"INBLR4",
"billOfEntryNumber":"8108363",
"dateOfBill":"01-04-2020"
}
}
}
}
}
optionalParametersis a non mandatory parameter in payload, can be set to null.
Sample Request Body of B2B (Optional Parameters)
{
"fromRetPeriod": "082020",
"toRetPeriod": "082020",
"returns": {
"gstr1": {
"b2b": true
}
},
"parameters": {
"gstr1": {
"b2b":{
"optionalParameters":{
"actionRequired":"true",
"counterPartyGstin":"33GSPTN0791G1Z5",
"from":"01-01-2017"
}
}
}
}
}
cmpReturn Type available only in GSTR Flynn-version v3.0
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#
Result API response is unique for each API.
Successful Response
{
"status": "1",
"data": [
{
"status": "1",
"data": {
"b2b": [
{
"inv": [
{
"itms": [
{
"num": 1,
"itm_det": {
"samt": 0,
"csamt": 0,
"rt": 12,
"txval": 1000,
"camt": 0,
"iamt": 120
}
},
{
"num": 2,
"itm_det": {
"samt": 0,
"csamt": 0,
"rt": 5,
"txval": 1000,
"camt": 0,
"iamt": 50
}
}
],
"val": 2000,
"inv_typ": "R",
"flag": "U",
"pos": "33",
"updby": "S",
"idt": "01-11-2021",
"rchrg": "N",
"inum": "inv-00000020170",
"cflag": "N",
"chksum": "840ab0dfe4b858953f74c558672a026680a1d290c8ba0cda1ee2a969af152483"
}
],
"cfs": "N",
"ctin": "27AOZPD0347J2ZK"
}
]
},
"error": null,
"info": null,
"additionalInfo": {
"key": {
"action": "B2B",
"section": "",
"module": "taxpayerapi",
"version": "v3.0",
"returnType": "gstr1",
"apiType": "gstr1-get-b2b",
"retPeriod": "112021"
}
},
"alert": null
}
],
"error": null,
"info": null,
"additionalInfo": null,
"alert": null
}
Where, data node contains the data received via GSTN for the mentioned sub-document (attribute in the above payload is action) of the Return Type for a return period.
For more details on the schema (of the attribute data) please check with GSTN Developer Documentation.
Flow for integration#
- To establish GST session, first Request OTP
- Once you get the session request ID, use authentication API to Verify OTP with GSTN
- Now if you have successfully established a session, request to download GST returns based on your requirements
- You will get async
task-idto track the status of the GST Returns Download Bulk request. Use the task id to track the status - Once async task status states
completedyou can proceed to download the result - which will be give you the page count - 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.