Trigger Max ITC Workflow

Max ITC API

This API will trigger MaxITC workflow based on the inputs provided by the user in the request payload. It is a bi-functional API with the option to ingest PR data or skip ingestion if the user wants to trigger MaxITC for the existing purchase data in Clear.

Request Method

POST

Request URL

{{BASE_URL}}/integration/v1/maxItc/triggerWorkflow

Request Headers

Parameter	Data Type	Field Validations	Description
x-cleartax-auth-token	String	NA	Mandatory. User auth token.

Request Path Params

There are no path parameters for this API.

Request Query Params

There are no query parameters for this API.

Request Body

Parameter	Data Type	Field Validations	Description
fileList	Array	NA	Conditional. List of File Objects. Each File Object contains information about the file which is to be ingested before running the reconciliation.
userInputArgs	Object	NA	Mandatory. User input arguments for the running reconciliation.

File List

If no data needs to be ingested, provide fileListas an empty list. The API will run reconciliation against the data already available in Clear system.

Parameter	Data Type	Field Validations	Description
s3FileUrl	String	NA	Mandatory. Pre-Signed URL used to upload the file to storage.
userFileName	String	NA	Mandatory. Filename used when generating the Pre-signed URL.

User Input Arguments Object

Parameter	Data Type	Field Validations	Description
gstins	List<String>	NA	Optional. List of GSTINs for which reconciliation will be triggered. Default: Can be an empty list or NULL. We will take all GSTINs under the provided PAN in the pan field and will be considered for reconciliation and GSTR Pull.
pan	String	NA	Mandatory. PAN for which the reconciliation will be triggered.
pullReturnPeriodStart	String	Format: MMYYYY	Mandatory. Start Return Period for 2A Pull in MMYYYY format. Example : 042021 if the return period is April 2021.
pullReturnPeriodEnd	String	Format: MMYYYY	Mandatory. End Return Period for 2A Pull in MMYYYY format. Example : 042021 if the return period is April 2021.
reconReturnPeriodStart	String	Format: MMYYYY	Mandatory. Start Return Period for recon in MMYYYY format. Example : 042021 if the return period is April 2021.
reconReturnPeriodEnd	String	Format: MMYYYY	Mandatory. End Return Period for recon in MMYYYY format. Example : 042021 if the return period is April 2021
enableVoucherMerge	Boolean	NA	If enabled, vouchers pertaining to same document will get merged in the same document e.g. doc1 [v1, v2] If disabled, vouchers will get overridden in the document E.g. doc1 [v2]
templateId	String	NA	Mandatory. Template ID of the file uploaded. For a purchase document, the system template ID is "60e5613ff71f4a7aeca4336b".
reconType	Enum	Enum: MAX_ITC_2A_PR, MAX_ITC_2B_PR, MAX_ITC_6A_PR, MAX_ITC_8A_PR	Mandatory. Type of Reconciliation to trigger.
reconResultFilter	Object	NA	Optional. Pass filtering criteria to filter response.
returnType	String	NA	MAX_ITC_2A_PR, MAX_ITC_2B_PR, MAX_ITC_8A_PR, MAX_ITC_6A_PR

gstins can be an empty list or NULL. We will take all GSTINs under the provided PAN in pan field for reconciliation and GSTN Pull in such case.

Return Period will be accepted only in MMYYYY format.

ReconResultFilter Object

Parameter	Data Type	Field Validations	Description
matchStatus	Object	NA	Optional; Filter based on match status e.g. exact, missing_in_pr etc.
voucherNos	Object	NA	Optional; Filter based on voucher number
returnPeriod	Object	NA	Optional; Filter based on govt / pr return period
myGstin	Object	NA	Optional; Filter based on customer gstin
vendorCode	Object	NA	Optional; Filter based on voucher code
supplierPan	Object	NA	Optional; Filter based on supplier PAN

MatchStatus Object

Parameter	Data Type	Field Validations	Description
values	Array	Valid MatchStatus	Mandatory Values should be one or more of [exact, suggested, manual, mismatch, missing_in_pr, missing_in_govt, ignored_pr, ignored_govt, excluded_pr, excluded_govt]
negative	Boolean	NA	Optional : Negates the filtering criteria
source	String	Valid source string	Mandatory Should be “metadata”

VoucherNos Object

Parameter	Data Type	Field Validations	Description
values	Array	NA	Mandatory Should be an array of voucher numbers E.g. [“voucher1”, “voucher2”]
negative	Boolean	NA	Optional : Negates the filtering criteria
source	String	Valid source string	Mandatory Should be one of “pr” or “govt”

ReturnPeriod Object

Parameter	Data Type	Field Validations	Description
values	Array	Format: MMYYYY	Mandatory Return period of the document
negative	Boolean	NA	Optional : Negates the filtering criteria
source	String	Valid source string	Mandatory Should be one of “pr” or “govt”

MyGSTIN Object

Parameter	Data Type	Field Validations	Description
values	Array	Valid GSTIN number	Mandatory Should be an array of GSTIN numbers E.g. ["23AAAAAAAAAA123"]
negative	Boolean	NA	Optional : Negates the filtering criteria
source	String	Valid source string	Mandatory Should be one of “pr” or “govt”

VendorCode Object

Parameter	Data Type	Field Validations	Description
values	Array	NA	Mandatory Should be array of vendor codes E.g. ["V1"]
negative	Boolean	NA	Optional : Negates the filtering criteria
source	String	Valid source string	Mandatory Should be one of “pr” or “govt”

