Bulk XML download

Bulk download (the SAT service that delivers the CFDIs a taxpayer issued and received) automatically retrieves three types of documents from the SAT (Mexico's tax authority, Servicio de Administración Tributaria): CFDIs (Mexico's electronic invoices), which are the complete invoices in XML; metadata, a summary of each CFDI; and withholding CFDIs (CFDI de Retenciones e Información de Pagos, the CFDIs that report taxes withheld from a payment). Use them to generate your electronic accounting (contabilidad electrónica, the accounting records Mexican taxpayers send to the SAT in XML) and journal entries; reconcile accounts payable, accounts receivable, and bank transactions; prepare audits; automate your supply chain and supplier payments; and verify the CFDIs you receive.

Legal framework

Bulk download is based on Articles 29 and 29-A of the CFF (Código Fiscal de la Federación, Mexico's Federal Tax Code), which set the obligation to issue CFDIs and their requirements. It's also based on Rule 2.7.6.4 of the Resolución Miscelánea Fiscal (RMF, the SAT's annual tax rules), which regulates the bulk download service for CFDIs and withholding CFDIs.

Requirements

Bulk download requires the taxpayer's current e.firma (the SAT advanced electronic signature that identifies a taxpayer, formerly FIEL). The e.firma and the CSD (Certificado de Sello Digital, the digital seal certificate used to sign CFDIs) each consist of a .cer file, a .key file, and a password, but they serve different purposes. The CSD only seals invoices, and the e.firma is a general-purpose electronic signature used for everything else, including bulk download.

Download types

Fiscalapi downloads three types of documents from the SAT. You choose the type with the satQueryTypeId field when you create a download rule.

Concepts

These are the bulk download concepts, from the most general to the most specific:

Entity hierarchy

API responses follow this hierarchy:

Regla de descarga
  └── Solicitud de descarga
        └── Paquete de descarga
              ├── Xml[]          (cuando satQueryTypeId = "CFDI")
              └── MetadataItem[] (cuando satQueryTypeId = "Metadata")

A rule generates requests over time: Fiscalapi creates at least one automatic request per day, and you can create as many manual requests as you need with the API. Each request produces one or more packages, and each package contains the extracted XML files or metadata.

Test environment

The SAT doesn't offer a test environment for bulk download. That's why Fiscalapi's test environment includes its own simulator, which reproduces the complete flow. To use it, follow these three steps.

Step 1: Set up your tenant to issue CFDIs

Follow the quickstart to set up your tenant (the space in Fiscalapi that holds your issuers, recipients, credits, and data): create an issuer person, upload its test certificates, and verify that you can issue invoices.

Step 2: Issue test invoices

Issue a few test invoices by reference (invoice by reference: you send the IDs of people and products already saved in Fiscalapi), with the API or from the dashboard. The simulation takes your most recent invoices whose issuer is a person registered in your tenant, so invoices by value (invoice by value: you send every issuer, recipient, and item value in the request) don't work for this step. You can use any HTTP client or the Postman collection, and the invoice tutorial explains the process in detail.

Step 3: Simulate bulk download from the dashboard

The simulator needs invoices issued in your tenant. Once you have them, go to Descarga CFDI > Reglas de descarga (CFDI download > Download rules) in the dashboard's side menu and click Agregar (Add) in the upper-right corner.

Create a test download rule from the dashboard

Test flow result

When you complete the flow, Fiscalapi creates a test download rule with status Aprobada (Approved) and a download request with status Completada (Completed), with the downloaded CFDIs (XML) and their metadata. You can also start the simulation with the API:

POST /api/v4/download-rules/test

How it works in production

To use bulk download in production, follow these steps in the dashboard:

1. Turn on the Bulk CFDI download add-on (an extra you add to your subscription, such as Auto CFDI invoicing) in Compras en línea > Módulos adicionales (Billing > Add-ons).
2. Create a person with the RFC you want to download documents for and upload its e.firma.
3. In Descarga CFDI > Reglas de descarga (CFDI download > Download rules), create a download rule and assign it to that person.
4. In Descarga CFDI > Solicitudes de descarga (CFDI download > Download requests), create a download request and assign it to the rule.

Table of download requests for CFDIs, metadata, or withholding CFDIs

Request types

Lifecycle

Download rules and requests go through several statuses while they're processed. Check them to track the progress of your downloads.

Download rule statuses

Pendiente (1) --> Aprobada (2) --> Abandonada (-1)
                             └--> Rechazada (3)

Request statuses (Fiscalapi)

EsperandoSat (1) --> EsperandoApi (2) --> Completada (3)
                                      └--> Abandonada (-1)

Request statuses at the SAT

Desconocido (0) --> Aceptada (1) --> EnProceso (2) --> Terminada (3)
                                                   └--> Error (4) --> Abandonada (-1)
                                                   └--> Rechazada (5) --> Abandonada (-1)
                                                   └--> Vencida (6) --> Abandonada (-1)

Automatic processing

From a rule's approval date, and while the rule stays in the Aprobada (Approved) status, Fiscalapi runs the download without manual intervention:

Validation rules

Download rule validations

Forbidden combinations

Period limits

Uniqueness rule

You can't have two active rules with the same RFC, query type (satQueryTypeId), issued or received (downloadTypeId), and invoice status (satInvoiceStatusId). A rule is active in any status except Abandonada (Abandoned). Uniqueness is checked by RFC, so it applies even if the RFC is registered under two people.

SAT status codes

The SAT responds to each bulk download operation with one of these codes:

Related resources