Descarga masiva de XML

La descarga masiva es un servicio que permite descargar de forma automática y programática tres tipos de comprobantes fiscales desde el SAT: CFDI (facturas completas en XML), Metadatos (resumen estructurado de comprobantes) y Retenciones (comprobantes de retenciones e información de pagos). La recuperación de estos documentos facilita la gestión documental, el cumplimiento normativo y la eficiencia fiscal de las empresas. Es especialmente útil para generar contabilidad electrónica, pólizas contables, auditorías, cuentas por pagar, cuentas por cobrar, automatizar procesos de la cadena de suministro, conciliaciones bancarias, pago a proveedores y verificación de comprobantes recibidos.

Marco legal

• Código Fiscal de la Federación (CFF), artículos 29 y 29-A: obligaciones de expedición y requisitos de comprobantes fiscales digitales.
• Regla 2.7.6.4 de la Resolución Miscelánea Fiscal (RMF): servicio de descarga masiva de CFDI y Retenciones.

Requisitos

Para poder utilizar el servicio de descarga masiva, se requiere contar con Firma Electrónica Avanzada (e.firma) vigente. La e.firma es equivalente a la anteriormente llamada FIEL y es diferente a los certificados de sello digital (CSD) utilizados para sellar las facturas emitidas. Ambas credenciales (e.firma y CSD) constan de un archivo .cer, archivo .key y una contraseña, pero tienen propósitos diferentes. La e.firma es una firma electrónica de propósito general (excepto para sellar facturas), mientras que los CSD se utilizan exclusivamente para sellar las facturas.

Tipos de descarga

Fiscalapi soporta tres tipos de descarga desde el SAT:

Conceptos

Todo el ciclo de la descarga masiva es gestionado vía cinco conceptos principales: Personas, Reglas de descarga, Solicitudes de descarga, Paquetes de descarga y documentos descargados (XML o Metadatos).

Personas

Una persona representa a un contribuyente, empresa, cliente, organización, usuario, holding, persona física, persona moral, etc. Vea Emisores o Receptores para más información.

Reglas de descarga

Una regla de descarga es una plantilla para crear solicitudes de descarga, es decir, una regla es un registro que se crea una vez con los datos repetitivos de una solicitud de descarga y se reutiliza para lanzar solicitudes automáticamente. La regla de descarga se asocia a una persona y a los criterios de los documentos que dicha persona quiere descargar, por ejemplo: CFDI, Recibidos, Vigentes.

Solicitudes de descarga

Una solicitud de descarga es un registro creado a partir de una regla de descarga; es la solicitud concreta y contiene los mismos datos de la regla más el período de descarga (fecha inicial y fecha final), adicionalmente otros campos para gestión de estado, mecanismos de resiliencia y reintentos.

Paquetes de descarga

Un paquete de descarga es un archivo ZIP que el SAT genera como respuesta a una solicitud completada. Cada solicitud puede generar uno o más paquetes. Los paquetes contienen los comprobantes solicitados y son procesados automáticamente por Fiscalapi para extraer su contenido.

XML parseados

Cuando el tipo de descarga es CFDI, cada comprobante XML contenido en los paquetes es parseado y almacenado de forma estructurada, permitiendo consultar los datos de cada factura (emisor, receptor, conceptos, impuestos, complementos, etc.) directamente desde la API sin necesidad de procesar el XML manualmente.

Metadatos

Cuando el tipo de descarga es Metadata, los datos del resumen de cada comprobante (UUID, RFC emisor, RFC receptor, fecha, monto, tipo, estatus) son extraídos y almacenados individualmente, permitiendo consultas rápidas y filtrado desde la API.

Jerarquía de entidades

Las respuestas de la API siguen esta estructura jerárquica:

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

Una Regla genera múltiples Solicitudes a lo largo del tiempo: al menos una solicitud automática por día (creada por Fiscalapi) y tantas solicitudes manuales como el usuario necesite vía API. Cada solicitud produce uno o más Paquetes, y cada paquete contiene los XML parseados o los Metadatos extraídos.

