How to integrate PrestaShop with VeriFactu using native invoices and credit slips

Integrating PrestaShop with VeriFactu should not mean reconstructing an invoice from the cart or embedding XML, certificates or fiscal rules inside the ecommerce module. PrestaShop provides OrderInvoice for invoices and OrderSlip for credit slips, together with native PDF hooks. Puente VeriFactu connector 0.5.0 uses those capabilities as commercial sources, validates and reconciles amounts to cents, and delegates MappingProfile, classification and transport to a central engine. Automation is opt-in and compatibility is evaluated by capabilities, with an executed matrix covering 1.7.8.11, 8.1.7 and 8.2.7. This architecture reduces drift between stores, keeps secrets outside ecommerce and allows module upgrades without losing recordId, idempotency or state from previous operations.

1. Start with the documentary model PrestaShop already maintains

OrderInvoice contains an invoice representation with totals and breakdowns already produced by PrestaShop. The connector uses `getProductTaxesBreakdown()`, `getShippingTaxesBreakdown()` and `getWrappingTaxesBreakdown()` together with document totals. Recalculating VAT from cart lines would introduce differences around discounts, shipping or rounding that the platform has already resolved. Reusing the native invoice reduces parallel logic and makes it easier to compare what the customer sees with what is sent to preflight.

The current automatic flow requires one fiscal OrderInvoice per order. An order with multiple invoices is not resolved by selecting the first or adding them together; it blocks until an explicit strategy exists. This illustrates a useful integration rule: when the source system expresses documentary ambiguity, the adapter should surface it rather than inventing an answer just to keep automation running. Shop diagnosis therefore includes these cases before automatic hooks are enabled.

2. Taxes are grouped and reconciled to cents before issuance

An invoice may mix 21%, 10% and 4% rates together with shipping, wrapping and discounts. The extractor groups the breakdown by rate and compares taxable base, tax amount and totals against OrderInvoice. Additional fixture tests cover those three VAT rates, acceptable rounding and mismatches that must block. This gate prevents a material discrepancy from being hidden by a transformation and only appearing after a fiscal record has been created.

Ecotax or any concept requiring additional classification is not forced into a generic bucket either; it requires explicit mapping. When a store operates in multiple currencies, the commercial view is preserved while fiscal conversion is handled on the server rather than inside PrestaShop. The principle stays the same: the shop declares facts it can demonstrate and the fiscal engine decides how they map; when amounts cannot reconcile, preflight fails without fiscal side effects.

3. An OrderSlip is a corrective operation with independent identity

When PrestaShop creates a credit slip, `actionOrderSlipAdd` represents a native OrderSlip event. The connector converts it into a neutral payload with credit-slip identity, number and date, recipient, currency, reference to the original invoice and negative totals. Table `pvf_order_slip_sync` keeps one row per shop and OrderSlip, allowing several credits on the same order without overwriting state. The main invoice must already have a recordId before a corrective operation can be processed.

Fiscal classification is not inferred from the word 'credit slip'. A separate server-side corrective profile decides R1-R5, correction type and other rules. To determine historical VAT, the module retrieves the TaxCalculator from each original OrderDetail and compares observed tax amounts with that rate. It does not divide amount by base to guess a percentage. A later tax-configuration change therefore cannot silently alter how a return linked to an older sale is interpreted.

4. Invoice and credit slip share one rule: an existing recordId is never reissued

The ordinary invoice uses a stable key based on shop, order and invoice number; an OrderSlip uses a distinct identity based on shop, credit slip and corrective number. If a new operation encounters a recoverable failure before receiving recordId, the next attempt preserves exactly the same idempotency. Once recordId exists, both retryable and non-retryable errors preserve that identity and move into reconciliation or review rather than creating a new issuance.

This semantic contract is executed through Connector Contract Suite v2 for invoice and corrective operations inside the real matrix installations. A recoverable error may leave `retry_pending`, while a definitive failure becomes blocked, but both preserve what is already known about the operation. This reduces the risk that a timeout, network outage or module update turns into duplicate fiscal records. The local interface exposes the problem without changing the meaning of server state.

5. PrestaShop renders presentation while the server authors it

PrestaShop developer documentation provides dynamic PDF hooks such as `displayPDFInvoice` and `displayPDFOrderSlip`. Module 0.5.0 registers these points and consumes `presentation_json` persisted after issue or reconcile. That block contains metadata needed for URL, QR and wording associated with an operation. PrestaShop does not rebuild tax ID, consultation URL or regulatory text from local fields, avoiding a second source of truth for presentation.

