Tabla de Contenidos

Web Service de Descarga de CFDI del SAT – IEngine

Web Service de Descarga de CFDI del SAT – IEngine

1. Introducción

El presente documento describe el uso del Web Service IEngine – Descarga SAT, utilizado para solicitar la descarga de comprobantes fiscales digitales (CFDI) desde el SAT mediante los parámetros proporcionados.

El servicio permite consultar y descargar los XML asociados a un RFC emisor dentro de un rango de fechas determinado. Una vez obtenidos los comprobantes, el sistema envía cada XML descargado hacia un endpoint webhook configurado por el usuario.

2. Endpoint del Servicio

URL del Web Service:

https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php

3. Método de consumo

El servicio recibe parámetros mediante una solicitud HTTP GET.

Ejemplo de estructura:

https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php?engine=descagaSAT&RfcEmisor=RFC&TipoComprobante=N&callback=webhookUrl&fechaInicial=2025-10-22&fechaFinal=2025-10-24

4. Parámetros de entrada

Parámetro	Tipo	Requerido	Descripción
engine	String	Sí	Nombre del motor a ejecutar. Para descarga SAT debe enviarse descagaSAT.
RfcEmisor	String	Sí	RFC del emisor del cual se desean descargar comprobantes.
TipoComprobante	String	Sí	Tipo de comprobante a consultar. Ejemplo: N para nómina. Ver catálogo al final.
callback	URL/String	Sí	Endpoint donde serán enviados los XML descargados.
fechaInicial	Date	Sí	Fecha inicial del rango de búsqueda. Formato: YYYY-MM-DD
fechaFinal	Date	Sí	Fecha final del rango de búsqueda. Formato: YYYY-MM-DD

5. Ejemplo de solicitud

Solicitud (GET):

https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php?engine=descagaSAT&RfcEmisor=XAXX010101000&TipoComprobante=N&callback=https://midominio.com/webhook&fechaInicial=2025-10-22&fechaFinal=2025-10-24

6. Funcionamiento del servicio

El flujo de operación es el siguiente:

El usuario realiza una petición al Web Service indicando:
- RFC del emisor.
- Tipo de comprobante.
- Periodo de consulta.
- URL del webhook receptor.
El servicio consulta los CFDI disponibles en SAT.
Por cada XML encontrado, el servicio realiza una llamada HTTP al webhook registrado.
El webhook recibe el XML correspondiente.
El proceso se repite hasta enviar todos los XML encontrados.

7. Webhook receptor

Descripción: El webhook es un endpoint proporcionado por el usuario consumidor del servicio. Este endpoint será invocado N veces, donde N corresponds al número de XML descargados.

Nota: Si SAT devuelve 100 XML, el webhook será llamado 100 veces de forma individual y cada llamada contendrá un XML diferente.

8. Parámetros enviados al webhook

El webhook recibe un parámetro vía POST:

Parámetro	Tipo	Descripción
xml	String/XML	Contenido completo del CFDI descargado.

Ejemplo de payload recibido:

[
    'xml' => 'contenido_xml_del_cfdi'
]

9. Ejemplo de recepción del webhook

Ejemplo en PHP:

<?php

$xml = $_POST['xml'] ?? null;

if ($xml) {
    // Procesar XML recibido
    file_put_contents('cfdi.xml', $xml);
    echo "XML recibido correctamente";
} else {
    http_response_code(400);
    echo "XML no recibido";
}

?>

10. Recomendaciones para implementar el webhook

Aceptar solicitudes HTTP POST.
Validar que el parámetro xml exista.
Guardar o procesar el XML recibido.
Responder rápidamente para evitar tiempos de espera (timeouts).
Registrar errores de procesamiento.

Respuesta recomendada: HTTP 200 OK (Cuerpo: OK)

11. Manejo de múltiples XML

El webhook puede recibir múltiples llamadas consecutivas.
Cada llamada representa un CFDI independiente.
No debe asumir que todos los XML llegarán en una sola petición.
Debe implementar almacenamiento temporal o procesamiento en cola si espera grandes volúmenes.

12. Consideraciones de seguridad

Utilizar HTTPS en el callback.
Validar el origen de las solicitudes.
Implementar autenticación adicional en la URL si el ambiente lo requiere.
Evitar almacenar XML sin controles de acceso.

13. Resumen del flujo

Cliente
  |
  | Solicitud descarga SAT (GET)
  v
IEngine Web Service
  |
  | Consulta CFDI SAT
  v
XML encontrado
  |
  | POST webhook (N veces)
  v
Sistema consumidor (Procesa y almacena)

14. Ejemplo completo

Solicitud:

https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php?engine=descagaSAT&RfcEmisor=AAA010101AAA&TipoComprobante=N&callback=https://cliente.com/webhook/cfdi&fechaInicial=2025-10-22&fechaFinal=2025-10-24

Resultado si existen 25 CFDI:

El webhook será invocado 25 veces de forma independiente.
Cada invocación recibirá:

[
    'xml' => '<cfdi:Comprobante ... > ... </cfdi:Comprobante>'
]

Tipos de comprobante CFDI soportados

El parámetro TipoComprobante permite indicar el tipo de CFDI que se desea consultar durante la descarga desde SAT. Los valores posibles corresponden al atributo oficial definido por la autoridad:

Valor	Tipo de comprobante	Descripción
I	Ingreso	Comprobantes emitidos por la prestación de servicios, venta de productos, arrendamientos u operaciones donde existe un ingreso.
E	Egreso	Comprobantes utilizados para devoluciones, descuentos, bonificaciones o ajustes relacionados con ingresos previamente registrados.
T	Traslado	Comprobantes utilizados para acreditar el transporte o traslado de mercancías.
N	Nómina	Comprobantes fiscales digitales utilizados para registrar pagos de salarios y prestaciones a trabajadores.
P	Pago	Comprobantes utilizados para registrar la recepción de pagos relacionados con operaciones previamente facturadas.

Ejemplos de uso rápidos:

Descargar CFDI de nómina: TipoComprobante=N
Descargar facturas emitidas: TipoComprobante=I
Descargar notas de crédito: TipoComprobante=E
Descargar comprobantes de traslado: TipoComprobante=T
Descargar complementos de pago: TipoComprobante=P

Consideraciones adicionales:

El valor enviado debe utilizar la letra correspondiente en mayúscula.
La consulta se realizará únicamente para el tipo de comprobante indicado.
Para descargar diferentes tipos de CFDI se debe realizar una solicitud independiente por cada valor.

iTimbre Wiki

Herramientas de usuario

Herramientas del sitio