> ## Documentation Index
> Fetch the complete documentation index at: https://docs.syntage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration Flow

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](/api-reference/ds-mx-sat-credentials/create-a-credential). After the credential is submitted, use one of these approaches to track validation:

* Create a webhook endpoint with [Create a webhook endpoint](/api-reference/webhook-endpoints/create-a-webhook-endpoint) and listen for `credential.updated` events.
* Poll [Retrieve a credential](/api-reference/ds-mx-sat-credentials/retrieve-a-credential) until the credential reaches a final status.

SAT credential validation usually takes between 10 and 20 seconds.

A credential can have one of the following statuses:

| Status        | Description                                                                                                               |
| ------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `waiting`     | Credential validation is temporarily disabled, usually because of an ongoing incident. The credential is validated later. |
| `pending`     | Credential validation has been requested and is waiting to be processed.                                                  |
| `valid`       | The credential was accepted by SAT and can be used for extractions.                                                       |
| `invalid`     | SAT rejected the credential during validation.                                                                            |
| `disabled`    | SAT reported the credential as disabled or otherwise unrecoverable during validation.                                     |
| `deactivated` | **Deprecated.** Legacy status retained for existing records. Use `disabled` for credentials that can no longer be used.   |
| `error`       | Credential 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.

```mermaid theme={null}
sequenceDiagram
    %%{init: {'securityLevel': 'loose', 'theme': 'base'}}%%

    autonumber
    participant Client
    participant Syntage
    participant SAT

    Client->>+Syntage: Create credential (POST /credentials)
    Syntage-->>-Client: Credential response
    Syntage->>+SAT: Validate credential
    SAT-->>-Syntage: Validation result

    opt webhook endpoint subscribed to credential.updated
        Syntage->>Client: Send credential.updated event
    end

    loop until the credential reaches a final status
        Client->>Syntage: Retrieve credential (GET /credentials/{id})
        Syntage-->>Client: Credential response
    end
```

## 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](/api-reference/extractions/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](/api-reference/extractions/retrieve-an-extraction).

You can create webhook endpoints for extraction events and receive notifications when extractions are created or updated.

```mermaid theme={null}
sequenceDiagram
    %%{init: {'securityLevel': 'loose', 'theme': 'base'}}%%

    autonumber
    participant Client
    participant Syntage
    participant Datasource

    Client->>+Syntage: Create extraction (POST /extractions)
    Syntage-->>-Client: Extraction response

    opt webhooks are enabled
        Syntage->>Client: Send extraction.created event
    end

    Syntage->>Syntage: Start extraction

    opt extraction status changes
        Syntage->>Client: Send extraction.updated event
    end

    Syntage->>+Datasource: Retrieve data for the entity
    Datasource-->>-Syntage: Return records

    opt extraction finishes
        Syntage->>Client: Send extraction.updated event
    end
```

After an extraction finishes, use the relevant API reference pages to retrieve the extracted records, reports, insights, or files.