Ambiente de pruebas

El Servicio de Administración Tributaria (SAT) no proporciona un ambiente de pruebas para el servicio de descarga masiva. Sin embargo, Fiscalapi creó un entorno de simulación propio que permite probar el flujo completo de descarga masiva en el ambiente de pruebas.

Para utilizarlo, siga estos tres pasos:

Paso 1: Configurar la cuenta para emisión de CFDI

Siga el Quickstart para configurar su cuenta completamente: crear una persona emisor, subir sus certificados de pruebas, y verificar que puede emitir facturas.

Paso 2: Emitir facturas de prueba

Emita al menos algunas facturas de prueba utilizando la API o el dashboard. Puede usar cualquier cliente HTTP o la colección de Postman preconfigurada:

Colección de Postman

Dentro de la colección, busque los ejemplos en Facturas > Facturación Por Valores > Ingreso y lance solicitudes para crear facturas de prueba. También puede consultar el tutorial de emisión de facturas para más detalles.

Paso 3: Simular la descarga masiva desde el dashboard

Solo después de haber emitido facturas de prueba podrá simular la descarga masiva:

1. Navegue a Descarga XML en el menú lateral.
2. Seleccione Reglas de descarga.
3. Presione el botón AGREGAR en la parte superior derecha.

Crear una regla de descarga de prueba desde el dashboard

Resultado del flujo de prueba

Al completar el flujo anterior, Fiscalapi genera automáticamente:

• Una Regla de descarga de prueba con estado Aprobada.
• Una Solicitud de descarga asociada a esa regla con estado Completada.
• Los CFDI descargados (XML parseados) y Metadatos vinculados a dicha solicitud.

También puede activar este flujo de prueba vía API:

POST /api/v4/download-rules/test

Cómo funciona en producción

Para utilizar la descarga masiva en producción, siga los siguientes pasos dentro del dashboard:

1. Active el módulo desde el menú Compras en línea > Módulos adicionales.
2. Cree una persona y suba su e.firma.
3. Cree una regla de descarga desde el menú Descarga masiva > Reglas de descarga y asígnela a la persona creada.
4. Cree una solicitud de descarga desde el menú Descarga masiva > Solicitudes de descarga y asígnela a la regla creada.

Tabla de solicitudes de descarga de CFDI, Metadatos o Retenciones

Tipos de solicitud

Ciclo de vida

Las reglas y solicitudes de descarga atraviesan distintos estados durante su procesamiento. Conocer estos estados es útil para monitorear el progreso de las descargas.

Estados de la regla de descarga

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

Estados de la solicitud (Fiscalapi)

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

Estados de la solicitud en el SAT

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

Procesamiento automático

A partir de la fecha de aprobación de la regla de descarga y mientras la regla se mantenga en estado Aprobada, Fiscalapi se encarga de todo el proceso de descarga de manera automática:

1. Generación diaria: cada día a la 1:00 AM CST se crean solicitudes automáticas para descargar los documentos del día anterior (00:00:00 a 23:59:59).
2. Verificación y descarga: cada 30 minutos se verifica el estado de las solicitudes pendientes en el SAT y se descargan los paquetes disponibles.
3. Procesamiento de paquetes: los paquetes descargados son procesados automáticamente para extraer los XML o Metadatos.
4. Reintentos automáticos: si ocurre un error transitorio durante la descarga o el procesamiento, Fiscalapi reintenta automáticamente hasta que la solicitud alcance un estado definitivo (Completada o Abandonada).

Este ciclo se repite diariamente sin intervención del usuario.

Reglas de validación

Validaciones para reglas de descarga

Combinaciones prohibidas

Límites de período

Regla de unicidad

No puede existir una regla activa con la misma combinación de:

• personId (Persona / RFC)
• satQueryTypeId (Tipo de consulta)
• downloadTypeId (Dirección: Emitidos / Recibidos)
• satInvoiceStatusId (Estatus de factura)

Códigos de estado del SAT

El SAT responde con códigos numéricos que indican el resultado de las operaciones de descarga masiva:

Recursos relacionados