El problema
La tienda vendía en línea y alguien abría CloudInvoice, el ERP fiscal de la empresa, para cargar cada pedido manualmente. Además del tiempo perdido, era una fuente constante de errores: series fiscales cruzadas, almacenes incorrectos y familias de productos que no coincidían con el registro. Además, la misma empresa opera una tienda física, por lo que el documento debía emitirse aislado por serie, almacén y familia para no mezclar la contabilidad de ambos canales.
Lo que construí
Un Worker en Cloudflare, en TypeScript, entre Shopify y CloudInvoice:
- Escucha el webhook de pedido pagado de la tienda.
- Traduce el pedido al formato de documento fiscal, aplicando las reglas de serie, almacén y familia de la empresa.
- Crea clientes y productos bajo demanda cuando el pedido incluye datos que aún no existen en el registro, evitando fallos y cargas manuales previas.
- Deduce el stock en la misma operación.
- Emite el documento y devuelve el número generado.
Decisiones técnicas
Idempotencia ante todo. Los webhooks no se entregan exactamente una vez, sino al menos una vez. Sin una clave de idempotencia vinculada al pedido, un reenvío genera una factura duplicada, lo que en documentos fiscales es un problema contable grave. Cada pedido se registra antes de la emisión, y cualquier reintento devuelve el documento ya emitido en lugar de generar uno nuevo.
Worker en lugar de servidor dedicado. El volumen es variable, con picos en promociones y bajo tráfico el resto del tiempo. Al no usar servidores dedicados, no hay costos de máquinas ociosas ni servidores desactualizados. Escala automáticamente en los picos.
Modo de ensayo. Probar integraciones fiscales requiere rigor: un error aquí genera un documento legal que luego debe anularse manualmente. Por eso implementé un modo que recorre toda la cadena contra la empresa real, arma el documento, valida los totales y descarta el borrador al final sin emitir nada.
Fallo explícito y visible. Cuando CloudInvoice rechaza un documento, el error queda registrado con el pedido causante. Un endpoint de salud expone la última factura emitida y un monitor externo alerta por correo ante cualquier interrupción.
Resultado
Una integración robusta en producción que elimina el trabajo manual de facturación y garantiza 0% de discrepancia fiscal.