Ejemplo de integración CFDI en ecommerce

Una venta en línea puede quedar pagada en segundos, pero el CFDI puede tardar horas si pedido, datos fiscales, pago y timbrado viven en sistemas separados. Este ejemplo de integración CFDI en ecommerce muestra cómo diseñar una ruta trazable desde la confirmación comercial hasta el XML/PDF y la conciliación final, con controles para reintentos, devoluciones, errores y responsabilidades. La meta no es automatizar todo indiscriminadamente, sino eliminar recapturas sin perder revisión fiscal ni control operativo.

Problema operativo: el pedido avanza y el CFDI queda aislado

El ecommerce conoce el carrito, el importe cobrado y el estado de entrega. El sistema fiscal necesita identificar al emisor y receptor, recibir un XML correcto y conservar el resultado del timbrado. Inventarios, almacén, cobranza y contabilidad, por su parte, requieren saber qué movimiento corresponde a la misma operación. Cuando cada área trabaja con un folio diferente, la empresa termina conciliando por nombre, fecha o importe, señales que pueden repetirse.

La integración debe responder una pregunta sencilla: ¿cómo reconstruirá el equipo la historia completa de una venta cuando exista una aclaración? La respuesta necesita enlazar pedido, cliente, pago, surtido, solicitud de timbrado, UUID, XML/PDF y cualquier cancelación o devolución posterior. En este artículo el enfoque es ese recorrido y sus controles. La landing de integración CFDI para ecommerce concentra la propuesta comercial, mientras la guía de API de timbrado frente a captura manual ayuda a elegir el modelo de operación.

Datos y documentos que deben prepararse

Antes de programar, conviene acordar un diccionario de datos y señalar el sistema dueño de cada campo. El ecommerce puede dominar pedido, pago y envío; el ERP o una capa intermedia puede preparar la información fiscal; y el servicio de timbrado devuelve el resultado del comprobante. Esa división evita que dos aplicaciones intenten corregir al mismo tiempo el RFC, el precio, la existencia o el saldo.

• Identificador estable del pedido y referencia del canal, sin reutilizarlos para otra venta.
• Razón social emisora, sucursal o serie aplicable y credencial autorizada para esa empresa.
• Datos fiscales del receptor, uso requerido y evidencia de la solicitud de factura cuando corresponda al proceso.
• Conceptos, cantidades, precios, descuentos, moneda e impuestos definidos por la operación real.
• Estado y referencia del pago, además de las reglas para parcialidades, anticipos, crédito o reembolsos.
• Estado de surtido, entrega, devolución y cancelación comercial que deba relacionarse con el expediente.
• XML CFDI formado y sellado por el sistema externo cuando se utilice el contrato actual de la API.
• UUID, XML timbrado, PDF cuando aplique, código de respuesta y referencia de la solicitud.

La distinción sobre el XML es importante: el contrato documentado de timbrado recibe un CFDI ya formado y sellado. Si el proyecto pretende enviar sólo conceptos, clientes e impuestos para que otro componente construya el comprobante, ese alcance debe definirse y validarse por separado. No conviene ocultar una decisión fiscal dentro de una transformación técnica no documentada.

Flujo paso a paso: del pedido al CFDI conciliado

1. Mapear eventos y responsables. Define qué significa pedido creado, pago confirmado, listo para facturar, surtido, timbrado, entregado, devuelto y cancelado. Asigna qué sistema cambia cada estado.
2. Crear una referencia común. Conserva el folio de pedido como referencia externa durante todo el recorrido. No dependas del correo del comprador ni del total para localizar la transacción.
3. Separar venta de solicitud fiscal. Un pago aprobado no demuestra que los datos del receptor estén completos. Valida la información antes de preparar el XML y conserva la versión utilizada.
4. Aplicar la política de emisión. La empresa debe decidir en qué evento emite y cómo trata ventas al público en general, crédito, anticipos, parcialidades o devoluciones. El ecommerce sólo ejecuta la regla aprobada.
5. Formar y revisar el CFDI. El componente responsable arma y sella el XML, confirma emisor, receptor, conceptos, importes e impuestos, y evita mezclar pedidos o razones sociales.
6. Enviar con protección contra duplicados. Cada intento usa una clave de idempotencia estable para el mismo comprobante. Si hay timeout, el integrador consulta o reintenta con esa misma clave, en vez de crear otra solicitud.
7. Registrar el resultado. Guarda request_id, UUID, estado, XML timbrado y PDF cuando se solicite. Una respuesta incierta permanece pendiente de conciliación; no debe marcarse como fallo definitivo ni reenviarse a ciegas.
8. Actualizar los sistemas relacionados. El ecommerce muestra el estado útil para el cliente y conserva la referencia; administración relaciona el documento con pedido y pago; contabilidad recibe evidencia trazable.
9. Procesar excepciones y cierre. Devoluciones, cancelaciones, cambios y reembolsos siguen una ruta autorizada. Al cierre, un reporte compara pedidos facturables, solicitudes, UUID, XML y movimientos sin correspondencia.

Contrato técnico mínimo para reintentos y estados

Una integración confiable necesita más que una respuesta de éxito o error. Debe distinguir validación rechazada, solicitud recibida, timbrado confirmado, resultado pendiente y cancelación en proceso. El nombre interno de cada estado puede cambiar, pero su significado y la acción permitida deben quedar documentados. Así, soporte sabe si debe corregir datos, consultar una solicitud existente o escalar un rechazo.

La clave de idempotencia protege contra facturas duplicadas cuando la tienda repite una petición por pérdida de conexión. La referencia externa relaciona la solicitud con el pedido. El request_id permite consultar el resultado sin reconstruir la llamada original. Además, los registros técnicos deben conservar fecha, empresa, endpoint, código público y hash del XML sin exponer credenciales, certificados ni respuestas sensibles.

