DfProforma Shopware — Preventivi pro forma con accettazione cliente e auto-conversione

Cosa fa DfProforma

Shopware 6.7 sa emettere fatture, DDT e note di credito — ma non preventivi pro forma. Eppure, in quasi tutti i contesti B2B (attrezzature industriali, servizi alle aziende, appalti pubblici, vendite per gara d’appalto), il cliente deve ricevere un documento formale che accetta prima che l’ordine diventi vincolante.

DfProforma colma questa lacuna senza espedienti: un vero tipo di documento Shopware nativo df_proforma, un proprio range di numerazione PF{n}, un template PDF Twig brandizzato, un workflow di accettazione cliente autonomo con URL pubblica firmata HMAC-SHA256, e una conversione automatica in ordine vincolante non appena la transazione sottostante passa allo stato pagato.

Requisiti

• Shopware 6.7.0 o superiore (il plugin non è retrocompatibile con 6.6 a causa del refactoring del sistema di documenti)
• PHP 8.2 minimo
• MySQL 8.0+ o MariaDB 10.6+
• Message worker Shopware attivi (raccomandato per la gestione automatica delle scadenze)
• Mail Service Shopware configurato (SMTP funzionante per gli invii transazionali)

Installazione

1. Caricare il plugin

Dall’amministrazione Shopware, andate in Estensioni → Le mie estensioni → Carica estensione, e selezionate il file DfProforma-1.0.6.zip.

2. Installare e attivare

Nell’elenco delle estensioni, cliccate Installa e poi Attiva. Le migrazioni Shopware si eseguono automaticamente e creano:

• La tabella SQL df_proforma con i suoi indici su order_id, status, public_token
• Il tipo di documento df_proforma in document_type
• Il range di numerazione document_df_proforma nel formato PF{n} configurabile
• Il template email transazionale base per generazione, invio e accettazione

3. Ricompilare l’amministrazione

Il plugin fornisce un modulo Vite admin che estende la scheda ordine (sw-order-detail-base). Bisogna ricompilare il bundle di amministrazione globale affinché il tab Pro forma appaia:

bin/build-administration.sh
bin/console cache:clear

Configurazione

Impostazioni globali

Da Estensioni → Le mie estensioni → DfProforma → Configura, accedete alle seguenti impostazioni:

• Validità di default — Numero di giorni durante i quali il link di accettazione rimane valido (30 di default). Ogni preventivo può sovrascrivere questo valore individualmente.
• Auto-conversione al pagamento — Attivata di default. Disattivatela se volete conservare il controllo manuale della transizione Accettato → Convertito.
• Nome del mittente — Nome mostrato come mittente delle email transazionali (di default: il nome del sales-channel).
• Colore brand del PDF — Colore accento utilizzato nel template PDF fornito (banda di intestazione, linea di separazione, badge di stato).

Configurazione per sales-channel

Le impostazioni sopra possono essere sovrascritte per sales-channel in Impostazioni → Sales channels → [vostro canale] → Configurazione plugin. Utile se gestite più shop con politiche di validità diverse (per esempio 30 giorni per B2C, 60 giorni per B2B).

Generare un preventivo pro forma

Dalla scheda ordine (admin)

1. Aprite un ordine in Ordini → Panoramica
2. Cliccate sul tab Pro forma (accanto a Documenti)
3. Cliccate Genera preventivo pro forma
4. Il PDF viene creato, il preventivo appare nell’elenco con un numero PF-… e lo stato Bozza

Dall’API admin

Vengono esposti tre endpoint per integrare la generazione nei vostri flussi esterni:

POST /api/_action/df-proforma/generate
Body: { "orderId": "…" }

POST /api/_action/df-proforma/mark-sent
Body: { "proformaId": "…" }

GET  /api/_action/df-proforma/by-order/{orderId}

Autenticazione OAuth2 admin standard di Shopware. Utile per collegare DfProforma a un CRM esterno o a una pipeline di automazione.

Inviare un preventivo al cliente

Email transazionale

