Create request

Introduction

This API is the first step in using the GST Prism product.

This API is responsible for generating a single OTP for the client which would later be used for establishing a session for fetching GSTR data and creating analytics reports. OTP will be sent to the registered number on the GST portal. This API can also be used to submit the username and password if the end customer has opted for that authentication mechanism. The GST Prism API supports fetching up to 3 years of data. For longer durations, contact your sales representative for a customization. You will require an authorization token to use this API. This authorization token will be generated by Signzy for you and will be used in each API call. Please contact [email protected] or your sales representative for this.

cURL

curl --location --globoff 'https://api.signzy.app/api/v3/gstr-analytics/create-request' \
--header 'Authorization: <Access-Token>' \
--header 'Content-Type: application/json' \
--data '{
    "gstin": "29ABCDE1234F1Z5",
    "username": "signzy8e_1",
    "fromDate": "062022",
    "toDate": "082022",
    "pdfUrl": true,
    "entityDetails": true,
    "authType": "password",
    "password": "signzyGSTA8e_1",
    "callbackUrl": "https://client-specific.callback.url",
    "relatedPartyTransactions": ["29ABCDE1234F5","Signzy"]
}'

Endpoints

https://api-preproduction.signzy.app/api/v3/gstr-analytics/create-request

Request Headers

Key	Value
Authorization	shared by Signzy
Content-type	application/json

Request Body

{
    "gstin": "12ABCDE3456X7YZ",
    "username": "abcde3456x_7",
    "fromDate": "022020",
    "toDate": "012023",
    "entityDetails": true,
    "pdfUrl": false,
    "callbackUrl": "https://client-specific.callback.url",
    "authType" : "OTP",
    "password" : "testt"
}

Input Mapping

PARAMETERS	DESCRIPTION	TYPE	VALUE (COMPULSORY OR OPTIONAL)
gstin	GSTIN of the business/customer for which the analytics report/raw data is to be generated/fetched	String	COMPULSORY
username	Username of the entity on GST portal for which the authorization is being done	String	COMPULSORY
fromDate	Starting date (MMYYYY format) from which the analytics report is to be generated	String	COMPULSORY
toDate	Ending date (MMYYYY format) till which the analytics report is to be generated	String	COMPULSORY
entityDetails	Shall the report consist of entity details of the provided GSTIN?	Boolean	OPTIONAL
pdfUrl	Shall the report be generated in PDF format as well?	Boolean	OPTIONAL
callbackUrl	The URL which will be used to publish raw GST data	String	OPTIONAL
authType	The type of authentication being used to take consent. Default is OTP if not passed	string, only accepts - "OTP"/ "PASSWORD"	OPTIONAL in case of OTP. Compulsory if going with Password authentication
password	Password for the GST portal corresponding to the GSTIN and username provided	String	OPTIONAL, in case of authorization type of password, it is mandatory
relatedPartyTransactions	The GSTINS and entity Names for which we want to get the Transaction data.	Array of String	OPTIONAL

Response Data

{
    "result": {
        "requestId": "d54becdf-05d9-49b9-9af8-7c93ae2772a4",
        "message": "GST OTP generation successful."
    }
}

PARAMETERS	DESCRIPTION	TYPE	VALUE (COMPULSORY OR OPTIONAL)
result	This parameter contains the actual output.	Object	COMPULSORY
requestId	This is a unique 36-character long alphanumeric string created during the successful generation of OTP/submission of password and to be used for subsequent GSTR APIs	String	COMPULSORY
message	It indicates whether the OTP generation step was successful or not.	String	COMPULSORY

Sample Status Codes And Messages

{
    "result": {
        "requestId": "605e824c-7008-40c6-b420-ed25d0a8991d",
        "message": "GST OTP generation successful."
    }
}

1. GST OTP generation successful.
2. OTP is already triggered for this gstin. Use the requestId and proceed with the submit otp API.
3. API Access/GSTIN Username Error.

Dummy GSTINs: For integration and testing purposes. The following GSTIN is for integration purposes, so that real GSTIN/OTPs are not required for integrating the GST Prism APIs. There are 2 GSTINs to test success scenarios, where you will receive a dummy report in response and two GSTINs to test failure scenarios.

Success Scenario GSTIN -

GSTIN	Username	Password	OTP	Description
29ABCDE1234F1Z5	signzy8e_1	signzyGSTA8e_1	777777	This GSTIn can be used to generate a successful dummy report
27ABCDE1234F1Z9	signzyBe_2	signzyGSTBe_2	777777	This GSTIn can be used to generate a successful dummy report

Failure Scenario GSTIN -

GSTIN	Username	Password	OTP	Description
33ABCDE1234F1Q3	signzy8e_3	signzyGSTA8e_3	777777	This GSTIn will give failure error scenarios while generating OTP
35ABCDE1234F1Q1	signzy8e_4	signzyGSTA8e_4	777777	This GSTIN will let you submit the OTP successfully, but the report will not be generated, and a failure callback response will be received.

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected].