Skip to main content
This guide describes a common SAT credential and extraction flow. Other datasources may use different credentials, authorizations, or report endpoints, but the same general pattern applies: create or identify the entity, provide the required datasource access, request or schedule data extraction, and listen for webhook events.

​
Create and validate a SAT credential

Create a SAT credential with Create a credential. After the credential is submitted, use one of these approaches to track validation: SAT credential validation usually takes between 10 and 20 seconds. A credential can have one of the following statuses:
StatusDescription
waitingCredential validation is temporarily disabled, usually because of an ongoing incident. The credential is validated later.
pendingCredential validation has been requested and is waiting to be processed.
validThe credential was accepted by SAT and can be used for extractions.
invalidSAT rejected the credential during validation.
disabledSAT reported the credential as disabled or otherwise unrecoverable during validation.
deactivatedDeprecated. Legacy status retained for existing records. Use disabled for credentials that can no longer be used.
errorCredential validation failed because of an unexpected error.
Some credential responses include a statusReason object with a more specific reason for the status. For example, an error credential can include statusReason.type: "unsupportedPortableEfirma" when SAT requires the portable e.firma dynamic-code flow, which Syntage does not support for credential registration. When a SAT credential becomes valid, Syntage creates the related entity if it does not already exist.

​
Extract data

After the entity and credential are available, you can request data extraction. Extractions are jobs that retrieve data from a datasource, such as SAT invoices, tax returns, tax status, tax compliance checks, and other supported records. You can create an extraction directly with Create an extraction. Schedulers can also create recurring or first-time extractions when configured for your organization. All extractions start with a pending status while they wait in the queue. When processing starts, the status changes to running. You can retrieve the current status with Retrieve an extraction. You can create webhook endpoints for extraction events and receive notifications when extractions are created or updated. After an extraction finishes, use the relevant API reference pages to retrieve the extracted records, reports, insights, or files.