Integration Flow

This guide describes the general flow of integration with Satws Connect.

Walk through

Creating credentials is the first step and is done by using the POST /credentials endpoint and applying two approaches to retrieve the status after validation. The first optional block is using POST /webhook-endpoint to create a webhook endpoint that will listen to credential.update events and notify in the URL once the validation against SAT is done; the second approach could be looping over GET /credentials/{id} to check the new status of the credential.

Usually, the validation with SAT portals takes between 10s to 20s.

Credentials status are:

• pending
• valid
• invalid
• deactivated
• error

After validations against SAT Portals of taxpayer credentials, Satws automatically creates a link if the taxpayer credential is valid, which is a representation of a relationship between the taxpayer and the customer account.

At this point, we can start creating extractions, which are jobs to download the data from different SAT portals depending on the extractor. Two scenarios fit this case: one is having the schedulers for first time extractions enabled (this only can be done on Dashboard), which will trigger extractions automatically based on the rules defined in the scheduler; the second scenario is using the POST /extractions to create the desired extractions.

All extractions are created with a pending status which means that they are waiting in a queue to start. Once it starts, the status change to running. Extractions status are described here.

Customers can subscribe webhook endpoints to extraction events and be notified when extractions are created or updated.

The below sequence diagram represents the flow using the first time scheduler from Dashboard.

Below sequence diagram represents the flow using POST /extractions.

Customers can always retrieve information from extractions reaching the GET /extractions/{id} endpoint.

After extractions are finished documents can be retrieved through specific endpoints described in our documentation.
Along with Insights and other information. Check the documentation for further information.