How to integrate VeriFactu with ERP, ecommerce and custom software without creating fiscal technical debt

VeriFactu introduces requirements affecting computerized invoicing systems in Spain, but the technical response should not be to add isolated calls to every application that emits an invoice. That strategy works in a demonstration and becomes fragile when multiple channels, corrections, network failures, imports, version changes and audit needs appear. The alternative is to treat adaptation as an architecture problem: define a boundary between the business system and the fiscal layer, use a common data contract, validate before producing effects, record states and preserve enough evidence to reconstruct what happened. This approach does not replace the regulatory analysis appropriate to each company; it organizes technical implementation so obligations can be applied in a controlled way. Kairoseth Fiscal follows this pattern to connect WooCommerce, PrestaShop, ERP, CRM, spreadsheets and custom software without requiring every source to understand the details of fiscal transport.

1. Start with the data model, not the endpoint

The first task is to describe what an invoicing operation means inside the company. Teams need to identify issuer, recipient when applicable, series, number, date, line items, taxable bases, taxes, totals, currency, references and relationships with previous operations when a correction exists. Operational context matters too: which system created the record, which event made it invoiceable and which identifier will find it months later. A canonical contract prevents every connector from inventing names and behavior. A WooCommerce adapter can translate a paid order into the contract; an ERP adapter can start from a posted invoice; an import can read a validated row. All of them deliver an equivalent structure to the core. This model should be versioned. When a rule changes or a new field appears, the platform can evolve explicitly instead of silently breaking older connectors. Stability of the internal contract is one of the strongest defenses against fiscal technical debt.

2. Define exactly when the fiscal operation is created

In ecommerce, the technically easiest event to capture is not always the correct one. Creating an order, authorizing payment, capturing it, marking it complete or issuing an invoice are different moments. Integration needs to follow the company's real process rather than a hook chosen for convenience. It also needs a policy for cancellations, partial refunds and changes made after issuance. The same principle applies in ERP systems: saving a draft does not necessarily mean posting or issuing it. The rule should be documented per connector and tested with scenarios. A transition table helps specify which states can create an operation, which are ignored and which produce a correction or human review. This precision reduces two opposite risks: submitting information too early while it can still change, or failing to submit an operation because the expected event never occurred. Good design turns the commercial flow into explicit, observable fiscal decisions.

3. Validate before execution and explain errors

Validation should happen as close as possible to the fiscal boundary. A connector can check basic source requirements, but the core needs to apply common rules to avoid differences between channels. A useful error identifies the field, reason and possible action; a generic error forces operators into logs and increases resolution time. Data, configuration, authentication, connectivity and external-response failures should be separated. The first categories often require human correction or a source-system change; temporary failures may allow retries; definitive failures should stop automation. This taxonomy also improves metrics because the company can see whether problems originate in incomplete data, a specific connector or external availability. Pre-execution validation should be deterministic and repeatable so the same payload produces the same diagnosis while rules remain unchanged. If the core transforms data, that transformation needs documentation; it should never silently fill fiscal information it does not actually know.

4. Design idempotent retries from day one

Partial failures are inevitable. A request can leave the server while its response is lost; a process can restart; an operator can click again; a queue can deliver the same message more than once. Without idempotency, each case can create duplicates or leave the team unsure which state is real. The solution starts with a stable key derived from the identity of the source operation and an internal processing record. Before producing an effect, the core checks whether the operation was already accepted, definitively rejected or remains pending. If state is uncertain, it should neither assume success nor retry blindly; it should enter reconciliation. Retries need limits, progressive delay where appropriate and an intervention queue for cases that cannot be resolved automatically. This discipline matters more than speed. A fiscal platform that processes thousands of operations quickly but cannot demonstrate what it did with a repeated operation is operationally weaker than one that prioritizes consistency.

5. Preserve useful evidence without turning logs into a dumping ground

Traceability does not mean indiscriminately storing every byte forever. Evidence should answer concrete questions: which operation was processed, from which system, with which connector and core version, when its state changed, what the result was and which reference links it to the source. Sensitive data should be limited according to necessity and retention policy. It is also useful to distinguish operational evidence from diagnostic logs. The former belongs to the history used for audit and reconciliation; the latter supports incident investigation and can have a different lifecycle. Correlation identifiers let teams follow an operation across components without copying full information into every message. When a correction exists, its relationship to the previous operation should remain explicit. An operations interface should support searches by order reference, invoice or internal identifier and reconstruct the sequence. This capability dramatically reduces support cost and avoids dependence on the person who originally implemented the connector.

6. Reconciliation checks the whole system, not just transport

A health check showing that an endpoint responds does not prove that every invoice was processed correctly. Reconciliation starts with sets: which operations should exist according to the source during a period, and which operations are known by the fiscal layer. Differences are classified as legitimate pending items, errors, operations intentionally ignored by rule, potential duplicates or states requiring investigation. This process can run periodically and on demand after an incident. For ecommerce, teams can compare orders that reached the fiscal event with processed records; for ERP, issued invoices from included series; for imports, accepted rows against results. The goal is not blind equality but an explanation for every difference. Good reconciliation produces an actionable list and closure evidence. It also measures coverage and detects regressions after a plugin or rule update. When this capability exists by design, recovering from an outage stops being a bespoke investigation and becomes a repeatable procedure.

7. Deploy in phases and preserve a safe exit

Deployment should reduce technical and operational risk at the same time. First, document the current flow and build the connector without changing production behavior. Then run synthetic cases and controlled samples, including invalid data and deliberate failures. The next phase enables a pilot limited by organization, series, channel or volume. During the pilot, results are compared with the source system and the amount of manual work is measured. Coverage expands only with that evidence. Every phase needs exit and rollback criteria. Stopping transport should not destroy data or prevent commercial operations from being recorded; a controlled queue can preserve pending work while an incident is resolved. After service recovery, reconciliation determines what should be retried. For companies in Barcelona, Catalonia and the rest of Spain, this approach adapts existing processes without duplicating pages or architectures by geography. In European organizations, the Spanish implementation should remain a clearly bounded jurisdictional module inside a broader platform.