SupplierPan Object

values	Array	Valid GSTIN number	Mandatory Should be an array of supplier PAN numbers E.g. - [“CXXPS1795P”]
negative	Boolean	NA	Optional : Negates the filtering criteria
source	String	Valid source string	Mandatory Should be one of “pr” or “govt”

Example

1. Not in “Missing in PR”

reconResultFilter:{
    "matchStatus": {
        "values": ["missing_in_pr"], 
        "negative": true,
        "source": "metadata",
    }
}

1. Not in “Missing in PR” & “Not in supplier pan = [“abcd…”]” (“abcd..” is PAN for which recon is triggered)

reconResultFilter:{
    "matchStatus": {
        "values": ["missing_in_pr"], 
        "negative": true,
        "source": "metadata",
    },
"supplierPan": {
        "values": ["<Insert PAN for which recon is being triggered>"],
 "negative": true,
        "source": "pr"
    }
}

Sample Request

Request Body:

{
  "fileList": [
        {
            "userFileName": "test123.xls",
            "s3FileUrl": "https://ingestionv2-prod.s3.ap-south-1.amazonaws.com/4fee63cb-6f7c-455c-9c13-6f3cdb7a0e08/MaxItc/2021/NOVEMBER/e3704ce6d0074d9e8378c716224bc48f/OriginalFileName/e3704ce6d0074d9e8378c716224bc48f__1637316021949.xls"
        }
  ],
 "userInputArgs": {
        "gstins": [],
        "pan": "AAFCD5862R",
        "templateId": "60e5613ff71f4a7aeca4336b",
        "reconType": "MAX_ITC_2A_PR",
        "pullReturnPeriodStart": "042021",
        "reconReturnPeriodStart": "042021",
        "pullReturnPeriodEnd": "052022",
        "reconReturnPeriodEnd": "052022"
    }

}

Response Status Codes

HTTP Status Code	Description
201	Triggered ingestion successfully.
400	Bad request.
401	Unauthorized
500	Internal Server Error

Response Schema

Parameter	Data Type	Field Validations	Description
workflowId	String	NA	Workflow Id to track the status of the triggered workflow.
status	String	Enum: WORKFLOW_IN_PROGRESS, WORKFLOW_FAILED	Status of the workflow.
errors	List<JSON>	NA	Array of Error Objects. If there are no errors, then this field will be an empty list.
userInputArgs	Object	NA	User Input for the request.

Error Object

Parameter	Data Type	Field Validations	Description
errorCode	String	Enum: AUTHORIZATION_FAILED, WORKFLOW_ALREADY_IN_PROGRESS,LICENSE_EXPIRED, QUOTA_EXCEEDED, PERMISSION_DENIED, INTERNAL_ERROR, INVALID_TEMPLATE, GSTIN_TOKEN_INACTIVE, INVALID_REQUEST_PARAMETER	API Error Code
errorMessage	String	NA	Name of the field if it is a validation error.
errorValues	Array	NA	List of error values.
errorResolution	String	NA	Possible resolution.

User Input Arguments Object

templateId	String	NA	Template Id
pan	String	NA	PAN for which the reconciliation is triggered.
gstins	String	NA	List of GSTINs for which reconciliation is triggered. considered.
reconType	String	NA	Type of Reconciliation trigger.
pullReturnPeriodStart	String	Format: MMYYYY	Start Return Period for 2A Pull
pullReturnPeriodEnd	String	Format: MMYYYY	End Return Period for 2A Pull
reconReturnPeriodStart	String	Format: MMYYYY	Start Return Period for recon
reconReturnPeriodEnd	String	Format: MMYYYY	End Return Period for recon
returnType	String	NA	Type of return

Sample Response (Success)

HTTP Status Code - 201 Created

{
    "workflowId": "68ed4fd2-06c2-4f1c-a80f-31514d203d5d",
    "status": "WORKFLOW_IN_PROGRESS",
    "errors": [],
    "userInputArgs": {
        "templateId": "60e5613ff71f4a7aeca4336b",
        "sheetName": null,
        "groupId": null,
        "metadata": null,
        "pan": "AAFCD5862R",
        "gstins": [],
        "reconType": "MAX_ITC_2A_PR",
        "pullReturnPeriodStart": "062023",
        "pullReturnPeriodEnd": "072023",
        "reconReturnPeriodStart": "062023",
        "reconReturnPeriodEnd": "072023",
        "enableVoucherMerge": false,
        "convertErpChannelValidationAsWarning": false,
        "reconResultFilter": null,
        "returnType": "GSTR2A"
    }
}

Sample Response (Error)

HTTP Status Code - 401 Unauthorized

{
    "workflowId": null,
    "status": null,
    "errors": [
        {
            "errorCode": "AUTHORIZATION_FAILED",
            "errorMessage": "Invalid Auth Token",
            "errorField": null,
            "errorValues": null,
            "errorResolution": null
        }
    ],
    "userInputArgs": null
}

API Validations

Currently there are no known validations.

API Constraints

We place the following four constraints as a ‘fair usage policy’ on our APIs:

1. ERP Trigger workflow cannot be triggered more than 24 times per day/PAN in Production and 48 times per day/PAN in SaaS sandbox environments from a single workspace

2. Customer is expected to use ingestion API for transferring historic data instead of triggering recon

3. Customer is expected to use ingestion API for transferring historic data instead of triggering recon