How to integrate an ERP with VeriFactu by API without duplicating fiscal logic inside the source system

A common mistake when adapting an ERP to a new fiscal requirement is trying to turn the ERP itself into the complete implementation of the regulation. It looks direct initially but multiplies dependencies: the source becomes coupled to XML, certificates, transport, validation rules, remote states and regulatory evolution. Kairoseth Fiscal uses a different boundary: ERP, CRM or custom software keeps the commercial facts it already governs, while Puente VeriFactu centralizes the fiscal contract, validation, idempotency, reconciliation and supported transport. API v1 accepts both canonical InvoiceIntent and mapped source payloads, includes signed webhook ingress and belongs to a capability-first matrix where API is preferred but not mandatory. That makes it possible to adapt both modern and legacy systems without maintaining a separate fiscal engine for every vendor.

1. Define the boundary: the ERP knows the business and the bridge knows the fiscal contract

The source system is usually authoritative for invoice series and number, issue date, customer, products or services, discounts, currency and calculated taxes. Those facts need to come from a stable, traceable source. The bridge should not invent them when missing, and the ERP should not take on responsibilities belonging to the fiscal layer. Puente VeriFactu keeps tenant, certificate, AEAT environment, permissions, sensitive fiscal classification, hashes, chaining and transport outside the source. This boundary reduces the risk that a regulatory update requires modifications across dozens of ERP installations.

The same architecture prevents every integration from becoming a completely separate project. API, webhook, file, Local Agent or native connector paths all end by producing the same InvoiceIntent and running through the same preflight. The adapter changes because the ingress capability changes, while the fiscal core remains the same. This matters for companies with several systems: ecommerce may use a native connector, a subsidiary may use ERP REST and a legacy application may use read-only database access, yet all share status, idempotency and presentation semantics.

2. Decide whether to send canonical InvoiceIntent or keep the ERP's existing JSON

The API supports a canonical mode for teams that want to construct InvoiceIntent v1 directly. It is useful when the software is custom, the model is well documented and the development team can control the transformation with tests. Monetary amounts travel as exact decimal strings to avoid binary floating-point errors and the contract preserves stable source identity. The client does not select organizationId, installationId or sourceSystem through the payload: those values come from authenticated credentials and any client-supplied equivalent is not authoritative.

The second mode is mapped. The ERP can keep sending fields using its historical vocabulary while the request references a profileId. MappingProfile translates approved source paths into the canonical contract, can supply fixed configuration and remains versioned server-side. This often reduces changes in third-party software because the source does not have to rebuild its internal structures. The choice should not be based on convenience alone: server-managed mapping improves governance, while strongly typed custom software may prefer the canonical contract to detect errors even before calling the API.

3. Use preflight as a quality gate before any fiscal side effect

POST /v1/preflight exists to separate validation from issuance. A new integration should start with anonymized real samples, test number and date, recipient, taxable bases, tax amounts, currency and configuration, and correct failures without creating fiscal records. Mapped mode uses the same profile that will be applied during issuance, which validates not only the raw payload but the complete transformation. A failed preflight should be visible and actionable; hiding it behind automatic defaults only moves the problem into a more expensive stage.

The gate also supports a safer rollout strategy. First validate one operation manually, then repeat with relevant invoice and corrective cases, test expected failures and automate only afterwards. The ERP team can build alerts around structured errors without understanding internal AEAT transport details. Separating commercial data from mapping clarifies ownership: a missing tax ID is corrected at the source, incomplete server-side classification is corrected in configuration, and a timeout is handled as a transport incident.

4. Design the Idempotency-Key before automating the first send

POST /v1/fiscal-records requires an Idempotency-Key because enterprise integrations must assume requests will be repeated. An ERP may retry after a timeout, a worker may restart and a queue may deliver the same event more than once. The key should derive from stable operation identity and remain unchanged across every retry of the same intent. The API scopes idempotency by organization, installation and key; the same key with the same content returns the same resource, while different content produces a conflict instead of silently reusing the wrong identity.

Fiscal idempotency also exists at invoice/source identity level. That layered defense supports recovery even when an HTTP reservation was left pending by a process crash. The operational rule for the integrator stays simple: a new operation keeps its key; when the server returns recordId, persist that recordId. From then on, a network or synchronization failure must not create a new identity. The client queries the existing resource, records correlationId and applies retry policy to lookup or reconciliation when appropriate.

5. Separate creation, status and errors so reconciliation is actually possible

