Bulk download rules

A download rule is a template for creating requests to download CFDIs (Mexico's electronic invoices), metadata, or withholding CFDIs (CFDI de Retenciones e Información de Pagos, the CFDIs that report taxes withheld from a payment) from the SAT (Mexico's tax authority, Servicio de Administración Tributaria). It stores the data that repeats in every request: the requesting person (any individual or legal entity registered in your tenant), with their RFC (Mexico's taxpayer ID, Registro Federal de Contribuyentes) and e.firma (the SAT advanced electronic signature that identifies a taxpayer, formerly FIEL); the document type; whether the documents are issued or received; and their status. You create it once and reuse it to create many download requests.

See the introduction to bulk download (bulk download: the SAT service that delivers the CFDIs a taxpayer issued and received) for its concepts.

Download rule model

The download rule model contains all of a rule's data.

Properties

Name
id
Type
string?
Description
The download rule's ID, assigned by Fiscalapi.
Name
description
Type
string?
Description
The download rule's description or name.
Name
personId
Type
string?
expandable
Description
The ID of the rule's person. See issuers or recipients for the person model.
Name
tin
Type
string?
Description
The RFC of the rule's person.
Name
downloadRuleStatusId
Type
string?
expandable
Description
The ID of the rule's status. See the download rule statuses.
Type
enum:
Values
"-1""1""2"
Name
satQueryTypeId
Type
string?
expandable
Description
The document type the rule downloads.
Type
enum:
Values
"CFDI""Metadata""Retenciones"
Name
downloadTypeId
Type
string?
expandable
Description
Whether the rule downloads the CFDIs the person issued or the ones they received.
Type
enum:
Values
"Emitidos""Recibidos"
Name
satInvoiceStatusId
Type
string?
expandable
Description
The status of the CFDIs the rule downloads. "Cancelado" is valid only with the "Metadata" type.
Type
enum:
Values
"Cancelado""Vigente"

GET/api/v4/download-rules

List rules

This endpoint returns a paginated list of download rules, ten per page by default. Use the query parameters to adjust the pagination.

Query parameters

Name
pageNumber
Type
integer | number
required
Description
The page number you want to retrieve.
Default:
1
Name
pageSize
Type
integer | number
required
Description
The number of records per page, from 1 to 50.
Default:
10

Request

GET

/api/v4/download-rules?pageNumber=1&pageSize=2

curl --location 'https://test.fiscalapi.com/api/v4/download-rules?pageNumber=1&pageSize=2' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": {
        "items": [
            {
                "person": {
                    "legalName": "KARLA FUENTE NOLASCO",
                    "email": "karla@gmail.com",
                    "phoneNumber": null,
                    "validTo": "2025-07-06T15:26:06.906",
                    "satTaxRegimeId": "626",
                    "satTaxRegime": {
                        "id": "626",
                        "description": "Régimen Simplificado de Confianza",
                        "createdAt": "2024-08-10T15:46:30.373",
                        "updatedAt": null
                    },
                    "satCfdiUseId": "G03",
                    "satCfdiUse": {
                        "id": "G03",
                        "description": "Gastos en general.",
                        "createdAt": "2024-08-10T15:46:30.373",
                        "updatedAt": null
                    },
                    "userTypeId": "C",
                    "userType": {
                        "id": "C",
                        "description": "Cliente",
                        "createdAt": "2024-08-10T15:46:30.373",
                        "updatedAt": null
                    },
                    "manifestStatusId": "NotInvited",
                    "manifestStatus": null,
                    "tin": "FUNK671228PH6",
                    "zipCode": "01160",
                    "base64Photo": null,
                    "taxPassword": null,
                    "curp": null,
                    "countryId": null,
                    "country": null,
                    "foreignTin": null,
                    "availableBalance": 2,
                    "committedBalance": 0,
                    "availableValidationBalance": 0,
                    "balances": [
                        {
                            "creditType": 1,
                            "available": 2
                        }
                    ],
                    "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
                    "isOwner": false,
                    "id": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
                    "createdAt": "2025-01-07T15:26:06.906",
                    "updatedAt": "2025-07-09T15:14:42.597"
                },
                "tin": "FUNK671228PH6",
                "description": "Regla de prueba descarga XML.",
                "downloadRuleStatus": {
                    "description": "Aprobada",
                    "id": "2",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": null
                },
                "satQueryType": {
                    "description": "Facturas",
                    "id": "CFDI",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": null
                },
                "downloadType": {
                    "description": "Recibidos",
                    "id": "Recibidos",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": null
                },
                "satInvoiceStatus": {
                    "description": "Vigente",
                    "id": "Vigente",
                    "createdAt": "2024-08-10T15:46:30.373",
                    "updatedAt": null
                },
                "isTest": true,
                "id": "99d42dca-a555-4e77-b036-379652a3976a",
                "createdAt": "2025-08-16T10:34:25.040",
                "updatedAt": "2025-08-16T10:34:25.040"
            }
        ],
        "pageNumber": 1,
        "totalPages": 1,
        "totalCount": 1,
        "hasPreviousPage": false,
        "hasNextPage": false
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

POST/api/v4/download-rules

Create a rule

This endpoint creates a download rule. Only the tenant owner (tenant: the space in Fiscalapi that holds your issuers, recipients, credits, and data; owner: the person who created the tenant) can create a rule for the owner; if you use the API key of any other person in the tenant, the endpoint returns 403.

Request body

Name
personId
Type
string
required
Description
The ID of the rule's person. The person must have a valid RFC and a current e.firma.
Name
description
Type
string
required
Description
The rule's description or name, up to 100 characters.
Name
satQueryTypeId
Type
string
required
Description
The document type the rule downloads.
Type
enum:
Values
"CFDI""Metadata""Retenciones"
Name
downloadTypeId
Type
string
required
Description
Whether the rule downloads the CFDIs the person issued or the ones they received.
Type
enum:
Values
"Emitidos""Recibidos"
Name
satInvoiceStatusId
Type
string
required
Description
The status of the CFDIs the rule downloads. "Cancelado" is valid only with the "Metadata" type.
Type
enum:
Values
"Cancelado""Vigente"

Errors

The message arrives in details.

Status	When it happens	Message
403	The rule belongs to the owner and you use the API key of another person in the tenant. Fiscalapi checks this before it checks the seats (seat: one RFC and one download type in bulk download) and the e.firma.	Solo el propietario de la cuenta puede modificar al propietario de la cuenta.

Request

POST

/api/v4/download-rules

curl --location 'https://test.fiscalapi.com/api/v4/download-rules' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "personId": "b0c1cf6c-153a-464e-99df-5741f45d6695",
  "description": "Regla Regla Demo1",
  "satQueryTypeId": "CFDI",
  "downloadTypeId": "Recibidos",
  "satInvoiceStatusId": "Vigente"
}'

