Checks 1 al 3: Validar datos fiscales, campos del checkout y lógica de pagos

Antes de integrar, resolvé estos tres puntos: perfil fiscal, datos del checkout y regla de emisión. Si esa base no está bien armada, la integración se rompe.

Check 1: Confirmar el perfil fiscal y el catálogo impositivo de productos

Sin CUIT activo y clave fiscal nivel 3 o superior, la integración no puede emitir comprobantes.

También conviene separar el punto de venta web del manual y usar uno habilitado para Factura Electrónica por Web Services. Ese número va a figurar en cada comprobante que emita la tienda, así que no es un dato menor.

La condición fiscal del emisor define qué comprobantes puede sacar el sistema. Un Responsable Inscripto emite Facturas A y B. Un Monotributista emite Facturas C. Esa regla tiene que quedar configurada en la app de facturación desde el arranque.

Después viene el catálogo. Cada SKU necesita tener bien marcado si está gravado o exento, qué alícuota de IVA le corresponde - 21%, 10,5%, 27% o exento - y, si aplica, su clasificación para exportación. En Shopify, esto se puede resolver con metafields de producto. Por ejemplo, afip.tax_rate para el mercado local.

Con el perfil fiscal listo, el paso siguiente es pedir y guardar bien esos datos en el checkout.

Check 2: Confirmar que el checkout recolecta CUIT, condición fiscal y datos de facturación

Shopify no pide CUIT ni condición fiscal de forma nativa. Por eso, hay que cargar CUIT, condición fiscal y datos de facturación en metafields, atributos de carrito o extensiones de checkout.

Para emitir un comprobante válido ante AFIP, necesitás estos datos:

• razón social
• CUIT/CUIL/DNI
• condición fiscal
• dirección de facturación
• email
• estado de pago

Hay un detalle práctico que suele pasarse por alto. AFIP indica que, cuando el monto del comprobante supera los $21.505, se deben informar nombre, domicilio e identificación del comprador. En otras palabras, no alcanza con cobrar y seguir. Conviene validar el formato del CUIT en tiempo real y hacer que los datos de facturación queden completos antes de cerrar la compra.

Con esos campos resueltos, falta definir el momento exacto de emisión según cómo entra el pago.

Check 3: Definir las reglas de emisión según el flujo de pago

Definí cuándo se emite según el medio de pago. Este punto tiene que quedar acordado por el equipo antes de configurar los webhooks. Si no, aparecen errores clásicos: facturas emitidas antes de tiempo, operaciones duplicadas o notas de crédito que se podrían haber evitado.

La idea es simple: el sistema tiene que emitir cuando el pago está efectivamente confirmado, no antes. Ese criterio evita bastante ruido operativo.

Checks 4 y 5: Construir la capa de integración con webhooks y mapeo de datos

Con la regla de emisión ya resuelta, el trabajo ahora es más concreto: convertir cada evento de Shopify en un comprobante válido.

Check 4: Elegir y proteger los webhooks correctos

Los eventos clave son orders/create, orders/paid, orders/updated, refunds/create y orders/cancelled. Si el costo de envío impacta el comprobante, también incluí el evento de envío correspondiente.

El flujo de procesamiento tiene que ser uno solo y sin vueltas: verificá la firma HMAC-SHA256 que Shopify manda en X-Shopify-Hmac-SHA256, guardá el payload crudo, respondé 200 enseguida y dejá la lógica fiscal para un worker asíncrono. Si la firma no coincide, respondé 401 y no procesés el evento. La verificación de firma tiene que hacerse con comparación en tiempo constante.

Para evitar comprobantes duplicados, usá X-Shopify-Webhook-Id como clave de idempotencia y guardá los IDs procesados durante al menos 72 horas. También conviene sumar logging estructurado con topic, dominio de la tienda, order ID, webhook ID y resultado. Y si ves picos de errores o crecimiento en la cola de fallos, activá alertas.

Con los webhooks bajo control, el paso siguiente es traducir cada pedido al esquema fiscal.

Check 5: Mapear los campos del pedido al esquema de la e-factura

Tomá el CUIT y la condición fiscal desde los campos personalizados que ya cargaste en el checkout. La lógica del tipo de comprobante sale del cruce entre la condición fiscal del emisor y la del receptor. Ese cruce define si emitís Factura A, B o C, y también cómo tratás el IVA. Los tax_lines del pedido son la base para armar el desglose de alícuotas que exige AFIP.

Los descuentos, tanto a nivel de ítem como de orden, tienen que verse reflejados en los totales. Si no, importe_gravado e importe_iva no van a cerrar contra lo que se cobró de verdad.

Para una Nota de Crédito, guardá el número de factura original y el CAE desde el mismo momento en que se emite el comprobante.

Con el mapeo cerrado, pasá a devoluciones, notas de crédito y pruebas end-to-end. Para escalar estas operaciones, podés apoyarte en un cerebro de comercio inteligente que orqueste tus automatizaciones.

