Synchronous and asynchronous transactions
POST requests to Indirect Tax API can result in either synchronous or asynchronous transactions. Each requires to be handled differently.
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. You then need to send GET requests per country, based on filter criteria such as the tax ID. Depending on the async configuration these requests are sent either after receiving a webhook call or a small timeout when no webhook is configured.
In response to these GET requests, Indirect Tax API returns an SCIResponseCode. You must then parse the SCIResponseCode to determine the transaction's status:
- SCIResponseCode is "CA", "RE", or "AP"
- The transaction is completed, so you should send a PUT request to mark it completed.
- SCIResponseCode is "AB" or "IP"
- The transaction is still being processed, and you need to proceed and handle the transaction according to your asynchronous communication setup.
Asynchronous communication setup
- Polling method
- In this case, you 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.Tip:
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.
- Pushing method (webhooks)
- In this case, you receive the information that there are new events available for processing, via previously configured webhooks. You then send GET requests that use the contentUrl from the webhooks.