====== 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:** ===== 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' => ' ... ' ] ===== 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. \\