Synchronous and asynchronous transactions
POST requests to the Indirect Tax API can result in either synchronous or asynchronous transactions, each requiring different handling by the client application.
In a synchronous transaction, Indirect Tax API returns a JSON response with a 200 status code and possibly an application response with an SCIResponseCode of "CA", "RE", or "AP." This means that the transaction has ended, and no further requests are necessary.
An asynchronous transaction starts when the client application sends a POST request. The Indirect Tax API responds with a JSON response that has a 202 status code and a documentId. Because the transaction is still in progress, the API does not include any application responses. The client then sends GET requests per country, based on filter criteria such as the tax ID.
In response to these GET requests, Indirect Tax API returns an SCIResponseCode. The client application must then parse the SCIResponseCode to determine the transaction's status:
- SCIResponseCode is "CA", "RE", or "AP"
- In this case, the transaction is completed, so the client should send a PUT request to mark it completed.
- SCIResponseCode is "AB" or "IP"
- In this case, the transaction is still being processed, and the client must send additional GET requests periodically. Because the tax authority's own processing time can vary greatly across different jurisdictions, Sovos recommends doing the first polling attempt after 30 seconds. If unsuccessful, wait an additional minute before retrying, and then increase the interval by another minute for each subsequent attempt.
Depending on the transaction volume, you might need to decrease the interval between the POST request and the GET or PUT requests. This ensures that the GET and PUT requests can be processed at the same or a higher frequency as the POST request, which prevents the list of notifications from growing indefinitely. This should be evaluated on a case-by-case basis, using the above-mentioned intervals as a general guideline.