Cómo pasar facturas de Excel o CSV a VeriFactu sin convertir la hoja en un sistema fiscal

Excel y CSV son una realidad en la facturación de muchas pequeñas empresas, despachos y operaciones internas. El problema no es el formato en sí, sino cómo convertir una tabla mutable en un proceso seguro, trazable y reanudable. Si una aplicación leyera la hoja y emitiera fila por fila de inmediato, un error de mapping, una caída a mitad de lote o un doble clic podría tener consecuencias difíciles de reconstruir. Kairoseth Fiscal separa el recorrido en fases: bytes de entrada, parseo, sesión temporal, mapping, preflight, confirmación explícita, batch durable, lease, emisión idempotente y export de estado. El binario original no se persiste. En producción, las sesiones temporales y los batches confirmados utilizan stores MongoDB inyectados por Kairoseth, manteniendo la infraestructura acordada de Hostinger + MongoDB y dejando el core fiscal desacoplado del cliente de base de datos.

1. Por qué subir y emitir en el mismo paso es una mala arquitectura

Una hoja de cálculo es un artefacto editable. Puede tener columnas desplazadas, fórmulas, filas vacías, fechas en distintos formatos, importes con separadores regionales y campos que solo una persona de la empresa entiende. Si el primer botón después de seleccionar el fichero fuera emitir, el sistema tendría que asumir demasiado. Incluso una plantilla aparentemente conocida puede cambiar por una nueva versión, una exportación distinta o un usuario que inserta una columna para control interno. La primera capa debe observar y explicar el archivo antes de permitir efectos.

Separar inspección, preflight y confirmación convierte el proceso en una conversación verificable. El usuario ve qué hoja y cabeceras se han detectado, qué columnas tienen mapping fuerte, cuáles necesitan revisión y qué filas no cumplen el contrato. Solo después se congela una intención emitible. Este orden también permite repetir el análisis durante onboarding sin miedo a que una prueba cree registros. Para una pyme, esa seguridad de interacción es tan importante como la API interna que termina procesando el lote.

2. Parsear el archivo crea una sesión temporal, no un archivo fiscal permanente

El endpoint de inspección recibe bytes y crea una sesión temporal con lo necesario para seguir trabajando: importId, contexto de organización e instalación, filas parseadas, cabeceras, metadata de hoja y resultado del asistente de mapping. En Kairoseth productivo esa sesión vive en MongoDB con TTL. El core no recibe MongoClient, URI ni contraseña; la capa de infraestructura inyecta una interfaz de colección ya resuelta. Esta frontera evita acoplar Puente VeriFactu a detalles de infraestructura y protege credenciales de base de datos.

El binario original se descarta. No se conserva Buffer, bytes XLSX/CSV ni rawBody como parte del contrato. Esta política reduce duplicación de datos y obliga a que el flujo posterior dependa de una representación estructurada explícita. Para el usuario significa que la plataforma no pretende convertirse en su repositorio documental. Si necesita conservar el Excel original para archivo interno, lo mantiene en su sistema habitual; Kairoseth conserva únicamente la información necesaria para mapping, validación y ejecución confirmada.

3. Mapping Assistant adapta cabeceras conocidas y obliga a revisar la ambigüedad

Una plantilla puede llamar a un mismo concepto de muchas maneras. El asistente propone equivalencias con niveles de confianza y solo automatiza coincidencias fuertes. Las propuestas en estado review necesitan confirmación explícita. Los overrides manuales se limitan a destinos conocidos del contrato y el core rechaza rutas peligrosas como prototype, constructor o __proto__. Esto protege tanto contra errores accidentales como contra estructuras diseñadas para alterar objetos durante la transformación.

El resultado es un borrador de MappingProfile reutilizable. La empresa no tiene que renombrar su hoja para adoptar los nombres internos del motor. Sin embargo, mapping no resuelve decisiones que el origen no debe tomar: tenant, certificado, permisos, clasificación sensible y entorno permanecen server-side. También se detectan campos esenciales o configuración fija pendiente. Un buen perfil debe explicar de dónde sale cada dato y qué valores son configuración, no solo conseguir que una fila pase validación por casualidad.

4. Preflight se ejecuta antes y durante la confirmación para evitar emitir un estado obsoleto

El usuario puede ejecutar preflight tantas veces como necesite mientras corrige el archivo o el mapping. Esta fase no crea registros. Cuando finalmente pulsa confirmar, el backend vuelve a ejecutar preflight. Solo si todas las filas requeridas siguen siendo válidas se crea el batch. Esta repetición intencionada cierra la ventana entre una validación anterior y la autorización actual, y evita que un cambio de perfil o sesión convierta en emitible algo que ya no cumple.

La confirmación repetida del mismo contenido devuelve el mismo batch determinista. No existe una ruta legacy que permita emitir directamente desde una sesión no confirmada: esa operación responde con conflicto de confirmación requerida. Así el contrato no depende de que la interfaz esconda un botón; el servidor mismo impide saltarse el gate. Esta defensa es especialmente importante cuando en el futuro otros clientes o integraciones utilicen la API de importación sin pasar por la misma UI.

