Preview a range of SAT history before paying for it

POST

https://api.gigstack.io/v2/invoices/download/preview

Queues a metadata pull for a date range and reports how many CFDIs exist and what downloading them would cost.

Reading header data from the SAT costs nothing; only fetching an XML is billed. This endpoint uses that gap: it stores what it finds as browsable rows in the metadata stage, which you can list with GET /invoices/sat?sync_state=metadata and then selectively import.

Answers 202, not 200. One month is roughly a twelve second round trip to the SAT and a full history is dozens of them, well past any HTTP timeout. Poll GET /invoices/download/jobs/{id} for progress.

Only one job may run per team at a time.

Request

Authorization

API Key

Add parameter in header

Authorization

Example:

Authorization: ********************

Query Params

Body Params application/jsonRequired

Examples

Responses

🟢202Accepted

application/json

Job queued

Bodyapplication/json

🟠400Bad Request

🟠401Unauthorized

🟠403Forbidden

🟠409

🔴500Server Error

Request Example

Shell

JavaScript

Java

Swift

curl --location 'https://api.gigstack.io/v2/invoices/download/preview?team=undefined' \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--data '{
    "start_date": "2026-01-01",
    "end_date": "2026-08-31",
    "directions": [
        "issued"
    ]
}'

Response Example

202 - Example 1

{
    "success": true,
    "data": {
        "id": "satjob_a1b2c3d4e5",
        "status": "queued",
        "total_windows": 0
    }
}

Modified at 2026-08-31 18:26:55

Get SAT history sync progress

List recent preview and import jobs