Diferencias

Muestra las diferencias entre dos versiones de la página.

--- web-service-descarga-masiva-sat [2026/07/07 20:20]
creado
+++ web-service-descarga-masiva-sat [2026/07/07 20:51] (actual)
@@ Línea 1: / Línea 1: @@
+====== Web Service de Descarga de CFDI del SAT – IEngine ======
+===== 1. Introducción =====
-**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.
@@ Línea 9: / Línea 7: @@
 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 =====
-**2. Endpoint del Servicio**
-**URL del Web Service**
+**URL del Web Service:**
 https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php
-----
+===== 3. Método de consumo =====
-**3. Método de consumo**
+El servicio recibe parámetros mediante una solicitud **HTTP GET**.
-El servicio recibe parámetros mediante una solicitud HTTP GET.
+**Ejemplo de estructura:**
-Ejemplo:
+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
-https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php?
+===== 4. Parámetros de entrada =====
-engine=descagaSAT&
+^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 |
-RfcEmisor=RFC&
+===== 5. Ejemplo de solicitud =====
-TipoComprobante=N&
+**Solicitud (GET):**
-callback=webhookUrl&
+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
-fechaInicial=2025-10-22&
+===== 6. Funcionamiento del servicio =====
-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. \\  |
-| \\ 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:
+  * 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.
+  * El servicio consulta los CFDI disponibles en SAT.
-  - Por cada XML encontrado, el servicio realiza una llamada HTTP al webhook registrado.
+  * Por cada XML encontrado, el servicio realiza una llamada HTTP al webhook registrado.
-  - El webhook recibe el XML correspondiente.
+  * El webhook recibe el XML correspondiente.
-  - El proceso se repite hasta enviar todos los XML encontrados.
+  * El proceso se repite hasta enviar todos los XML encontrados.
-----
+===== 7. Webhook receptor =====
-**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.
-**Descripción**
+**Nota:**  Si SAT devuelve 100 XML, el webhook será llamado 100 veces de forma individual y cada llamada contendrá un XML diferente.
-El webhook es un endpoint proporcionado por el usuario consumidor del servicio.
+===== 8. Parámetros enviados al webhook =====
-Este endpoint será invocado **N veces**, donde **N corresponde al número de XML descargados**.
+El webhook recibe un parámetro vía POST:
-Ejemplo:
+^Parámetro ^Tipo ^Descripción |
+|**xml**   |String/XML |Contenido completo del CFDI descargado. |
-  * Si SAT devuelve 100 XML:
+**Ejemplo de payload recibido:**
-      * El webhook será llamado 100 veces.
-      * Cada llamada contendrá un XML diferente.
-----
-**8. Parámetros enviados al webhook**
-El webhook recibe un parámetro:
-^ \\ **Parámetro** \\    ^ \\ **Tipo** \\    ^ \\ **Descripción** \\    |
-| \\ xml \\  | \\ String/XML \\  | \\ Contenido completo del CFDI descargado. \\  |
-Ejemplo de payload recibido:
-[
-'xml' => 'contenido_xml_del_cfdi'
+<code>[
+    'xml' => 'contenido_xml_del_cfdi'
 ]
+</code>
+===== 9. Ejemplo de recepción del webhook =====
-----
+**Ejemplo en PHP:**
-**9. Ejemplo de recepción del webhook**
+<code><?php
-Ejemplo en PHP:
-<?php
 $xml = $_POST['xml'] ?? null;
 if ($xml) {
+    // Procesar XML recibido
-// Procesar XML recibido
+    file_put_contents('cfdi.xml', $xml);
+    echo "XML recibido correctamente";
-file_put_contents(
-'cfdi.xml',
-$xml
-);
-echo "XML recibido correctamente";
 } else {
+    http_response_code(400);
-http_response_code(400);
+    echo "XML no recibido";
-echo "XML no recibido";
 }
 ?>
+</code>
-----
+===== 10. Recomendaciones para implementar el webhook =====
-**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.
+  * Responder rápidamente para evitar tiempos de espera (timeouts).
   * Registrar errores de procesamiento.
-Respuesta recomendada:
+**Respuesta recomendada:**  HTTP 200 OK (Cuerpo: OK)
-HTTP 200 OK
+===== 11. Manejo de múltiples XML =====
-Ejemplo:
-OK
-----
-**11. Manejo de múltiples XML**
-El consumidor debe considerar que:
   * El webhook puede recibir múltiples llamadas consecutivas.
@@ Línea 187: / Línea 106: @@
   * Debe implementar almacenamiento temporal o procesamiento en cola si espera grandes volúmenes.
-----
+===== 12. Consideraciones de seguridad =====
-**12. Consideraciones de seguridad**
-Se recomienda:
   * Utilizar HTTPS en el callback.
   * Validar el origen de las solicitudes.
-  * Implementar autenticación adicional si el ambiente lo requiere.
+  * Implementar autenticación adicional en la URL si el ambiente lo requiere.
   * Evitar almacenar XML sin controles de acceso.
-----
+===== 13. Resumen del flujo =====
-**13. Resumen del flujo**
-Cliente
-|
-| Solicitud descarga SAT
-|
-v
+<code>Cliente
+  |
+  | Solicitud descarga SAT (GET)
+  v
 IEngine Web Service
+  |
-|
+  | Consulta CFDI SAT
+  v
-| Consulta CFDI SAT
-|
-v
 XML encontrado
+  |
+  | POST webhook (N veces)
+  v
+Sistema consumidor (Procesa y almacena)
+</code>
+===== 14. Ejemplo completo =====
-|
+**Solicitud:**
-| POST webhook
-|
-v
-Sistema consumidor
-|
-| Procesa y almacena XML
-----
-**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:
+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
-Si existen 25 CFDI:
+**Resultado si existen 25 CFDI:**
-  * El webhook será invocado 25 veces.
+      * El webhook será invocado 25 veces de forma independiente.
   * Cada invocación recibirá:
-[
+<code>[
+    'xml' => '<cfdi:Comprobante ... > ... </cfdi:Comprobante>'
-'xml' => '<cfdi:Comprobante ... > ... </cfdi:Comprobante>'
 ]
+</code>
+===== 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. |
-**Tipos de comprobante CFDI soportados**
+**Ejemplos de uso rápidos:**
-El parámetro TipoComprobante permite indicar el tipo de CFDI que se desea consultar durante la descarga desde SAT.
+      * **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
-Los valores posibles corresponden al atributo TipoDeComprobante definido por el SAT:
+**Consideraciones adicionales:**
-^ \\ **Valor** \\    ^ \\ **Tipo de comprobante** \\    ^ \\ **Descripción** \\    |
+      * El valor enviado debe utilizar la letra correspondiente en mayúscula.
-| \\ 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**
-**Descargar CFDI de nómina**
-TipoComprobante=N
-Consulta únicamente CFDI de nómina.
-----
-**Descargar facturas emitidas**
-TipoComprobante=I
-Consulta comprobantes tipo ingreso.
-----
-**Descargar notas de crédito**
-TipoComprobante=E
-Consulta comprobantes tipo egreso.
-----
-**Descargar comprobantes de traslado**
-TipoComprobante=T
-Consulta CFDI tipo traslado.
-----
-**Descargar complementos de pago**
-TipoComprobante=P
-Consulta CFDI tipo pago.
-----
-**Consideraciones**
-  * 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 de TipoComprobante.
+  * Para descargar diferentes tipos de CFDI se debe realizar una solicitud independiente por cada valor.
-  * La cantidad de llamadas al webhook dependerá del número de XML encontrados para el tipo de comprobante solicitado.
 \\

iTimbre Wiki

Herramientas de usuario

Herramientas del sitio

Diferencias

Herramientas de la página