Descarga Masiva SAT Guide

Download all your issued and received CFDI invoices directly from SAT using your FIEL (Firma Electrónica Avanzada). Descarga Masiva gives you a complete history of every invoice associated with your RFC — whether you issued it in gigstack or not.

Overview

The Descarga Masiva API lets you connect your RFC to SAT's bulk download service and retrieve your full invoice history. You can run one-time requests for specific date ranges, or set up a daily schedule that automatically syncs new invoices.

Key Features

Full Invoice History - Download all issued and received CFDIs from SAT, regardless of origin

Automatic Daily Sync - Schedule recurring downloads to keep your data up to date

FIEL Authentication - Secure connection using your electronic signature (FIEL)

Live Status Updates - Status polling refreshes pending requests in real time

Metered Billing - Pay only for what you download ($0.20 MXN per XML)

Prerequisites

Before using Descarga Masiva:

Your team must have a valid RFC configured

You need an active paid gigstack plan

You must have your FIEL files (.cer + .key) and their password ready

FIEL vs CSD: The FIEL (Firma Electrónica Avanzada) is your personal digital identity certificate used to authenticate with SAT. It is different from the CSD (Certificado de Sello Digital), which is used to stamp CFDI invoices. You need both for full gigstack functionality.

Setup Flow

Step 1 — Check Activation Status

Before anything else, check whether Descarga Masiva is activated for your team.

Response:

{
    "success": true,
    "data": {
        "status": "needs_activation",
        "planIncludesFeature": true,
        "isActivated": false,
        "pricing": {
            "perDownload": "$0.20 MXN",
            "addonMonthly": null
        }
    }
}

Status values:

Status	Meaning	Next step
`active`	Ready to use	Go to Step 3
`needs_activation`	Your plan includes it, not yet turned on	Call `POST /activate`
`needs_addon`	Paid plan, feature not included	Call `POST /activate` — adds $400 MXN/RFC/month
`needs_upgrade`	Free plan	Upgrade your plan first

Step 2 — Activate

Response:

{
    "success": true,
    "message": "Descarga Masiva activada. Cada descarga de XML consumirá créditos SAT.",
    "data": {
        "type": "included",
        "activated": true
    }
}

Billing:

If your plan includes Descarga Masiva (type: "included"): activation is free — you only pay $0.20 MXN per XML downloaded.

If activating as an add-on (type: "addon"):

400 MXN / RFC / m o n t hi s a dd e d t oyo u rs u b scr i pt i o n, p ror a t e d t o t o d a y, pl u s

0.20 MXN per XML.

Step 3 — Upload your FIEL

This is the main setup step. Upload your .cer and .key files along with the password. gigstack validates your FIEL, securely stores the credentials, and automatically registers your RFC with SAT — all in one request.

Parameters:

Field	Type	Required	Description
`cert`	file	Yes	`.cer` file from SAT
`key`	file	Yes	`.key` file from SAT
`password`	string	Yes	Password for the `.key` file
`sync_start_date`	string	Recommended	Start date for historical sync (`YYYY-MM-DD`, up to 71 months back)
`phone`	string	Recommended	Contact phone in international format (`+52...`)

Response:

{
    "success": true,
    "message": "FIEL credentials stored successfully. Business registered with SAT sync enabled.",
    "data": {
        "rfc": "XAXX010101000",
        "expires_at": 1893456000000,
        "expires_at_readable": "2029-12-31T00:00:00.000Z",
        "serial_number": "00001000000504465028",
        "sync_start_date": "2023-01-01",
        "phone": "+5215512345678",
        "registered": true,
        "registered_at": 1743600000000
    }
}

When registered: true, your RFC is connected to SAT and you can start downloading invoices immediately.

If registered: false, registration failed (rare — usually a temporary SAT service issue). Use POST /v2/invoices/download/register to retry.

Downloading Invoices

Once activated and registered, you have two options: scheduled daily sync or manual requests.

Option A — Scheduled Daily Sync

Set up a schedule and gigstack automatically downloads new invoices every day.

Parameters:

Field	Type	Required	Description
`enabled`	boolean	Yes	Enable or disable the schedule
`time`	string	Yes	Run time in `HH:mm` format (America/Mexico_City timezone)
`download_types`	array	Yes	`["issued"]`, `["received"]`, or `["issued", "received"]`
`days_back`	integer	Yes	How many days back to look on each run (1–90)

Response:

{
    "success": true,
    "message": "Scheduled download enabled successfully",
    "data": {
        "schedule": {
            "enabled": true,
            "time": "21:00",
            "downloadTypes": ["received"],
            "daysBack": 1,
            "lastRunAt": null,
            "lastRunStatus": null,
            "lastRunError": null
        }
    }
}

