How to move Excel or CSV invoices to VeriFactu without turning the spreadsheet into fiscal software

Excel and CSV remain a practical invoicing source for many small businesses, professional firms and internal operations. The problem is not the format itself but how to turn a mutable table into a safe, traceable and resumable process. If an application simply read the workbook and issued row by row immediately, a mapping error, a crash halfway through the file or a double click could create outcomes that are hard to reconstruct. Kairoseth Fiscal separates the path into stages: input bytes, parsing, temporary session, mapping, preflight, explicit confirmation, durable batch, lease, idempotent issuance and status export. The original binary is not persisted. In production, temporary sessions and confirmed batches use MongoDB stores injected by Kairoseth, preserving the agreed Hostinger + MongoDB infrastructure while keeping the fiscal core decoupled from database credentials.

1. Why upload-and-issue in one step is a bad architecture

A spreadsheet is an editable artifact. It may contain shifted columns, formulas, empty rows, several date formats, locale-specific decimal separators and fields understood only by one person in the company. If the first button after selecting a file were issuance, the system would have to assume too much. Even a familiar template can change after a new version, a different export or a user inserting a column for internal control. The first layer should observe and explain the file before side effects are possible.

Separating inspection, preflight and confirmation turns the process into a verifiable conversation. The user can see which sheet and headers were detected, which columns have strong mapping, which ones need review and which rows fail the contract. Only afterwards is an issuable intent frozen. This order also makes it safe to repeat analysis during onboarding without fear that a test creates records. For a small business, that interaction safety is as important as the API that eventually processes the batch.

2. Parsing creates a temporary session, not a permanent fiscal file archive

The inspection endpoint receives bytes and creates a temporary session containing what the workflow needs next: importId, organization and installation context, parsed rows, headers, sheet metadata and Mapping Assistant output. In Kairoseth production that session lives in MongoDB with TTL. The core receives no MongoClient, URI or password; the infrastructure layer injects an already resolved collection interface. This boundary avoids coupling Puente VeriFactu to infrastructure details and protects database credentials.

The original binary is discarded. Buffer, XLSX/CSV bytes and rawBody are not retained as part of the contract. This policy reduces duplicated data and makes later stages depend on an explicit structured representation. For the user it means the platform is not trying to become a document archive. If the original Excel file must be retained for internal records, it stays in the normal business system; Kairoseth keeps only what is needed for mapping, validation and confirmed execution.

3. Mapping Assistant adapts known headers and forces ambiguous matches to be reviewed

A template can name the same concept in many different ways. Mapping Assistant proposes matches with confidence levels and only automates strong matches. Suggestions in review state require explicit confirmation. Manual overrides are limited to known contract destinations and the core rejects dangerous paths such as prototype, constructor or __proto__. This protects against both accidental errors and structures designed to alter objects during transformation.

The output is a reusable MappingProfile draft. The business does not need to rename the workbook to adopt internal engine field names. Mapping still does not grant the source authority over tenant, certificates, permissions, sensitive classification or environment; those stay server-side. Missing essential fields and pending fixed configuration are also detected. A good profile should explain where every value comes from and which values are configuration, not merely make a row pass by coincidence.

4. Preflight runs before and during confirmation so stale state cannot be issued

Users can run preflight as many times as needed while correcting the file or mapping. This phase creates no records. When they finally confirm, the backend runs preflight again. A batch is created only if every required row is still valid. That intentional repetition closes the gap between an earlier validation and the current authorization, preventing a profile or session change from making stale data issuable.

Repeated confirmation of the same content returns the same deterministic batch. There is no legacy route that can issue directly from an unconfirmed session; that operation returns a confirmation-required conflict. The contract therefore does not depend on a UI hiding a button because the server itself prevents bypassing the gate. This defense matters when other clients or future integrations call the import API without using the same visual interface.

5. Confirmation freezes InvoiceIntent and idempotency row by row

Every confirmed row internally stores its row number, frozen InvoiceIntent, Idempotency-Key, status, minimal result and attempt counter. The key follows the importId:row:n pattern. The client never receives the frozen intent because its purpose is to guarantee that retries use exactly the same intent that was validated and confirmed. If the original workbook changes afterwards, the authorized batch does not change; different data requires a new session and confirmation.

This design gives a much more precise recovery unit than the entire file. One row can be issued, another pending and another failed without losing the identity of each operation. It also makes it possible to demonstrate that a retried operation corresponds to the same confirmed content. Users can see a simple batch with row states while freezing and idempotency remain backend concerns that can be tested and audited.

6. The lease prevents concurrent workers and makes crash recovery possible

The issue endpoint acquires an atomic lease before processing. This prevents two workers from running the same batch concurrently. As rows complete, the lease is renewed. If the process dies, the lease expires and another worker can continue. Rows are not deleted or reset merely because the process handling them disappeared. Durable state distinguishes what was confirmed, what was issued and what still needs retry.

The critical scenario is a crash between bridge.issue() and persistence of the local result. The row may already have been processed remotely even though the worker did not store the response. Recovery keeps the same Idempotency-Key, so the core returns the same resource instead of creating another one. That property is why the key is frozen before processing begins rather than generated again for each attempt.

7. Status and export should reconcile the batch rather than replicate all fiscal data

GET /v1/import-batches/{batchId} returns sanitized row status and results. Batch states show whether the batch is confirmed, processing, partial or completed. Rows already issued are skipped during recovery, and only pending rows or retryable failures are attempted again. A row error is reduced to code, status and retryable so remote messages or XML containing unnecessary or sensitive information are not persisted.

JSON or CSV export contains row, status, recordId, duplicate, fiscalStatus, errorCode, retryable and attempts. This lets the business compare the result with the original workbook using row numbers without returning the full content in the evidence file. The source spreadsheet or ERP remains the business record while export acts as an operational processing receipt rather than a new master invoicing database.

8. In Kairoseth production, MongoDB makes the workflow durable inside the agreed infrastructure

Kairoseth injects two stores: importSessionStore for the temporary TTL session and importBatchStore for the durable confirmed batch. They must be configured together; a mixed Mongo-session/in-memory-batch configuration fails closed. Tenant + installation indexes maintain isolation and TTL removes temporary sessions when they are no longer needed. This implementation respects the Kairoseth Platform infrastructure decision: Hostinger + MongoDB for the product without introducing PostgreSQL as a platform dependency.

SQLite or memory remain standalone and development profiles, but they do not replace Kairoseth production persistence. Keeping that distinction documented prevents a local demo from accidentally becoming production architecture. The fiscal core consumes store interfaces and does not need to know the Mongo URI, which allows alternative stores in tests without changing the contract exposed to the web application.

9. A technically correct batch still does not equal enabled AEAT production

A business can have stable mapping, green preflight, durable batches and tested recovery before being authorized for go-live. That is an advantage: technical preparation can be completed and repeated in TEST without exposing the production certificate or turning internal training into a real submission. The production gate separately reviews identity, certificate, configuration, current regulation, evidence and authorization. No Excel validation should bypass that boundary.

The Spanish Tax Agency publishes SIF/VERI*FACTU technical and regulatory information and BOE maintains the applicable legal framework. Because deadlines and specifications may evolve, Kairoseth re-checks official sources before production. Editorial content should explain the process and technology without presenting the importer as an official certification. The correct promise is controlled adaptation of existing data, not turning a spreadsheet into an automatic license to send.