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.

URL del Web Service:

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

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

Sí

Sí

Sí

Sí

Sí

Sí

===== 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

El flujo de operación es el siguiente:

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

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

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

El webhook recibe el siguiente parámetro mediante un método POST:

Ejemplo de payload recibido (Estructura de arreglo):

<code-block> [ 'xml' ⇒ 'contenido_xml_del_cfdi' ] </code-block>

Ejemplo básico de implementación en PHP:

<code-block> <?php $xml = $_POST['xml'] ?? null; if ($xml) { Procesar XML recibido (Guardar en disco, base de datos, etc.) file_put_contents( 'cfdi.xml', $xml ); echo “XML recibido correctamente”; } else { http_response_code(400); echo “XML no recibido”; } ?> </code-block> ===== 10. Recomendaciones para implementar el webhook ===== El endpoint receptor estructurado por el cliente debe cumplir con lo siguiente: * Aceptar solicitudes HTTP POST. * Validar estrictamente que el parámetro xml exista y no esté vacío. * Guardar o procesar el XML de forma asíncrona o ligera. * Responder rápidamente para evitar bloqueos por timeout en el servidor de IEngine. * Registrar en logs locales cualquier error de procesamiento. Respuesta recomendada esperada: HTTP 200 OK (Cuerpo: OK) ===== 11. Manejo de múltiples XML ===== Consideraciones importantes para el consumidor: * El webhook puede recibir múltiples llamadas consecutivas en un lapso corto de tiempo. * Cada llamada representa un CFDI completamente independiente. * No debe asumir ni esperar que todos los XML llegarán empaquetados en una sola petición. * Se recomienda implementar almacenamiento temporal o un sistema de procesamiento en cola (Queues) si se esperan grandes volúmenes de comprobantes fiscales. ===== 12. Consideraciones de seguridad ===== * Utilizar obligatoriamente HTTPS en la URL del callback. * Validar el origen IP de las solicitudes si es posible. * Implementar tokens de autenticación adicionales en la URL del webhook (Ej: ?token=xyz123). * Evitar almacenar los archivos XML expuestos públicamente en servidores web sin controles de acceso estrictos. ===== 13. Resumen del flujo ===== <code-block text-center text-white font-monospace> Cliente | | (Solicitud descarga SAT via GET) v IEngine Web Service | | (Consulta y descarga CFDI SAT) v XML Encontrado | | (Llamada POST webhook N veces) v Sistema Consumidor | | (Procesa, valida y almacena XML) </code-block> ===== 14. Ejemplo completo de escenario ===== Solicitud enviada: 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 esperado: Si existen 25 CFDI en ese rango de fechas: * El webhook del cliente será invocado de manera individual 25 veces. * Cada invocación recibirá un payload estructurado de la siguiente forma: <code-block> [ 'xml' ⇒ '<cfdi:Comprobante …> … </cfdi:Comprobante>' ] </code-block> ===== Tipos de comprobante CFDI soportados ===== El parámetro TipoComprobante permite filtrar el tipo de CFDI que se desea consultar durante la extracción desde el SAT. Los valores corresponden al catálogo oficial de la autoridad fiscal: ^Valor ^Tipo de Comprobante ^Descripción Oficial | |I | Ingreso |Comprobantes emitidos por la prestación de servicios, venta de productos, arrendamientos u operaciones donde existe un ingreso directo. | |E | Egreso |Comprobantes utilizados para devoluciones, descuentos, bonificaciones o ajustes relacionados con ingresos previamente registrados (Notas de crédito). | |T | Traslado |Comprobantes utilizados para acreditar legalmente el transporte o traslado de mercancías en territorio nacional. | |N | Nómina |Comprobantes fiscales digitales utilizados para registrar formalmente los pagos de salarios, sueldos y prestaciones a trabajadores. | |P | Pago |Comprobantes utilizados para registrar la recepción de pagos parciales o totales relacionados con operaciones previamente facturadas (Complemento para recepción de pagos). | ==== Ejemplos Rápidos de configuración: ==== * 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 del catálogo: == * El valor enviado debe utilizar obligatoriamente la letra correspondiente en Mayúscula. * La consulta se realizará de manera exclusiva para el tipo de comprobante indicado. * Para descargar diferentes tipos de CFDI en un mismo rango de fechas, se debe realizar una solicitud HTTP independiente por cada valor.