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

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

1. RFC del emisor.
   
2. Tipo de comprobante.
   
3. Periodo de consulta.
   
4. 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 corresponde al número de XML descargados.

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

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 ====
El endpoint receptor debe:
* 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:

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.