También conviene definir tiempos de espera y una cola de revisión. Un timeout no prueba que el timbrado haya fallado: el servicio pudo terminar después de que se cortó la respuesta. Antes de crear otro intento, la aplicación debe buscar el estado del request_id o reutilizar la misma clave. Este control separa una intermitencia técnica de un rechazo fiscal y evita que el operador tome decisiones con evidencia incompleta.

Caso práctico común: pago confirmado con surtido pendiente

Una comercializadora recibe un pedido desde su tienda en línea y la pasarela confirma el cobro. El almacén detecta que parte de la mercancía necesita revisión antes del envío. En lugar de timbrar automáticamente sólo porque existe un pago, el flujo mantiene el pedido en espera conforme a la política definida y muestra la excepción al responsable. El cliente no se recaptura y el equipo tampoco pierde la referencia del cobro.

Cuando surtido libera la operación, la capa responsable valida los datos fiscales, forma el XML y lo envía con la referencia del pedido y una clave de idempotencia. La respuesta devuelve el UUID y los archivos correspondientes; esos datos se relacionan con la venta. Si la conexión se interrumpe, el sistema consulta la misma solicitud antes de reintentar. Más adelante, una devolución conserva el vínculo con el pedido y el comprobante para que administración determine el documento y movimiento correctos.

El valor del ejemplo no está en fijar un momento universal para facturar. Está en que cada transición tiene una regla, un responsable y evidencia. La política concreta de emisión, cancelación o sustitución debe validarse con el contador o asesor fiscal de la empresa.

Errores comunes y sus consecuencias administrativas

• Usar una clave nueva en cada reintento. Puede generar solicitudes duplicadas ante una respuesta tardía.
• Tratar el pago como autorización fiscal. Envía operaciones con datos incompletos o en un momento no aprobado.
• Transmitir sólo el total del pedido. Impide revisar conceptos, descuentos, impuestos y diferencias posteriores.
• No guardar la relación entre pedido y UUID. Obliga a conciliar por coincidencias y dificulta atender aclaraciones.
• Mezclar credenciales o emisores. Expone a rechazos y a documentos asignados a la empresa equivocada.
• Interpretar un timeout como rechazo. Provoca reenvíos innecesarios y estados contradictorios.
• Cancelar sólo en la tienda. Deja el estado comercial separado del fiscal y del expediente documental.
• Conservar únicamente el PDF. Pierde el XML que sustenta el comprobante y limita validaciones posteriores.

Estas fallas elevan recapturas, facturas duplicadas, inventarios sin explicación, saldos mal relacionados y tickets de soporte difíciles de resolver. El remedio no es agregar más pantallas: es acordar identificadores, estados, dueños de datos y rutas de excepción antes de automatizar.

Cómo ayuda SOATI E-Factura® Plataforma Fiscal

SOATI E-Factura® Plataforma Fiscal ofrece un flujo de API para recibir XML CFDI desde un sistema externo, validar la empresa y el RFC autorizados, aplicar controles de idempotencia, solicitar el timbrado y devolver el XML o XML/PDF según la modalidad configurada. También contempla cancelación y consulta de estado SAT, capacidades útiles cuando el ecommerce necesita mantener actualizado el expediente después de la emisión.

La referencia externa y el request_id ayudan a conciliar pedido, solicitud y resultado sin reemplazar el sistema dueño de la venta. Cuando la empresa utiliza módulos de ventas, inventarios o cobranza dentro de SOATI E-Factura® Plataforma Fiscal, el alcance puede relacionarse conforme a su configuración y sus permisos; una integración por API no debe asumirse automáticamente como sustituto del ecommerce, ERP, pasarela o almacén.

Para revisar el alcance comercial consulta la landing de facturación conectada con tiendas en línea. Si quieres ubicar procesos complementarios de CFDI, ventas, inventarios, cobranza y control documental, visita el Centro de soluciones.

Checklist antes de liberar la integración

• Cada pedido conserva una referencia externa única y estable.
• Está documentado qué sistema domina cliente, productos, precios, impuestos, pago e inventario.
• La política de emisión fue aprobada para los escenarios reales del negocio.
• El XML se forma, sella y valida en el componente responsable antes del timbrado.
• Los reintentos reutilizan la misma clave de idempotencia para la misma operación.
• El integrador distingue rechazo, timeout, resultado pendiente y timbrado confirmado.
• Pedido, request_id, UUID, XML/PDF y pago pueden consultarse como una misma historia.
• Devoluciones, cancelaciones, sustituciones y reembolsos tienen ruta de excepción.
• Las credenciales y certificados no aparecen en logs ni respuestas para el usuario.
• Existe una conciliación periódica de pedidos facturables, comprobantes y diferencias.

Conecta una operación completa, no sólo una llamada

Empieza con un flujo representativo, incluye sus excepciones y prueba reintentos antes de ampliar canales o razones sociales. Con SOATI E-Factura® Plataforma Fiscal puedes Activar mis 5 timbres gratis o seleccionar Prueba el Sistema para revisar cómo integrar el timbrado con la operación digital de tu empresa.

Nota fiscal y técnica prudente

Este contenido tiene enfoque operativo y técnico; no sustituye asesoría fiscal, contable, legal ni de seguridad. El momento de emisión, los datos del CFDI, impuestos, cancelaciones, sustituciones y conservación documental deben validarse con los responsables profesionales y con la documentación oficial vigente. El contrato técnico final debe confirmarse para la configuración habilitada antes de desarrollar o liberar la integración.