5. Confirmar congela InvoiceIntent e idempotencia fila por fila

Cada fila confirmada guarda internamente el número de fila, InvoiceIntent congelado, Idempotency-Key, estado, resultado mínimo y contador de intentos. La clave sigue el patrón importId:row:n. El cliente no recibe el intent congelado, porque su función es garantizar que los reintentos utilicen exactamente la misma intención que fue validada y confirmada. Si la hoja original se modifica después, eso no cambia el batch ya autorizado; para procesar datos distintos debe existir una nueva sesión y confirmación.

Este diseño proporciona una unidad de recuperación mucho más precisa que el archivo completo. Una fila puede estar emitida, otra pendiente y otra en error sin perder la identidad de cada una. También permite demostrar que una operación reintentada corresponde al mismo contenido confirmado. Para el usuario, el concepto puede presentarse de forma simple como un lote con filas y estados; la complejidad de congelación e idempotencia permanece en el backend, donde puede probarse y auditarse.

6. El lease evita dos workers concurrentes y hace posible la recuperación tras una caída

El endpoint de issue adquiere un lease atómico antes de procesar. Eso evita que dos workers ejecuten simultáneamente el mismo batch. Conforme se completan filas, el lease se renueva. Si el proceso muere, el lease expira y otro worker puede continuar. No se borran ni reinician las filas por el simple hecho de perder el proceso que las estaba trabajando. El estado durable permite distinguir qué quedó confirmado, qué fue emitido y qué necesita retry.

El escenario crítico es una caída entre bridge.issue() y la persistencia local del resultado. En ese caso la fila podría haber sido procesada remotamente aunque el worker no haya guardado la respuesta. La reanudación mantiene la misma Idempotency-Key. El core devuelve el mismo recurso en lugar de crear otro. Esa propiedad es la razón por la que la clave se congela antes de empezar el procesamiento y no se genera de nuevo en cada intento.

7. Estado y export deben servir para conciliar el lote, no para replicar todos los datos fiscales

GET /v1/import-batches/{batchId} devuelve estado y resultados sanitizados por fila. Los estados del batch permiten saber si está confirmado, procesándose, parcial o completado. Las filas ya emitidas se omiten al reanudar y solo se vuelven a intentar las pendientes o fallos retryable. Un error de fila se reduce a código, status y retryable, evitando persistir mensajes remotos o XML que puedan contener información innecesaria o sensible.

El export JSON o CSV contiene row, status, recordId, duplicate, fiscalStatus, errorCode, retryable y attempts. Eso permite comparar el resultado con la hoja original usando el número de fila sin devolver el contenido completo al descargar evidencia. Esta separación es útil para control interno: la empresa mantiene sus datos de negocio en la hoja o ERP y utiliza el export como recibo operativo de procesamiento, no como nueva fuente maestra de facturación.

8. En Kairoseth productivo, MongoDB hace durable el flujo sin salir de la infraestructura acordada

Kairoseth inyecta dos stores: importSessionStore para la sesión temporal con TTL e importBatchStore para el batch confirmado durable. Deben configurarse juntos; una mezcla de sesión Mongo y batch en memoria falla cerrada. Los índices tenant + installation sostienen el aislamiento y TTL elimina sesiones temporales cuando dejan de ser necesarias. Esta implementación respeta la decisión de infraestructura de Kairoseth Platform: Hostinger + MongoDB para el producto, sin introducir PostgreSQL como dependencia de plataforma.

SQLite o memoria siguen siendo perfiles standalone y de desarrollo, pero no sustituyen la persistencia productiva Kairoseth. Mantener esta diferencia documentada evita que una demo local se convierta accidentalmente en arquitectura productiva. El core fiscal consume interfaces de store y no necesita conocer la URI Mongo, lo que permite probar el comportamiento con stores alternativos sin modificar el contrato que verá la aplicación web.

9. Un batch técnicamente correcto sigue sin equivaler a producción AEAT habilitada

Una empresa puede tener mapping consolidado, preflight verde, batch durable y recuperación probada antes de estar autorizada para un go-live. Esa es una ventaja: la preparación técnica puede completarse y repetirse en TEST sin exponer certificado productivo ni convertir una formación interna en un envío real. El gate de producción revisa por separado identidad, certificado, configuración, normativa vigente, evidencia y autorización. Ninguna validación de Excel debe saltarse esa frontera.

La AEAT publica la información técnica y normativa de SIF/VERI*FACTU y el BOE mantiene el marco legal aplicable. Como el calendario y las especificaciones pueden evolucionar, Kairoseth vuelve a revisar fuentes oficiales antes de producción. El contenido editorial debe explicar el proceso y la tecnología sin presentar el importador como una certificación oficial. Para el usuario final, la promesa correcta es poder adaptar sus datos existentes de forma controlada, no convertir una hoja de cálculo en una licencia automática para enviar.