Subscribe for Updates

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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.

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField 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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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": "AAACO2563P",
    "pullReturnPeriodStart": "062023",
    "pullReturnPeriodEnd": "072023",
    "reconReturnPeriodStart": "062023",
    "reconReturnPeriodEnd": "072023",
    "reconType": "PAN_2A_PR_MAX_ITC",
    "templateId": "60e5613ff71f4a7aeca4336b"
  }
}

Response Status Codes

HTTP Status CodeDescription

201

Triggered ingestion successfully.

400

Bad request.

401

Unauthorized

500

Internal Server Error

Response Schema

ParameterData TypeField ValidationsDescription

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

ParameterData TypeField ValidationsDescription

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

Previous(Deprecated) Ingest PR via JSONNextGet Max ITC Results

Last updated