The behavior is fail-closed. If recordId exists but presentation is unavailable or fails validation, the module does not invent a QR just to make the PDF look complete. Invoice and OrderSlip keep separate presentation because they are separate operations. Regenerating a PDF also does not trigger issuance. This separation between fiscal lifecycle and documentary rendering allows templates to change without modifying identity or transport contracts.

6. Capability-first evolution avoids promising versions that have not been tested

The distribution matrix covers three combinations: PrestaShop 1.7.8.11/PHP 7.4, 8.1.7/PHP 8.1 and 8.2.7/PHP 8.1. Each environment installs and activates the real ZIP, creates an invoice and OrderSlip and executes contract scenarios. The code does not use those version numbers to decide fiscal logic; a compatibility class detects available hooks and capabilities. The matrix is evidence, not a coded list of conditionals.

This approach allows versions outside the matrix to be evaluated without automatically claiming support. A concrete operation needs minimum capabilities such as usable PDF hooks and compatible native objects. If `displayPDFOrderSlip` is unavailable, for example, diagnosis may still recognize the shop and validate other data, but corrective issuance is not enabled. With PrestaShop 9 or future versions, the same rule requires specific validation before commercial compatibility is published.

7. Automatic hooks exist, while both switches start OFF

Invoices use an event after order-status changes, while credit slips use `actionOrderSlipAdd`. Installing the module does not mean those events are processed fiscally. Configuration maintains separate switches for Automatic invoices and Automatic corrective credit slips, both disabled by default. When invoice automation is enabled, the flow still requires exactly one OrderInvoice and reuses manual-mode preflight and idempotency. Credit slips use their own profile and prerequisites.

Gradual activation lets a team test one manual invoice, then one automatic invoice and finally an OrderSlip when the business uses returns. This order makes it easier to associate problems with configuration, data or hook timing. It also prevents an update from starting fiscal sending without a merchant decision. The validated 0.4.0-to-0.5.0 upgrade explicitly verifies that both switches remain OFF while new PDF presentation hooks are added.

8. A fiscal module upgrade must preserve local history, not only install files

The upgrade smoke keeps an already synchronized main invoice and corrective operation, deploys successive versions and requires recordId, idempotency and status to survive. Version 0.5.0 adds `presentation_json` and registers `displayPDFInvoice` and `displayPDFOrderSlip`. This test proves that expanding presentation does not require fiscal operations to be recreated. It also verifies that an update does not accidentally enable automation.

A real store adds more variables: overrides, checkout modules, multistore configuration, PDF customizations, tax modules and theme changes. The recommended procedure mirrors CI principles in staging: inventory, backup, upgrade, hook review, existing invoice, new invoice, OrderSlip and PDF. Only when that evidence is coherent should the module be considered ready. An application rollback must not erase or reinterpret existing fiscal records.

9. Certificates and fiscal classification remain outside PrestaShop

The token used by the module to call the Bridge is encrypted locally using a key derived from `_COOKIE_KEY_`, while the AEAT certificate and private key are never delivered to the store. They are not stored in synchronization tables either. This boundary limits the impact of an ecommerce compromise and allows fiscal credentials to be rotated or managed inside the specialized runtime. Logs and status cards use operational information rather than secrets.

The module also does not know sensitive fiscal decisions that vary by organization. `invoiceType`, R1-R5, S/I mode, taxCode, regimeKey, operationClass, issuer and fiscal currency-conversion criteria belong to MappingProfile and server-side configuration. A PrestaShop installation can be upgraded or cloned without embedding a complete fiscal policy in its code. The module remains an adapter, reducing the risk that two stores execute divergent versions of the same rules.

10. Go-live begins after technical validation, not at installation time

A shop can have the module installed, endpoint configured, accepted TEST invoices and correct PDF rendering without AEAT production being enabled. Separating readiness from production allows reversible work to finish while regulation, certificate, fiscal identity and authorization are reviewed. It also allows upgrades and hooks to be tested without affecting the production fiscal channel. Payment or commercial entitlement does not change that boundary.

Before go-live, the concrete version, capabilities, MappingProfile, token, certificate, selected automation, credit-slip handling, failure recovery, support and rollback are checked again. If the shop has changed modules since diagnosis, the relevant smoke is repeated. The goal is not merely to obtain one accepted response, but to leave a reproducible flow where invoice, corrective operation, PDF and status can be explained and reconciled without duplicate operations.