Dall’elenco dei preventivi (tab Pro forma della scheda ordine), cliccate sull’icona busta accanto al preventivo. Il modulo:

1. Passa il preventivo allo stato Inviato (con timestamp)
2. Invia un’email al cliente via il Mail Service Shopware, usando il template df_proforma_sent, nella lingua del sales-channel
3. Allega il PDF del preventivo e include l’URL pubblica di accettazione
4. Emette l’evento ProformaGeneratedEvent (trigger Flow Builder)

URL pubblica di accettazione

Ogni preventivo inviato porta un URL della forma:

https://vostro-shop.com/proforma/accept/{token}

Il token è cifrato e firmato con HMAC-SHA256 usando la chiave segreta di Shopware (APP_SECRET / kernel.secret). Impossibile da falsificare o indovinare. L’URL scade dopo la validità del preventivo (30 giorni di default).

Pagina pubblica di accettazione cliente

Il cliente apre l’URL — nessun account Shopware richiesto (la pagina bypassa l’autenticazione standard dell’account cliente). Vede:

• Un riepilogo pulito dell’ordine: righe, prezzi, IVA, totali, condizioni
• Un pulsante principale Accetta questo preventivo
• Un pulsante secondario Rifiuta con motivo
• La validità mostrata (“Valido fino al 20/06/2026”)

All’accettazione:

• Firma con timestamp al millisecondo e persistita in database
• Indirizzo IP del cliente persistito come prova
• Stato passa a Accettato con la cronologia di transizione marcata
• Evento ProformaAcceptedEvent dispatchato a Flow Builder

In caso di rifiuto, il campo Motivo è obbligatorio — utile per i vostri commerciali che possono ricontattare il cliente con una contro-proposta.

Workflow di stati

Sei stati coprono l’intero ciclo di vita di un preventivo:

• Bozza — Preventivo creato ma non ancora inviato al cliente
• Inviato — Email inviata, in attesa di risposta cliente
• Accettato — Il cliente ha cliccato Accetta sulla pagina pubblica
• Rifiutato — Il cliente ha cliccato Rifiuta con motivo
• Scaduto — Validità superata senza risposta (transizione automatica via scheduled task)
• Convertito — Ordine sottostante pagato, conversione automatica

Ogni transizione viene persistita con timestamp al secondo, identificatore dell’attore, tipo di trigger (commerciale, cliente, sistema, pagamento) e payload JSON per metadati liberi. Potete ricostruire in qualsiasi momento la cronologia esatta di un preventivo.

Auto-conversione al pagamento

Il modulo registra un Subscriber sull’evento order_transaction.state.paid della macchina a stati di Shopware. Quando una transazione passa a pagata (Stripe, bonifico, PayPal ecc.), il Subscriber:

1. Cerca tutti i preventivi pro forma in stato Accettato collegati all’ordine
2. Li passa allo stato Convertito
3. Marca la cronologia di transizione con tipo di trigger pagamento

Nessun intervento umano, nessun cron, nessun ritardo. I vostri report commerciali rimangono coerenti senza sforzo.

Flow Builder — eventi Business Event

Il modulo emette due eventi standard Shopware Business Event:

• ProformaGeneratedEvent — Alla generazione di un preventivo (implementa BusinessEventInterface)
• ProformaAcceptedEvent — All’accettazione del cliente (implementa BusinessEventInterface)

Entrambi appaiono automaticamente nell’elenco dei trigger del Flow Builder Shopware nativo. Potete collegare qualsiasi azione Flow:

• Notifica Slack al team vendite all’accettazione
• Email riepilogo interno al commerciale responsabile
• Webhook al vostro CRM (HubSpot, Salesforce, Pipedrive…)
• Aggiornamento di campo personalizzato sul cliente (per esempio, tag quote-accepted)
• Notifica push mobile via un servizio di terze parti

Nessun intervento nel codice del modulo necessario — tutto passa per l’admin Shopware.

Personalizzazione del template PDF

