Herramientas de usuario
web-service-descarga-masiva-sat
Diferencias
Muestra las diferencias entre dos versiones de la página.
| Ambos lados, revisión anterior Revisión previa Próxima revisión | Revisión previa | ||
|
web-service-descarga-masiva-sat [2026/07/07 20:41] |
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 ====== | ====== Web Service de Descarga de CFDI del SAT – IEngine ====== | ||
| - | ==== 1. Introducción ====\\ | + | ===== 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 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. | 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:**\\ | + | |
| - | <code>https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php</code> | + | **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 de estructura:** |
| - | <code>\\ | + | |
| - | 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\\ | + | |
| - | </code> | + | |
| - | ==== 4. Parámetros de entrada ====\\ | + | 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 |
| - | ^ 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 ====\\ | + | ===== 4. Parámetros de entrada ===== |
| - | **Solicitud (GET):**\\ | + | |
| - | <code>\\ | + | ^Parámetro ^Tipo ^Requerido ^Descripción | |
| - | 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\\ | + | |**engine** |String |Sí |Nombre del motor a ejecutar. Para descarga SAT debe enviarse descagaSAT. | |
| - | </code> | + | |**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 ===== | ||
| - | ==== 6. Funcionamiento del servicio ====\\ | ||
| El flujo de operación es el siguiente: | 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.\\ | + | * RFC del emisor. |
| - | - Tipo de comprobante.\\ | + | * Tipo de comprobante. |
| - | - Periodo de consulta.\\ | + | * Periodo de consulta. |
| - | - URL del webhook receptor.\\ | + | * 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 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. ::: | + | **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 ===== | ||
| - | ==== 8. Parámetros enviados al webhook ====\\ | ||
| El webhook recibe un parámetro vía POST: | El webhook recibe un parámetro vía POST: | ||
| - | ^ Parámetro ^ Tipo ^ Descripción ^\\ | + | ^Parámetro ^Tipo ^Descripción | |
| - | | **xml** | String/XML | Contenido completo del CFDI descargado. | | + | |**xml** |String/XML |Contenido completo del CFDI descargado. | |
| - | **Ejemplo de payload recibido:**\\ | + | **Ejemplo de payload recibido:** |
| - | <code php>\\ | + | |
| - | [\\ | + | <code>[ |
| - | 'xml' => 'contenido_xml_del_cfdi'\\ | + | 'xml' => 'contenido_xml_del_cfdi' |
| - | ]\\ | + | ] |
| </code> | </code> | ||
| + | ===== 9. Ejemplo de recepción del webhook ===== | ||
| + | |||
| + | **Ejemplo en PHP:** | ||
| - | ==== 9. Ejemplo de recepción del webhook ====\\ | + | <code><?php |
| - | **Ejemplo en PHP:**\\ | + | |
| - | <code php>\\ | + | |
| - | <?php | + | |
| $xml = $_POST['xml'] ?? null; | $xml = $_POST['xml'] ?? null; | ||
| - | if ($xml) {\\ | + | if ($xml) { |
| - | // Procesar XML recibido\\ | + | // Procesar XML recibido |
| - | file_put_contents('cfdi.xml', $xml);\\ | + | file_put_contents('cfdi.xml', $xml); |
| - | echo "XML recibido correctamente";\\ | + | echo "XML recibido correctamente"; |
| - | } else {\\ | + | } else { |
| - | http_response_code(400);\\ | + | http_response_code(400); |
| - | echo "XML no recibido";\\ | + | echo "XML no recibido"; |
| } | } | ||
| - | ?>\\ | + | ?> |
| </code> | </code> | ||
| + | ===== 10. Recomendaciones para implementar el webhook ===== | ||
| - | ==== 10. Recomendaciones para implementar el webhook ====\\ | + | * Aceptar solicitudes HTTP POST. |
| - | El endpoint receptor debe:\\ | + | * Validar que el parámetro xml exista. |
| - | * Aceptar solicitudes HTTP POST.\\ | + | * Guardar o procesar el XML recibido. |
| - | * Validar que el parámetro xml exista.\\ | + | * Responder rápidamente para evitar tiempos de espera (timeouts). |
| - | * Guardar o procesar el XML recibido.\\ | + | * Registrar errores de procesamiento. |
| - | * Responder rápidamente para evitar tiempos de espera (timeouts).\\ | + | |
| - | * Registrar errores de procesamiento. | + | |
| - | **Respuesta recomendada:** %%HTTP 200 OK%% (Cuerpo: %%OK%%) | + | **Respuesta recomendada:** HTTP 200 OK (Cuerpo: OK) |
| - | ==== 11. Manejo de múltiples XML ====\\ | + | ===== 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 ====\\ | + | * El webhook puede recibir múltiples llamadas consecutivas. |
| - | * Utilizar HTTPS en el callback.\\ | + | * Cada llamada representa un CFDI independiente. |
| - | * Validar el origen de las solicitudes.\\ | + | * No debe asumir que todos los XML llegarán en una sola petición. |
| - | * Implementar autenticación adicional en la URL si el ambiente lo requiere.\\ | + | * Debe implementar almacenamiento temporal o procesamiento en cola si espera grandes volúmenes. |
| - | * Evitar almacenar XML sin controles de acceso. | + | |
| - | ==== 13. Resumen del flujo ====\\ | + | ===== 12. Consideraciones de seguridad ===== |
| - | <code>\\ | + | |
| - | 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)\\ | + | |
| - | </code> | + | |
| - | ==== 14. Ejemplo completo ====\\ | + | * Utilizar HTTPS en el callback. |
| - | **Solicitud:**\\ | + | * Validar el origen de las solicitudes. |
| - | <code>\\ | + | * Implementar autenticación adicional en la URL si el ambiente lo requiere. |
| - | 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\\ | + | * Evitar almacenar XML sin controles de acceso. |
| + | |||
| + | ===== 13. Resumen del flujo ===== | ||
| + | |||
| + | <code>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) | ||
| </code> | </code> | ||
| + | ===== 14. Ejemplo completo ===== | ||
| - | **Resultado si existen 25 CFDI:**\\ | + | **Solicitud:** |
| - | * El webhook será invocado 25 veces de forma independiente.\\ | + | |
| - | * Cada invocación recibirá:\\ | + | 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 |
| - | <code php>\\ | + | |
| - | [\\ | + | **Resultado si existen 25 CFDI:** |
| - | 'xml' => '<cfdi:Comprobante ... > ... </cfdi:Comprobante>'\\ | + | |
| - | ]\\ | + | * El webhook será invocado 25 veces de forma independiente. |
| + | * Cada invocación recibirá: | ||
| + | |||
| + | <code>[ | ||
| + | 'xml' => '<cfdi:Comprobante ... > ... </cfdi:Comprobante>' | ||
| + | ] | ||
| </code> | </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. | | ||
| + | |||
| + | **Ejemplos de uso rápidos:** | ||
| - | ==== Tipos de comprobante CFDI soportados ====\\ | + | * **Descargar CFDI de nómina:** TipoComprobante=N |
| - | 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: | + | * **Descargar facturas emitidas:** TipoComprobante=I |
| + | * **Descargar notas de crédito:** TipoComprobante=E | ||
| + | * **Descargar comprobantes de traslado:** TipoComprobante=T | ||
| + | * **Descargar complementos de pago:** TipoComprobante=P | ||
| - | ^ Valor ^ Tipo de comprobante ^ Descripción ^\\ | + | **Consideraciones adicionales:** |
| - | | **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:**\\ | + | * El valor enviado debe utilizar la letra correspondiente en mayúscula. |
| - | * **Descargar CFDI de nómina:** %%TipoComprobante=N%%\\ | + | * La consulta se realizará únicamente para el tipo de comprobante indicado. |
| - | * **Descargar facturas emitidas:** %%TipoComprobante=I%%\\ | + | * Para descargar diferentes tipos de CFDI se debe realizar una solicitud independiente por cada valor. |
| - | * **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. | + | |
web-service-descarga-masiva-sat.1783456861.txt.gz · Última modificación: 2026/07/07 20:41 por
Herramientas de la página