To check your current schedule configuration and FIEL status:

Option B — Manual Download Request

Submit a request for a specific date range. SAT processes it asynchronously.

Parameters:

Field	Type	Required	Description
`start_date`	string	Yes	Start of date range (`YYYY-MM-DD`)
`end_date`	string	Yes	End of date range (`YYYY-MM-DD`, max 1 month from start)
`rfc_type`	string	No	`"issued"` or `"received"` (default: `"received"`)
`request_type`	string	No	`"cfdi"` (XML files) or `"metadata"` (default: `"cfdi"`)
`invoice_type`	string	No	Filter by CFDI type: `I`, `E`, `P`, `N`, `T`
`invoice_status`	string	No	`"active"`, `"cancelled"`, or `"all"` (default: `"all"`)
`third_party_rfc`	string	No	Filter by counterparty RFC

Date range limit: SAT limits each request to a maximum of 1 month. For longer periods, submit one request per month.

Response:

{
    "success": true,
    "data": {
        "request_id": "req_abc123",
        "status": "pending",
        "duplicate": false
    }
}

Tracking Request Status

Check the status of your download history — pending requests are updated in real time:

Response:

{
    "success": true,
    "data": {
        "history": [
            {
                "id": "req_abc123",
                "rfcType": "received",
                "startDate": "2024-01-01",
                "endDate": "2024-01-31",
                "status": "completed",
                "invoiceCount": 143,
                "processedCount": 143,
                "source": "manual",
                "latestIssueDate": "2024-01-30",
                "earliestIssueDate": "2024-01-02",
                "createdAt": 1706745600000,
                "completedAt": 1706832000000
            }
        ]
    }
}

Status values:

Status	Meaning
`pending`	Request queued, being sent to SAT
`accepted`	SAT accepted the request
`processing`	SAT is generating the package
`completed`	Done — invoice count available
`failed`	SAT rejected (check `statusMessage`)
`expired`	Package expired before download

Deactivation

To stop Descarga Masiva and remove billing:

Scheduled downloads stop immediately. If the feature was billed as an add-on, the charge is removed from your subscription (prorated). Any XML downloads already recorded in the current period are still billed at period end.

Common Errors

Error	Cause	Fix
`RFC mismatch`	Certificate RFC doesn't match your team RFC	Upload the FIEL that belongs to this team's RFC
`Certificate expired`	FIEL has expired	Renew your FIEL at SAT's portal
`Failed to decrypt private key`	Wrong password for the `.key` file	Use the password created when generating the FIEL
`Invalid certificate file format`	Wrong file type	Upload `.cer` and `.key` files directly from SAT — do not convert
`Team RFC not configured`	Team has no RFC	Set up your fiscal information in gigstack settings first
`No active subscription`	No paid plan	Activate a paid plan before using Descarga Masiva
`duplicate: true`	Same request already submitted	No action needed — the existing request is still processing

Full Endpoint Reference

Method	Endpoint	Description
`GET`	`/v2/invoices/download/activate/status`	Check activation status
`POST`	`/v2/invoices/download/activate`	Activate billing
`POST`	`/v2/invoices/download/deactivate`	Deactivate billing
`POST`	`/v2/invoices/download/fiel`	Upload FIEL credentials
`POST`	`/v2/invoices/download/register`	Manual SAT registration (fallback)
`GET`	`/v2/invoices/download/schedule`	Get schedule + FIEL status
`PUT`	`/v2/invoices/download/schedule`	Save schedule config
`GET`	`/v2/invoices/download/schedule/history`	Download request history
`POST`	`/v2/invoices/download/request`	Submit manual download request
`GET`	`/v2/invoices/download/status/:request_id`	Check specific request
`GET`	`/v2/invoices/download/package/:package_id`	Download ZIP of XMLs
`GET`	`/v2/invoices/download/invoice/:uuid`	Get single CFDI from SAT
`GET`	`/v2/invoices/download/debug`	Debug SAT connectivity

Descarga Masiva

Descarga Masiva SAT Guide#

Overview#

Key Features#

Prerequisites#

Setup Flow#

Step 1 — Check Activation Status#

Step 2 — Activate#

Step 3 — Upload your FIEL#

Downloading Invoices#

Option A — Scheduled Daily Sync#

Option B — Manual Download Request#

Tracking Request Status#

Deactivation#

Common Errors#

Full Endpoint Reference#

Descarga Masiva SAT Guide

Overview

Key Features

Prerequisites

Setup Flow

Step 1 — Check Activation Status

Step 2 — Activate

Step 3 — Upload your FIEL

Downloading Invoices

Option A — Scheduled Daily Sync

Option B — Manual Download Request

Tracking Request Status

Deactivation

Common Errors

Full Endpoint Reference