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:31] |
web-service-descarga-masiva-sat [2026/07/07 20:51] (actual) |
||
|---|---|---|---|
| Línea 1: | Línea 1: | ||
| - | body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; color: #333; line-height: 1.6; } | ||
| - | h1, h2, h3 { color: #2c3e50; font-weight: 600; } | ||
| - | h1 { border-bottom: 3px solid #16a085; padding-bottom: 10px; margin-top: 20px; } | ||
| - | h2 { border-bottom: 1px solid #ddd; padding-bottom: 8px; margin-top: 30px; } | ||
| - | .endpoint-box { background-color: #ecf0f1; border-left: 5px solid #2980b9; padding: 15px; font-family: monospace; border-radius: 4px; word-break: break-all; } | ||
| - | .code-block { background-color: #282c34; color: #abb2bf; padding: 15px; border-radius: 6px; font-family: 'Courier New', Courier, monospace; overflow-x: auto; } | ||
| - | .table-thead-custom { background-color: #34495e; color: #fff; } | ||
| - | .badge-req { background-color: #e74c3c; color: white; padding: 4px 8px; border-radius: 4px; font-size: 0.8rem; } | ||
| - | .flow-step { background: #f8f9fa; border: 1px solid #e2e8f0; border-radius: 8px; padding: 15px; margin-bottom: 10px; } | ||
| - | |||
| ====== Web Service de Descarga de CFDI del SAT – IEngine ====== | ====== Web Service de Descarga de CFDI del SAT – IEngine ====== | ||
| Línea 29: | Línea 19: | ||
| **Ejemplo de estructura:** | **Ejemplo de estructura:** | ||
| - | https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php?\\ | + | 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 |
| - | engine=descagaSAT&\\ | + | |
| - | RfcEmisor=RFC&\\ | + | |
| - | TipoComprobante=N&\\ | + | |
| - | callback=webhookUrl&\\ | + | |
| - | fechaInicial=2025-10-22&\\ | + | |
| - | fechaFinal=2025-10-24 | + | |
| ===== 4. Parámetros de entrada ===== | ===== 4. Parámetros de entrada ===== | ||
| ^Parámetro ^Tipo ^Requerido ^Descripción | | ^Parámetro ^Tipo ^Requerido ^Descripción | | ||
| - | |**engine** |String | | + | |**engine** |String |Sí |Nombre del motor a ejecutar. Para descarga SAT debe enviarse descagaSAT. | |
| - | Sí | + | |**RfcEmisor** |String |Sí |RFC del emisor del cual se desean descargar comprobantes. | |
| - | |Nombre del motor a ejecutar. Para descarga SAT debe enviarse ''descagaSAT''. | | + | |**TipoComprobante** |String |Sí |Tipo de comprobante a consultar. Ejemplo: N para nómina. Ver catálogo al final. | |
| - | |**RfcEmisor** |String | | + | |**callback** |URL/String |Sí |Endpoint donde serán enviados los XML descargados. | |
| - | Sí | + | |**fechaInicial** |Date |Sí |Fecha inicial del rango de búsqueda. Formato: YYYY-MM-DD | |
| - | |RFC del emisor del cual se desean descargar comprobantes. | | + | |**fechaFinal** |Date |Sí |Fecha final del rango de búsqueda. Formato: YYYY-MM-DD | |
| - | |**TipoComprobante** |String | | + | |
| - | Sí | + | |
| - | |Tipo de comprobante a consultar. Ejemplo: ''N'' para nómina. Descubre más tipos al final de este documento. | | + | |
| - | |**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 ===== | + | ===== 5. Ejemplo de solicitud ===== |
| - | **Solicitud:** | + | **Solicitud (GET):** |
| - | 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 | 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 | ||
| Línea 70: | Línea 41: | ||
| 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: RFC del emisor, Tipo de comprobante, Periodo de consulta y URL del webhook receptor. | + | * El usuario realiza una petición al Web Service indicando: |
| - | - El servicio consulta los CFDI disponibles en el SAT. | + | * RFC del emisor. |
| - | - Por cada XML encontrado, el servicio realiza una llamada HTTP al webhook registrado. | + | * Tipo de comprobante. |
| - | - El webhook recibe el XML correspondiente de manera individual. | + | * Periodo de consulta. |
| - | - El proceso se repite de manera iterativa hasta enviar todos los XML encontrados. | + | * 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 ===== | ===== 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. | + | **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. |
| - | **Ejemplo:** Si el SAT devuelve 100 XML, el webhook será llamado 100 veces de forma secuencial y cada llamada contendrá un XML diferente. | + | **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 el siguiente parámetro mediante un método ''POST'': | + | El webhook recibe un parámetro vía POST: |
| ^Parámetro ^Tipo ^Descripción | | ^Parámetro ^Tipo ^Descripción | | ||
| - | |**xml** |String / XML |Contenido de texto completo del CFDI descargado. | | + | |**xml** |String/XML |Contenido completo del CFDI descargado. | |
| - | **Ejemplo de payload recibido (Estructura de arreglo):** | + | **Ejemplo de payload recibido:** |
| - | <code-block> | + | <code>[ |
| - | ''[ | + | |
| 'xml' => 'contenido_xml_del_cfdi' | 'xml' => 'contenido_xml_del_cfdi' | ||
| - | ]'' | + | ] |
| - | </code-block> | + | </code> |
| ===== 9. Ejemplo de recepción del webhook ===== | ===== 9. Ejemplo de recepción del webhook ===== | ||
| - | Ejemplo básico de implementación en **PHP**: | + | **Ejemplo en PHP:** |
| - | <code-block> | + | <code><?php |
| - | ''<?php | + | |
| $xml = $_POST['xml'] ?? null; | $xml = $_POST['xml'] ?? null; | ||
| if ($xml) { | if ($xml) { | ||
| - | + | // Procesar XML recibido | |
| - | // Procesar XML recibido (Guardar en disco, base de datos, etc.) | + | 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-block> | + | </code> |
| ===== 10. Recomendaciones para implementar el webhook ===== | ===== 10. Recomendaciones para implementar el webhook ===== | ||
| - | El endpoint receptor estructurado por el cliente debe cumplir con lo siguiente: | + | * 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. | ||
| - | * Aceptar solicitudes HTTP **POST**. | + | **Respuesta recomendada:** HTTP 200 OK (Cuerpo: OK) |
| - | * 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 ===== | ===== 11. Manejo de múltiples XML ===== | ||
| - | **Consideraciones importantes para el consumidor:** | + | * El webhook puede recibir múltiples llamadas consecutivas. |
| - | * El webhook puede recibir múltiples llamadas consecutivas en un lapso corto de tiempo. | + | * Cada llamada representa un CFDI independiente. |
| - | * Cada llamada representa un CFDI completamente independiente. | + | * No debe asumir que todos los XML llegarán en una sola petición. |
| - | * No debe asumir ni esperar que todos los XML llegarán empaquetados en una sola petición. | + | * Debe implementar almacenamiento temporal o procesamiento en cola si espera grandes volúmenes. |
| - | * 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 ===== | ===== 12. Consideraciones de seguridad ===== | ||
| - | * Utilizar obligatoriamente **HTTPS** en la URL del callback. | + | * Utilizar HTTPS en el callback. |
| - | * Validar el origen IP de las solicitudes si es posible. | + | * Validar el origen de las solicitudes. |
| - | * Implementar tokens de autenticación adicionales en la URL del webhook (Ej: ''?token=xyz123''). | + | * Implementar autenticación adicional en la URL si el ambiente lo requiere. |
| - | * Evitar almacenar los archivos XML expuestos públicamente en servidores web sin controles de acceso estrictos. | + | * Evitar almacenar XML sin controles de acceso. |
| ===== 13. Resumen del flujo ===== | ===== 13. Resumen del flujo ===== | ||
| - | <code-block text-center text-white font-monospace> | + | <code>Cliente |
| - | Cliente | + | | |
| - | | | + | | Solicitud descarga SAT (GET) |
| - | | (Solicitud descarga SAT via GET) | + | v |
| - | v | + | |
| IEngine Web Service | IEngine Web Service | ||
| - | | | + | | |
| - | | (Consulta y descarga CFDI SAT) | + | | Consulta CFDI SAT |
| - | v | + | v |
| - | XML Encontrado | + | XML encontrado |
| - | | | + | | |
| - | | (Llamada POST webhook N veces) | + | | POST webhook (N veces) |
| - | v | + | v |
| - | Sistema Consumidor | + | Sistema consumidor (Procesa y almacena) |
| - | | | + | </code> |
| - | | (Procesa, valida y almacena XML) | + | ===== 14. Ejemplo completo ===== |
| - | </code-block> | + | **Solicitud:** |
| - | ===== 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 | 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: | + | **Resultado si existen 25 CFDI:** |
| - | * El webhook del cliente será invocado de manera individual **25 veces**. | + | * El webhook será invocado 25 veces de forma independiente. |
| - | * Cada invocación recibirá un payload estructurado de la siguiente forma: | + | * Cada invocación recibirá: |
| - | + | ||
| - | <code-block> | + | |
| - | ''[ | + | |
| - | 'xml' => '<cfdi:Comprobante ...> ... </cfdi:Comprobante>' | + | |
| - | ]'' | + | |
| - | </code-block> | + | |
| + | <code>[ | ||
| + | 'xml' => '<cfdi:Comprobante ... > ... </cfdi:Comprobante>' | ||
| + | ] | ||
| + | </code> | ||
| ===== Tipos de comprobante CFDI soportados ===== | ===== 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: | + | 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. | | ||
| - | ^Valor ^Tipo de Comprobante ^Descripción Oficial | | + | **Ejemplos de uso rápidos:** |
| - | |**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 | ||
| - | * **Descargar CFDI de nómina:**''TipoComprobante=N'' | + | **Consideraciones adicionales:** |
| - | * **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**. | + | * El valor enviado debe utilizar la letra correspondiente en mayúscula. |
| - | * La consulta se realizará de manera exclusiva para el tipo de comprobante indicado. | + | * La consulta se realizará únicamente 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. | + | * Para descargar diferentes tipos de CFDI se debe realizar una solicitud independiente por cada valor. |
| \\ | \\ | ||
web-service-descarga-masiva-sat.1783456282.txt.gz · Última modificación: 2026/07/07 20:31 por
Herramientas de la página