Il PDF del preventivo viene renderizzato tramite DocumentFileRendererRegistry (il nuovo sistema di rendering di file di Shopware 6.7), a partire dal template Twig @DfProforma/documents/proforma.html.twig fornito nel modulo.

Per personalizzarlo, create un plugin personalizzato o sovrascrivetelo dal vostro tema rispettando la gerarchia standard dei template Twig di Shopware:

custom/plugins/YourTheme/src/Resources/views/documents/proforma.html.twig

Il template fornito espone questi blocchi Twig identificati:

• Intestazione con logo e dati aziendali
• Blocco cliente
• Riepilogo delle righe ordine
• Totali HT/TTC con scomposizione IVA
• Banda di riepilogo in fondo (numero PF, date di emissione e scadenza)
• Filigrana PRO FORMA
• Colore brand configurabile via config.accentColor

Variabili disponibili nel template: order (OrderEntity caricata con tutte le sue associazioni), config (configurazione del documento incluso documentNumber, documentDate, validUntil, validityDays), context.

Multilingua

FR, EN, DE ed ES sono forniti di default, snippet storefront e admin. Per aggiungere altre lingue, create un file di snippet per locale in src/Resources/snippet/ seguendo la convenzione standard di Shopware.

I template email transazionali sono anch’essi multilingua: il template corretto viene selezionato automaticamente in base alla lingua del sales-channel del cliente al momento dell’invio. Potete personalizzare i template per lingua da Impostazioni → Shop → Template email.

API — endpoint admin disponibili

POST   /api/_action/df-proforma/generate         # Genera un preventivo per un ordine
POST   /api/_action/df-proforma/mark-sent        # Marca come inviato (transizione manuale)
GET    /api/_action/df-proforma/by-order/{id}    # Elenca i preventivi di un ordine

Le entità df_proforma sono anche accessibili tramite l’API DAL standard Shopware (/api/df-proforma) per ricerche, esportazioni o integrazioni avanzate.

Disinstallazione

Di default, i dati di business vengono conservati alla disinstallazione (opzione Keep User Data attivata). Preservate così la cronologia di audit dei preventivi emessi, utile per conformità e tracciabilità commerciale.

Per forzare la rimozione completa (tabella df_proforma, tipo di documento, range di numerazione, template email), disattivate l’opzione Keep User Data nel prompt di disinstallazione.

Risoluzione dei problemi

Il tab Pro forma non appare sulla scheda ordine

Il bundle di amministrazione non è stato ricompilato dopo l’installazione. Eseguite bin/build-administration.sh e poi bin/console cache:clear.

Errore “Unable to find a document generator with type df_proforma”

Il tag di servizio del renderer non è corretto — questo bug è stato corretto dalla 1.0.2. Assicuratevi di usare una versione del plugin ≥ 1.0.2.

Errore “Call to undefined method Context::getSalesChannelId()”

Causa storica: vecchia firma del costruttore RenderedDocument. Corretto in 1.0.4. Aggiornate alla 1.0.6.

Errore Twig “Cannot rewind a generator that was already run”

Corretto in 1.0.6 — il template è stato adattato per non consumare due volte un generatore proveniente da |filter().

Il cliente riceve l’email ma l’URL di accettazione restituisce un 404

Verificate che il sales-channel Storefront sia correttamente registrato come dominio del canale di vendita utilizzato per l’ordine. La rotta pubblica /proforma/accept/{token} è registrata sullo Storefront — non funziona se accedete all’URL tramite il dominio admin.

La scadenza automatica non funziona

Verificate che i message worker di Shopware siano in esecuzione in background (bin/console messenger:consume o tramite un supervisore tipo systemd/supervisord). La scadenza passa dalla coda di messaggi Shopware standard.

Supporto e aggiornamenti

12 mesi di aggiornamenti inclusi (compatibilità Shopware, correzioni di bug, aggiunte funzionali minori). Supporto via email in francese e inglese entro 24 ore lavorative. Codice sorgente PHP consegnato in chiaro, conforme PSR-4, verificabile e modificabile.

Per qualsiasi domanda o segnalazione: contact@datafirefly.com.