Response

{
    "data": {
        "person": null,
        "tin": "FUNK671228PH6",
        "description": "Regla Regla Demo1",
        "downloadRuleStatus": null,
        "satQueryType": null,
        "downloadType": null,
        "satInvoiceStatus": null,
        "isTest": false,
        "id": "a376039a-58b7-46a1-b2de-8282938c9d7d",
        "createdAt": "2025-08-14T19:14:25.239",
        "updatedAt": "2025-08-14T19:14:25.239"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

GET/api/v4/download-rules/<id>

Get a rule by ID

This endpoint returns a download rule by its ID.

Errors

In the message, which arrives in details, <id> is the rule's ID.

Status	When it happens	Message
404	The rule doesn't exist or belongs to another tenant.	No such resource for the given Id: <id>

Request

GET

/api/v4/download-rules/<id>

curl --location 'https://test.fiscalapi.com/api/v4/download-rules/2c6aafcf-8cd2-4fb1-94a8-687adc671380' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": {
        "person": {
            "legalName": "KARLA FUENTE NOLASCO",
            "email": "karla@gmail.com",
            "phoneNumber": null,
            "validTo": "2025-07-06T15:26:06.906",
            "satTaxRegimeId": "626",
            "satTaxRegime": null,
            "satCfdiUseId": "G03",
            "satCfdiUse": null,
            "userTypeId": "C",
            "userType": null,
            "manifestStatusId": "NotInvited",
            "manifestStatus": null,
            "tin": "FUNK671228PH6",
            "zipCode": "01160",
            "base64Photo": null,
            "taxPassword": null,
            "curp": null,
            "countryId": null,
            "country": null,
            "foreignTin": null,
            "availableBalance": 2,
            "committedBalance": 0,
            "availableValidationBalance": 0,
            "balances": [
                {
                    "creditType": 1,
                    "available": 2
                }
            ],
            "tenantId": "102e5f13-e114-41dd-bea7-507fce177281",
            "isOwner": false,
            "id": "78d380fd-1b69-4e3c-8bc0-4f57737f7d5f",
            "createdAt": "2025-01-07T15:26:06.906",
            "updatedAt": "2025-07-09T15:14:42.597"
        },
        "tin": "FUNK671228PH6",
        "description": "Regla de prueba descarga XML.",
        "downloadRuleStatus": {
            "description": "Aprobada",
            "id": "2",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satQueryType": {
            "description": "Facturas",
            "id": "CFDI",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "downloadType": {
            "description": "Recibidos",
            "id": "Recibidos",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "satInvoiceStatus": {
            "description": "Vigente",
            "id": "Vigente",
            "createdAt": "2024-08-10T15:46:30.373",
            "updatedAt": null
        },
        "isTest": true,
        "id": "3a14c528-8315-4d47-a9ef-65aca7c0a95e",
        "createdAt": "2025-08-14T17:52:41.192",
        "updatedAt": "2025-08-14T17:52:41.192"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

PUT/api/v4/download-rules/<id>

Update a rule

This endpoint updates a download rule's description. Only the tenant owner can update a rule that belongs to the owner; if you use the API key of any other person in the tenant, the endpoint returns 403.

Request body

Name
id
Type
string
required
Description
The download rule's ID, assigned by Fiscalapi.
Name
description
Type
string
required
Description
The rule's new description or name, up to 100 characters.

Errors

The message arrives in details.

Status	When it happens	Message
403	The rule belongs to the owner and you use the API key of another person in the tenant.	Solo el propietario de la cuenta puede modificar al propietario de la cuenta.

Request

PUT

/api/v4/download-rules/<id>

curl --location --request PUT 'http://localhost:5001/api/v4/download-rules/8d5905f3-d7e1-46b7-b0f4-9f3a2528bb56' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <api-key>' \
--data '{
  "id": "8d5905f3-d7e1-46b7-b0f4-9f3a2528bb56",
  "description": "REGLA DESCARGA CFDI KARLA FUENTES"
}'

Response

{
    "data": {
        "person": null,
        "tin": "FUNK671228PH6",
        "description": "REGLA DESCARGA CFDI KARLA FUENTES",
        "downloadRuleStatus": null,
        "satQueryType": null,
        "downloadType": null,
        "satInvoiceStatus": null,
        "isTest": true,
        "id": "8d5905f3-d7e1-46b7-b0f4-9f3a2528bb56",
        "createdAt": "2025-08-15T17:09:20.359",
        "updatedAt": "2025-08-15T17:19:52.886"
    },
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}

DELETE/api/v4/download-rules/<id>

Delete a rule

This endpoint deletes a download rule by its ID. Only the tenant owner can delete a rule that belongs to the owner; if you use the API key of any other person in the tenant, the endpoint returns 403 and the rule isn't deleted.

Errors

The messages arrive in details. In the 404 message, <id> is the rule's ID.

Status	When it happens	Message
403	The rule belongs to the owner and you use the API key of another person in the tenant.	Solo el propietario de la cuenta puede modificar al propietario de la cuenta.
404	The rule doesn't exist or belongs to another tenant.	No such resource for the given Id: <id>

Request

DELETE

/api/v4/download-rules/<id>

curl --location --request DELETE 'https://test.fiscalapi.com/api/v4/download-rules/5d2dfd35-9e1c-4263-973e-5121aef74087' \
--header 'X-TENANT-KEY: <tenant-key>' \
--header 'X-TIME-ZONE: America/Mexico_City' \
--header 'X-API-KEY: <api-key>'

Response

{
    "data": true,
    "succeeded": true,
    "message": "",
    "details": "",
    "httpStatusCode": 200
}