Introduction to Max ITC API
The objective of this document is to describe the preliminary notes on the integration approach for ClearTax Max ITC product.

Integration Approach

High level diagram showing systems involved in Max ITC Integration.
Diagram showing role-based scope of actions in Max ITC cycle.
A typical Max ITC integration involves the following steps:
    1.
    Uploading purchase register from ERP to ClearTax.
    2.
    Triggering reconciliation task on ClearTax.
    3.
    Getting reconciliation results from ClearTax to ERP.
    4.
    Blocking payments on ERP based on the reconciliation results received.

Uploading purchase register (PR)

The preliminary source of the purchase register is your ERP. Needless to say, to reconcile this dataset with the 2A/2B dataset, it is necessary to synchronize the purchase register from your ERP to ClearTax.
When to upload?
How often the purchase register is synchronized with ClearTax depends on the payment cycle of the business. Some companies follow a monthly cycle, some have fortnightly, some weekly, and some daily.
How to upload?
The number of documents to be synced can vary from a few hundred to millions for a given cycle. Depending on the volume of the documents, ClearTax recommends different ways to upload the documents.
    1.
    Upload PR as JSON payload
    2.
    Upload PR as an Excel/CSV file
Upload PR as JSON payload
If the volume of documents is on the lower end, say a maximum of up to 1000 invoice line items, then we recommend you to send the documents as a JSON payload in a POST HTTP request. ClearTax will receive the documents and process them asynchronously. This API will provide an acknowledgement with a 201 HTTP status code that includes a request ID and the request status.
Upload PR as an Excel/CSV file
If the volume of documents is on the mid or higher end, say above 5000 invoices, then we recommend you to send the documents as an Excel or CSV file in a multipart/form-data POST HTTP request. ClearTax will receive the file and process the documents asynchronously. This API will provide an acknowledgement with a 201 HTTP status code that includes a request ID, request status and the AWS S3 URL.
Who will upload?
The implementation of the PR ingestion can be either clock-driven or event-driven depending on the end-user requirement. In case the accounts payable payment cycle is well defined and periodic, we can implement the PR ingestion to run based on a clock-driven schedule. For example, every Thursday, or every 15th and 30th of the month, etc. On the other hand, if the payment schedule is sporadic or aperiodic, then the PR ingestion can be implemented to run based on certain user events. For example, with the click of a button or in the event of running a report.
What happens in case of errors and exceptions?
At times, it is possible that a few documents uploaded have errors or invalid data. In such cases, ClearTax throws an exception with the error message back in response. This can then be parsed and updated back in the ERP for the use of the end-user against such documents. The end-user can review the error and fix the document and upload them again.
While the entire errors and exception handling is a good practice to ensure data accuracy and integrity, sometimes, it can be exasperating. In such a case, ClearTax gives an option to suppress certain validations and can be configured in the PR ingestion API request.

Downloading 2A/2B data

Triggering reconciliation

Once the reconciliation is triggered from customer's ERP, first ClearTax will download GSTR2A data from the government portal to ClearTax reconciliation product.
Each of these datasets can be huge and contain multiple sections across return periods. At times, the download can be slowed down due to the limitations on the government infrastructure. So these APIs are asynchronous and may take anywhere from a few seconds to a few minutes. Before we move on to the next step, it is important to ensure this download is completed in its entirety without any failed sections for any return period.
Once both the PR and 2A/2B documents are on ClearTax, ClearTax will trigger the reconciliation run. To enable the end-user to trigger this task from within the ERP, ClearTax provides an API that accepts the following parameters:
    1.
    Choice of recon (2A/2B) - mandatory
    2.
    PAN/ GSTIN selected for Recon
    3.
    Ingested Purchase Register, Downloaded 2A/2B (reference ID or URL)
    4.
    PR & 2A return period ranges
As soon as the reconciliation is completed on ClearTax, the end-user can see the result of matching in the Max ITC portal where they can take actions related to claim ITC / payment blocking flags.

Getting reconciliation results

Once the reconciliation task is completed on ClearTax, that is, post 24 hours (or as configured by the enterprise), ERP will send a GET request and receive a response file containing the results finalized on the Max ITC portal.

Blocking/unblocking payments on ERP

A custom program will be written in your ERP to use the reconciliation results to block payments in the immediate next payment cycle. It will enable automatic blocking of GST per the payment status received in the Max ITC result. It will also enable automatic release of GST as soon as the consecutive payment status received in the Max ITC result changes to ‘make payment’.

Interfaces

Delegator service

To simplify the overall integration, the first 3 steps in the approach above will be handled by a delegator service which will expose a single API request. This endpoint will take the request parameters related to all the 3 tasks together and then orchestrate them on the ClearTax end.
For Max ITC integration, we will have to implement the following interfaces:
    1.
    PR Ingestion & Reconciliation Trigger API
    2.
    Reconciliation Results API
PR Ingestion & Reconciliation Trigger API
Using this API, the PR documents are ingested along with the parameters required for consecutive actions. The delegator service will return a request ID and request status, and then schedule the tasks for further processing. The purchase register is to be uploaded in a predefined template.
Reconciliation Results API
Once the reconciliation is completed, you can get the reconciliation results using the request ID. This result can be saved in the ERP to block/unblock payments later. The response file will be in a predefined template.

Authentication and authorization

All the API requests will be authenticated with a static token sent in the request headers which is then used to check authorization for the actions requested against the organization (gstin/pan) ID.
Last modified 2d ago