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

* Create a webhook endpoint with [Create a webhook endpoint](https://docs.syntage.com/api-reference/webhook-endpoints/create-a-webhook-endpoint.md) and listen for `credential.updated` events.
* Poll [Retrieve a credential](https://docs.syntage.com/api-reference/ds-mx-sat-credentials/retrieve-a-credential.md) 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](https://docs.syntage.com/api-reference/extractions/create-an-extraction.md). 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](https://docs.syntage.com/api-reference/extractions/retrieve-an-extraction.md).

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.