iTimbre Wiki

Esta página es de solo lectura. Puedes ver la fuente pero no puedes cambiarla. Pregunta a tu administrador si crees que esto es incorrecto.

<p> &lt;html><br/> &lt;head><br/> </p> <pre class="code">&lt;style>\\ .box-url { background-color: #f4f6f7; border-left: 4px solid #3498db; padding: 10px; font-family: monospace; font-size: 14px; margin-bottom: 15px; word-break: break-all; }\\ .box-code { background-color: #2c3e50; color: #ffffff; padding: 12px; border-radius: 4px; font-family: monospace; font-size: 14px; overflow-x: auto; margin-bottom: 15px; white-space: pre; }\\ table { width: 100%; border-collapse: collapse; margin-bottom: 20px; }\\ th, td { border: 1px solid #dddddd; padding: 8px; text-align: left; }\\ th { background-color: #f2f2f2; }\\ .alert-box { background-color: #e8f4f8; border-left: 4px solid #2980b9; padding: 10px; margin-bottom: 15px; }\\ &lt;/style>\\ </pre><p> </p> <p> &lt;/head><br/> &lt;body> </p> <pre class="code">&lt;h1>Web Service de Descarga de CFDI del SAT – IEngine&lt;/h1>\\ \\ &lt;h2>1. Introducción&lt;/h2>\\ &lt;p>El presente documento describe el uso del Web Service &lt;strong>IEngine – Descarga SAT&lt;/strong>, utilizado para solicitar la descarga de comprobantes fiscales digitales (CFDI) desde el SAT mediante los parámetros proporcionados.&lt;/p>\\ &lt;p>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.&lt;/p> </pre><p> </p> <pre class="code">&lt;h2>2. Endpoint del Servicio&lt;/h2>\\ &lt;p>&lt;strong>URL del Web Service:&lt;/strong>&lt;/p>\\ &lt;div class="box-url">https://pruebas-ifactura.itimbre.com/plugins/IEngine/IEngine.php&lt;/div> </pre><p> </p> <pre class="code">&lt;h2>3. Método de consumo&lt;/h2>\\ &lt;p>El servicio recibe parámetros mediante una solicitud &lt;strong>HTTP GET&lt;/strong>.&lt;/p>\\ &lt;p>&lt;strong>Ejemplo de estructura:&lt;/strong>&lt;/p>\\ &lt;div class="box-url">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&lt;/div> </pre><p> </p> <pre class="code">&lt;h2>4. Parámetros de entrada&lt;/h2>\\ &lt;table>\\ &lt;thead>\\ &lt;tr>\\ &lt;th>Parámetro&lt;/th>\\ &lt;th>Tipo&lt;/th>\\ &lt;th>Requerido&lt;/th>\\ &lt;th>Descripción&lt;/th>\\ &lt;/tr>\\ &lt;/thead>\\ &lt;tbody>\\ &lt;tr>\\ &lt;td>&lt;strong>engine&lt;/strong>&lt;/td>\\ &lt;td>String&lt;/td>\\ &lt;td>Sí&lt;/td>\\ &lt;td>Nombre del motor a ejecutar. Para descarga SAT debe enviarse descagaSAT.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>RfcEmisor&lt;/strong>&lt;/td>\\ &lt;td>String&lt;/td>\\ &lt;td>Sí&lt;/td>\\ &lt;td>RFC del emisor del cual se desean descargar comprobantes.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>TipoComprobante&lt;/strong>&lt;/td>\\ &lt;td>String&lt;/td>\\ &lt;td>Sí&lt;/td>\\ &lt;td>Tipo de comprobante a consultar. Ejemplo: N para nómina. Ver catálogo al final.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>callback&lt;/strong>&lt;/td>\\ &lt;td>URL/String&lt;/td>\\ &lt;td>Sí&lt;/td>\\ &lt;td>Endpoint donde serán enviados los XML descargados.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>fechaInicial&lt;/strong>&lt;/td>\\ &lt;td>Date&lt;/td>\\ &lt;td>Sí&lt;/td>\\ &lt;td>Fecha inicial del rango de búsqueda. Formato: YYYY-MM-DD&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>fechaFinal&lt;/strong>&lt;/td>\\ &lt;td>Date&lt;/td>\\ &lt;td>Sí&lt;/td>\\ &lt;td>Fecha final del rango de búsqueda. Formato: YYYY-MM-DD&lt;/td>\\ &lt;/tr>\\ &lt;/tbody>\\ &lt;/table> </pre><p> </p> <pre class="code">&lt;h2>5. Ejemplo de solicitud&lt;/h2>\\ &lt;p>&lt;strong>Solicitud (GET):&lt;/strong>&lt;/p>\\ &lt;div class="box-url">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&lt;/div> </pre><p> </p> <pre class="code">&lt;h2>6. Funcionamiento del servicio&lt;/h2>\\ &lt;p>El flujo de operación es el siguiente:&lt;/p>\\ &lt;ul>\\ &lt;li>El usuario realiza una petición al Web Service indicando:\\ &lt;ul>\\ &lt;li>RFC del emisor.&lt;/li>\\ &lt;li>Tipo de comprobante.&lt;/li>\\ &lt;li>Periodo de consulta.&lt;/li>\\ &lt;li>URL del webhook receptor.&lt;/li>\\ &lt;/ul>\\ &lt;/li>\\ &lt;li>El servicio consulta los CFDI disponibles en SAT.&lt;/li>\\ &lt;li>Por cada XML encontrado, el servicio realiza una llamada HTTP al webhook registrado.&lt;/li>\\ &lt;li>El webhook recibe el XML correspondiente.&lt;/li>\\ &lt;li>El proceso se repite hasta enviar todos los XML encontrados.&lt;/li>\\ &lt;/ul> </pre><p> </p> <pre class="code">&lt;h2>7. Webhook receptor&lt;/h2>\\ &lt;p>&lt;strong>Descripción:&lt;/strong> El webhook es un endpoint proporcionado por el usuario consumidor del servicio. Este endpoint será invocado &lt;strong>N veces&lt;/strong>, donde N corresponde al número de XML descargados.&lt;/p>\\ &lt;div class="alert-box">\\ &lt;strong>Nota:&lt;/strong> Si SAT devuelve 100 XML, el webhook será llamado 100 veces de forma individual y cada llamada contendrá un XML diferente.\\ &lt;/div> </pre><p> </p> <pre class="code">&lt;h2>8. Parámetros enviados al webhook&lt;/h2>\\ &lt;p>El webhook recibe un parámetro vía POST:&lt;/p>\\ &lt;table>\\ &lt;thead>\\ &lt;tr>\\ &lt;th>Parámetro&lt;/th>\\ &lt;th>Tipo&lt;/th>\\ &lt;th>Descripción&lt;/th>\\ &lt;/tr>\\ &lt;/thead>\\ &lt;tbody>\\ &lt;tr>\\ &lt;td>&lt;strong>xml&lt;/strong>&lt;/td>\\ &lt;td>String/XML&lt;/td>\\ &lt;td>Contenido completo del CFDI descargado.&lt;/td>\\ &lt;/tr>\\ &lt;/tbody>\\ &lt;/table> </pre><p> </p> <pre class="code">&lt;p>&lt;strong>Ejemplo de payload recibido:&lt;/strong>&lt;/p>\\ &lt;pre class="box-code">[\\ 'xml' => 'contenido_xml_del_cfdi'\\ </pre><p> </p> <p> ]&lt;/pre> </p> <pre class="code">&lt;h2>9. Ejemplo de recepción del webhook&lt;/h2>\\ &lt;p>&lt;strong>Ejemplo en PHP:&lt;/strong>&lt;/p>\\ &lt;pre class="box-code">&lt;?php </pre><p> </p> <p> $xml = $_POST['xml'] ?? null; </p> <p> if ($xml) {<br/> </p> <pre class="code">// Procesar XML recibido\\ file_put_contents('cfdi.xml', $xml);\\ echo "XML recibido correctamente";\\ </pre><p> </p> <p> } else {<br/> </p> <pre class="code">http_response_code(400);\\ echo "XML no recibido";\\ </pre><p> </p> <p> } </p> <p> ?&gt;&lt;/pre> </p> <pre class="code">&lt;h2>10. Recomendaciones para implementar el webhook&lt;/h2>\\ &lt;ul>\\ &lt;li>Aceptar solicitudes HTTP POST.&lt;/li>\\ &lt;li>Validar que el parámetro xml exista.&lt;/li>\\ &lt;li>Guardar o procesar el XML recibido.&lt;/li>\\ &lt;li>Responder rápidamente para evitar tiempos de espera (timeouts).&lt;/li>\\ &lt;li>Registrar errores de procesamiento.&lt;/li>\\ &lt;/ul>\\ &lt;p>&lt;strong>Respuesta recomendada:&lt;/strong> HTTP 200 OK (Cuerpo: OK)&lt;/p> </pre><p> </p> <pre class="code">&lt;h2>11. Manejo de múltiples XML&lt;/h2>\\ &lt;ul>\\ &lt;li>El webhook puede recibir múltiples llamadas consecutivas.&lt;/li>\\ &lt;li>Cada llamada representa un CFDI independiente.&lt;/li>\\ &lt;li>No debe asumir que todos los XML llegarán en una sola petición.&lt;/li>\\ &lt;li>Debe implementar almacenamiento temporal o procesamiento en cola si espera grandes volúmenes.&lt;/li>\\ &lt;/ul> </pre><p> </p> <pre class="code">&lt;h2>12. Consideraciones de seguridad&lt;/h2>\\ &lt;ul>\\ &lt;li>Utilizar HTTPS en el callback.&lt;/li>\\ &lt;li>Validar el origen de las solicitudes.&lt;/li>\\ &lt;li>Implementar autenticación adicional en la URL si el ambiente lo requiere.&lt;/li>\\ &lt;li>Evitar almacenar XML sin controles de acceso.&lt;/li>\\ &lt;/ul> </pre><p> </p> <pre class="code">&lt;h2>13. Resumen del flujo&lt;/h2>\\ &lt;pre class="box-code">Cliente\\ </pre><p> </p> <p> |<br/> </p> <span class='np_break'> </span> <div class="table"><table class="inline"> <tr class="row0"> </tr> </table> <span class='np_break'> </span> </div> <p> v<br/> IEngine Web Service<br/> </p> <span class='np_break'> </span> <div class="table"><table class="inline"> <tr class="row0"> </tr> <tr class="row1"> </tr> </table> <span class='np_break'> </span> </div> <p> v<br/> XML encontrado<br/> </p> <span class='np_break'> </span> <div class="table"><table class="inline"> <tr class="row0"> </tr> <tr class="row1"> </tr> </table> <span class='np_break'> </span> </div> <p> v<br/> Sistema consumidor (Procesa y almacena)&lt;/pre> </p> <pre class="code">&lt;h2>14. Ejemplo completo&lt;/h2>\\ &lt;p>&lt;strong>Solicitud:&lt;/strong>&lt;/p>\\ &lt;div class="box-url">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&lt;/div> </pre><p> </p> <pre class="code">&lt;p>&lt;strong>Resultado si existen 25 CFDI:&lt;/strong>&lt;/p>\\ &lt;ul>\\ &lt;li>El webhook será invocado 25 veces de forma independiente.&lt;/li>\\ &lt;li>Cada invocación recibirá:&lt;/li>\\ &lt;/ul>\\ &lt;pre class="box-code">[\\ 'xml' => '&lt;cfdi:Comprobante ... &gt; ... &lt;/cfdi:Comprobante&gt;'\\ </pre><p> </p> <p> ]&lt;/pre> </p> <pre class="code">&lt;h2>Tipos de comprobante CFDI soportados&lt;/h2>\\ &lt;p>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:&lt;/p> </pre><p> </p> <pre class="code">&lt;table>\\ &lt;thead>\\ &lt;tr>\\ &lt;th>Valor&lt;/th>\\ &lt;th>Tipo de comprobante&lt;/th>\\ &lt;th>Descripción&lt;/th>\\ &lt;/tr>\\ &lt;/thead>\\ &lt;tbody>\\ &lt;tr>\\ &lt;td>&lt;strong>I&lt;/strong>&lt;/td>\\ &lt;td>Ingreso&lt;/td>\\ &lt;td>Comprobantes emitidos por la prestación de servicios, venta de productos, arrendamientos u operaciones donde existe un ingreso.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>E&lt;/strong>&lt;/td>\\ &lt;td>Egreso&lt;/td>\\ &lt;td>Comprobantes utilizados para devoluciones, descuentos, bonificaciones o ajustes relacionados con ingresos previamente registrados.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>T&lt;/strong>&lt;/td>\\ &lt;td>Traslado&lt;/td>\\ &lt;td>Comprobantes utilizados para acreditar el transporte o traslado de mercancías.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>N&lt;/strong>&lt;/td>\\ &lt;td>Nómina&lt;/td>\\ &lt;td>Comprobantes fiscales digitales utilizados para registrar pagos de salarios y prestaciones a trabajadores.&lt;/td>\\ &lt;/tr>\\ &lt;tr>\\ &lt;td>&lt;strong>P&lt;/strong>&lt;/td>\\ &lt;td>Pago&lt;/td>\\ &lt;td>Comprobantes utilizados para registrar la recepción de pagos relacionados con operaciones previamente facturadas.&lt;/td>\\ &lt;/tr>\\ &lt;/tbody>\\ &lt;/table> </pre><p> </p> <pre class="code">&lt;p>&lt;strong>Ejemplos de uso rápidos:&lt;/strong>&lt;/p>\\ &lt;ul>\\ &lt;li>&lt;strong>Descargar CFDI de nómina:&lt;/strong> TipoComprobante=N&lt;/li>\\ &lt;li>&lt;strong>Descargar facturas emitidas:&lt;/strong> TipoComprobante=I&lt;/li>\\ &lt;li>&lt;strong>Descargar notas de crédito:&lt;/strong> TipoComprobante=E&lt;/li>\\ &lt;li>&lt;strong>Descargar comprobantes de traslado:&lt;/strong> TipoComprobante=T&lt;/li>\\ &lt;li>&lt;strong>Descargar complementos de pago:&lt;/strong> TipoComprobante=P&lt;/li>\\ &lt;/ul> </pre><p> </p> <pre class="code">&lt;p>&lt;strong>Consideraciones adicionales:&lt;/strong>&lt;/p>\\ &lt;ul>\\ &lt;li>El valor enviado debe utilizar la letra correspondiente en mayúscula.&lt;/li>\\ &lt;li>La consulta se realizará únicamente para el tipo de comprobante indicado.&lt;/li>\\ &lt;li>Para descargar diferentes tipos de CFDI se debe realizar una solicitud independiente por cada valor.&lt;/li>\\ &lt;/ul> </pre><p> </p> <p> &lt;/body><br/> &lt;/html> </p>