GET /v1/fiscal-records/{recordId} returns normalized state without secrets and respects the authenticated tenant. If a resource belongs to another organization, the API behaves as if it were not found so its existence is not leaked. This lookup should become a normal part of the lifecycle rather than a support-only tool. An ERP that stores recordId can refresh status after an interruption, rebuild an operational tracking screen or resume a queue without repeating the creation process.

Errors use a stable structure with code, message, retryable, correlationId and sanitized details. retryable lets a worker decide whether to try again or require human correction. correlationId links client observability to runtime observability without exposing XML/SOAP or secrets. For reporting, the ERP can retain sourceInvoiceId, recordId, normalized state and the last error code. That set is enough to operate the integration without turning the customer database into a copy of the internal fiscal layer.

6. Use webhook when the source can emit events but does not need a full REST integration

POST /v1/webhooks/{profileId} provides a low-code route for CRM, SaaS or automation tools that can send HTTP when an invoice is produced. The body is protected with HMAC-SHA256 over timestamp and raw body, with an anti-replay window and stable event identity. profileId and secret are resolved on the server, and the event cannot choose tenant, certificate or environment. Security does not depend on hiding a URL; it depends on authenticating the event and limiting which mapping each installation may execute.

Webhook ingress enters the same pipeline as API: mapping, preflight, idempotency, creation and status lookup. Using a webhook therefore does not mean giving up control. A duplicated event must preserve the same identity, one outside the replay window is rejected and an incomplete payload is blocked. In low-code integrations it is also important to restrict which fields non-technical users can edit, because configuration convenience is not fiscal authority. Sensitive classification stays server-side even when the event itself is built through a visual automation tool.

7. For legacy ERP, choose the smallest adapter that can extract data without invading the system

Not every ERP can send HTTP or expose REST. The universal matrix includes read-only Local Agent database access for PostgreSQL, MySQL/MariaDB and SQL Server. The agent uses a configurable query or view, durable checkpoints and outbound HTTPS connections; by default it does not write into the ERP database. For systems that export files there are watch-folder and read-only, non-destructive SFTP routes. These adapters handle transport, discovery and checkpoints but still go through MappingProfile and do not contain their own AEAT rules.

CSV/XLSX covers the simplest case: the company exports a file, the system inspects its structure, proposes mapping, runs preflight, requires explicit confirmation and creates a durable batch. A row already issued is never issued again, and recovery after a failure preserves the same idempotency key. A universal manual flow remains the final fallback for microbusinesses or systems without a practical technical interface. The advantage is that an ERP limitation changes the selected adapter rather than forcing a different fiscal engine or a migration away from business software.

8. Keep secrets server-side and separate TEST from AEAT production

Integration can be developed without placing certificates or fiscal keys inside the ERP. Connector credentials are used server-to-server and authenticated context determines organization, installation and source. The client does not select a certificate through JSON and should never receive passphrases, raw AEAT XML or fiscal administration permissions. This model limits the impact of a breach in the source system and simplifies credential rotation. It also lets a partner implement an adapter against a documented contract without unnecessary access to sensitive material.

The recommended rollout goes through diagnosis, mapping, preflight, idempotency tests, failure scenarios and TEST before production is considered. The Spanish Tax Agency maintains a dedicated portal for invoicing software systems and VERI*FACTU with technical and regulatory information, while the baseline framework comes from Royal Decree 1007/2023 and its implementing rules. Because deadlines and specifications may evolve, the production gate must review current official sources at go-live. A technical release or commercial contract does not replace that review and is not an official certification.

9. Implementation checklist: what must be resolved before automation

Before enabling an automatic worker, the team should be able to answer several questions precisely: which event means an invoice has been issued, what its stable identity is, where number and date come from, how recipient and taxes are represented, how corrective operations behave, which currency the source uses, which fields are mandatory and which fallback route exists. Then document MappingProfile, create installation-scoped credentials and verify that preflight detects both valid cases and intentionally invalid ones. A test that proves only the happy path misses the failures most likely to cause duplicates.

The second test block should force retries: same Idempotency-Key with the same content, conflict with changed content, timeout after creation, lookup by recordId, retryable failure and non-retryable validation failure. Observability and support should also be verified: correlationId available, understandable states, secrets absent from logs and a recovery runbook. Automation is justified only when the system can explain what happened after an interruption. Integration speed matters, but for fiscal operations the ability to reconstruct identity and state matters more.