Checks 6 y 7: Devoluciones, pruebas end-to-end y monitoreo de errores

Check 6: Definir las reglas para devoluciones, reembolsos y notas de crédito

Con el mapeo ya cerrado, toca meterse en una de las partes más delicadas: devoluciones, reembolsos y notas de crédito.

Cada devolución o ajuste de base imponible pide una nota de crédito vinculada a la factura original, con su número, punto de venta y CAE.

Hay un detalle que no se puede pasar por alto: solo el emisor original puede emitir la nota de crédito. Si la tienda opera con más de un CUIT o más de un punto de venta, la integración tiene que mandar cada NC al emisor que corresponda.

Para que eso salga bien, conviene guardar en los metafields de Shopify - o en la base de datos de la integración - estos datos desde el momento en que se emite cada factura: tipo de comprobante (A/B/C), punto de venta, número de factura, CAE y condición frente al IVA del cliente.

Check 7: Probar escenarios reales y monitorear fallas después del lanzamiento

Con las reglas de devolución ya definidas, el siguiente paso es probar el circuito completo antes de pasar a producción.

Armá un plan de pruebas con datos reales en ARS, medios de pago locales y condiciones fiscales comunes en Argentina. Probar solo el caso ideal no alcanza. También hay que revisar qué pasa cuando algo falla, porque ahí es donde suelen aparecer los problemas más caros.

Ya en producción, el monitoreo tiene que mirar tres capas.

• Webhooks: Shopify reintenta entregas fallidas hasta 8 veces en 4 horas y puede eliminar de forma automática la suscripción después de 8 fallos consecutivos. Activá alertas si la tasa de éxito en 24 horas baja de 99,5% o si la dead-letter queue tiene eventos sin drenar por más de una hora.
• Errores de generación de facturas: logueá el código de error de AFIP, el CUIT, el tipo de comprobante y el monto. Si se pasa un umbral definido, escalalo a finanzas.
• Brechas de conciliación: armá un reporte diario o semanal que muestre pagos sin factura y facturas sin pago en ARS. Eso sirve para chequear que Shopify, las presentaciones ante AFIP y la contabilidad interna estén alineados.

Si este control falla, el problema no siempre aparece en el momento. A veces explota días después, cuando alguien intenta conciliar cobros, revisar IVA o emitir una nota de crédito y descubre que falta el dato más simple de todos: la referencia a la factura original.

Conclusión: Controles mínimos antes de activar e-invoicing en Shopify

Con la lógica fiscal y técnica ya definida, falta un último paso: cerrar el control operativo antes de pasar a producción. Dejás por escrito, en una sola fuente de verdad versionada, las reglas de emisión, impuestos, pagos y devoluciones.

También conviene dejar la localización cerrada antes del alta. Eso incluye:

• ARS con formato local
• Fechas en DD/MM/AAAA
• Zona horaria America/Argentina/Buenos_Aires
• Validación de CUIT, CUIL o DNI

Con esa base, el riesgo baja y el alta queda lista para producción. Si alguno de los siete puntos sigue ambiguo, la integración no está lista para producción.

FAQs

¿Qué pasa si facturo antes de confirmar el pago?

Facturar antes de confirmar el pago puede traer desajustes contables y líos en la operación del día a día. Lo más conveniente es emitir el comprobante solo cuando la transacción ya esté liquidada de forma efectiva, por ejemplo, a partir de eventos como order.paid.

Si no esperás esa confirmación, los reportes financieros pueden perder precisión. Y además, las devoluciones o cancelaciones se vuelven más engorrosas de manejar. Para evitar ese problema, configurá la emisión fiscal después de verificar el estado del pago.

¿Qué datos del checkout tengo que pedir sí o sí?

Para integrar bien el e-invoicing y cumplir con la normativa en Argentina, en el checkout tenés que pedir y validar los datos necesarios para emitir facturas electrónicas ante ARCA (ex AFIP).

Sí o sí, solicitá la identificación fiscal del cliente: CUIT, CUIL o DNI, según su condición frente al IVA. Validar esos datos te evita errores y te permite emitir comprobantes con los requisitos legales, como el CAE y el código QR.

¿Cómo evito facturas duplicadas con webhooks de Shopify?

Implementá idempotencia en tu sistema: como los webhooks de Shopify pueden llegar más de una vez, verificá si el ID del pedido ya se procesó antes de emitir un comprobante nuevo.

Dicho simple: si Shopify manda el mismo evento dos veces, tu sistema no debería facturar dos veces. La forma más directa de evitarlo es guardar el ID del pedido y chequearlo antes de generar cualquier transacción.

Además, podés sumar un polling cada 6 a 12 horas para detectar eventos perdidos o inconsistencias. Eso te da una segunda capa de control, algo así como una red de seguridad por si un webhook no llegó o falló en el camino.

También conviene usar una cola de mensajes fallidos para registrar errores sin repetir transacciones. Así, cuando algo sale mal, no perdés el rastro del problema ni corrés el riesgo de volver a emitir un comprobante por accidente.