DfProforma Shopware — Devis pro forma avec acceptation client et auto-conversion

Ce que fait DfProforma

Shopware 6.7 sait émettre des factures, des bons de livraison et des avoirs — mais pas de devis pro forma. Or dans la quasi-totalité des contextes B2B (équipement industriel, services aux entreprises, achats publics, ventes par appel d’offres), le client doit recevoir un document formel qu’il accepte avant que la commande devienne ferme.

DfProforma comble ce manque sans bricoler : un véritable type de document Shopware natif df_proforma, sa propre plage de numérotation PF{n}, son template PDF brandé Twig, un workflow d’acceptation client autonome avec URL publique signée HMAC-SHA256, et une auto-conversion en commande dès que la transaction sous-jacente passe à l’état payé.

Prérequis

• Shopware 6.7.0 ou supérieur (le plugin n’est pas rétro-compatible 6.6 en raison des refontes du système de documents)
• PHP 8.2 minimum
• MySQL 8.0+ ou MariaDB 10.6+
• Workers de messages Shopware actifs (recommandé pour la gestion automatique des expirations)
• Mail service Shopware configuré (SMTP fonctionnel pour les envois transactionnels)

Installation

1. Téléverser le plugin

Depuis l’administration Shopware, allez dans Extensions → Mes extensions → Téléverser une extension, et sélectionnez le fichier DfProforma-1.0.6.zip.

2. Installer et activer

Dans la liste des extensions, cliquez Installer puis Activer. Les migrations Shopware s’exécutent automatiquement et créent :

• La table SQL df_proforma et ses index sur order_id, status, public_token
• Le type de document df_proforma dans document_type
• La plage de numérotation document_df_proforma au format PF{n}, configurable
• Le template email transactionnel de base pour la génération, l’envoi et l’acceptation

3. Recompiler l’administration

Le plugin fournit un module Vite admin qui étend la fiche commande (sw-order-detail-base). Il faut recompiler le bundle d’administration global pour que l’onglet Pro forma apparaisse :

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

Configuration

Paramètres globaux

Depuis Extensions → Mes extensions → DfProforma → Configurer, vous accédez aux paramètres suivants :

• Validité par défaut — Nombre de jours pendant lesquels le lien d’acceptation reste valide (30 par défaut). Chaque devis peut surcharger cette valeur individuellement.
• Auto-conversion à l’encaissement — Activée par défaut. Désactivez-la si vous souhaitez conserver le contrôle manuel du basculement Accepté → Converti.
• Nom de l’expéditeur — Nom affiché comme expéditeur des emails transactionnels (par défaut : le nom du sales-channel).
• Accent de marque du PDF — Couleur d’accent utilisée dans le template PDF livré (bandeau d’en-tête, ligne de séparation, badge de statut).

Configuration par sales-channel

Les paramètres ci-dessus peuvent être surchargés par sales-channel dans Paramètres → Sales channels → [votre canal] → Configuration du plugin. Utile si vous gérez plusieurs boutiques avec des politiques de validité différentes (par exemple 30 jours pour le B2C, 60 jours pour le B2B).

Générer un devis pro forma

Depuis la fiche commande (admin)

1. Ouvrez une commande dans Commandes → Vue d’ensemble
2. Cliquez sur l’onglet Pro forma (à côté de Documents)
3. Cliquez Générer un devis pro forma
4. Le PDF est créé, le devis apparaît dans la liste avec un numéro PF-… et le statut Brouillon

Depuis l’API admin

Trois endpoints sont exposés pour intégrer la génération dans vos workflows externes :

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}

Authentification standard OAuth2 admin de Shopware. Utile pour brancher DfProforma sur un CRM externe ou un pipeline d’automatisation.

Envoyer un devis au client

Email transactionnel

Depuis la liste des devis (onglet Pro forma de la fiche commande), cliquez l’icône enveloppe à côté du devis. Le module :

1. Passe le devis en statut Envoyé (avec horodatage)
2. Envoie un email au client via le Mail Service Shopware, en utilisant le template df_proforma_sent, dans la langue du sales-channel
3. Joint le PDF du devis et inclut l’URL publique d’acceptation
4. Émet l’événement ProformaGeneratedEvent (déclencheur Flow Builder)

URL publique d’acceptation

Chaque devis envoyé porte une URL de la forme :

https://votre-boutique.com/proforma/accept/{token}

Le token est chiffré et signé HMAC-SHA256 avec la clé secrète Shopware (APP_SECRET / kernel.secret). Impossible à forger ou à deviner. L’URL expire après la validité du devis (30 jours par défaut).

Page publique d’acceptation client

Le client ouvre l’URL — sans compte Shopware requis (la page contourne l’authentification standard du compte client). Il voit :

• Un récapitulatif propre de la commande : lignes, prix, TVA, totaux, conditions
• Un bouton principal Accepter ce devis
• Un bouton secondaire Décliner avec motif
• La validité affichée (« Valable jusqu’au 20/06/2026 »)

À l’acceptation :

• Signature horodatée à la milliseconde et persistée en base
• Adresse IP client persistée pour preuve
• Statut passe à Accepté avec l’historique de transition marqué
• Événement ProformaAcceptedEvent dispatché vers Flow Builder

En cas de refus, le champ Motif est obligatoire — utile pour vos commerciaux qui peuvent recontacter le client avec une contre-proposition.

Workflow de statuts

Six statuts couvrent l’intégralité du cycle de vie d’un devis :

• Brouillon — Devis créé mais pas encore envoyé au client
• Envoyé — Email envoyé, en attente de réponse client
• Accepté — Client a cliqué Accepter sur la page publique
• Décliné — Client a cliqué Décliner avec motif
• Expiré — Validité dépassée sans réponse (transition automatique via scheduled task)
• Converti — Commande sous-jacente payée, conversion automatique

Chaque transition est persistée avec date à la seconde, identifiant de l’acteur, type de déclencheur (commercial, client, système, paiement) et payload JSON pour les métadonnées libres. Vous pouvez reconstituer l’historique exact d’un devis à tout moment.

Auto-conversion à l’encaissement

Le module enregistre un Subscriber sur l’événement order_transaction.state.paid de la machine à états Shopware. Quand une transaction bascule en payée (Stripe, virement, PayPal, etc.), le Subscriber :

1. Cherche tous les devis pro forma au statut Accepté rattachés à la commande
2. Les bascule en statut Converti
3. Marque l’historique de transition avec le type de déclencheur paiement

Aucune intervention humaine, aucun cron, aucun délai. Vos rapports commerciaux restent cohérents sans effort.

Flow Builder — événements Business Event

Deux événements standards Shopware sont émis par le module :

• ProformaGeneratedEvent — À la génération d’un devis (implémente BusinessEventInterface)
• ProformaAcceptedEvent — À l’acceptation par le client (implémente BusinessEventInterface)

Les deux apparaissent automatiquement dans la liste des déclencheurs du Flow Builder Shopware natif. Vous pouvez brancher dessus n’importe quelle action Flow :

• Notification Slack à l’équipe vente à l’acceptation
• Email récap interne au commercial responsable
• Webhook vers votre CRM (HubSpot, Salesforce, Pipedrive…)
• Mise à jour de champ personnalisé sur le client (par exemple, tag quote-accepted)
• Notification push mobile via un service tiers

Aucune intervention dans le code du module nécessaire — tout se configure depuis Paramètres → Shop → Flow Builder.

Personnalisation du template PDF

Le PDF du devis est rendu via DocumentFileRendererRegistry (le nouveau système de rendu de fichiers Shopware 6.7), à partir du template Twig @DfProforma/documents/proforma.html.twig livré dans le module.

Pour le personnaliser, créez un plugin custom ou surchargez-le depuis votre thème en respectant la hiérarchie de templates Twig standard de Shopware :

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

Le template livré expose ces blocs Twig identifiés :

• En-tête avec logo et coordonnées société
• Bloc client
• Récapitulatif des lignes de commande
• Totaux HT/TTC avec ventilation TVA
• Bandeau résumé en pied (numéro PF, dates d’émission et d’expiration)
• Filigrane PRO FORMA
• Accent de marque configurable via config.accentColor

Variables disponibles dans le template : order (OrderEntity chargée avec toutes ses associations), config (config du document dont documentNumber, documentDate, validUntil, validityDays), context.

Multilingue

FR, EN, DE et ES sont livrés par défaut, snippets Storefront et Admin. Pour ajouter d’autres langues, créez un fichier de snippets par locale dans src/Resources/snippet/ en suivant la convention Shopware standard.

Les templates email transactionnels sont également multilingues : le bon template est sélectionné automatiquement selon la langue du sales-channel du client au moment de l’envoi. Vous pouvez personnaliser les templates par langue depuis Paramètres → Shop → Templates d’email.

API — endpoints admin disponibles

POST   /api/_action/df-proforma/generate         # Génère un devis pour une commande
POST   /api/_action/df-proforma/mark-sent        # Marque comme envoyé (transition manuelle)
GET    /api/_action/df-proforma/by-order/{id}    # Liste les devis d'une commande

Les entités df_proforma sont également accessibles via l’API DAL standard Shopware (/api/df-proforma) pour recherches, exports ou intégrations avancées.

Désinstallation

Par défaut, les données métier sont conservées à la désinstallation (option Keep User Data activée). Vous préservez ainsi l’historique d’audit des devis émis, utile pour la conformité et la traçabilité commerciale.

Pour forcer la suppression complète (table df_proforma, type de document, plage de numérotation, template email), désactivez l’option Keep User Data dans le prompt de désinstallation.

Dépannage

L’onglet Pro forma n’apparaît pas sur la fiche commande

Le bundle d’administration n’a pas été recompilé après installation. Lancez bin/build-administration.sh puis bin/console cache:clear.

Erreur « Unable to find a document generator with type df_proforma »

Le tag de service du renderer n’est pas correct — ce bug est corrigé depuis la 1.0.2. Assurez-vous d’utiliser une version ≥ 1.0.2 du plugin.

Erreur « Call to undefined method Context::getSalesChannelId() »

Cause historique : ancienne signature du constructeur RenderedDocument. Corrigé en 1.0.4. Mettez à jour vers 1.0.6.

Erreur Twig « Cannot rewind a generator that was already run »

Corrigé en 1.0.6 — le template a été adapté pour ne pas consommer deux fois un générateur issu de |filter().

Le client reçoit l’email mais l’URL d’acceptation renvoie une erreur 404

Vérifiez que le sales-channel Storefront est bien enregistré comme domaine du canal de vente utilisé pour la commande. La route publique /proforma/accept/{token} est enregistrée sur le Storefront — elle ne fonctionne pas si vous accédez à l’URL via le domaine admin.

L’expiration automatique ne fonctionne pas

Vérifiez que les message workers Shopware sont bien lancés en arrière-plan (bin/console messenger:consume ou via un superviseur type systemd/supervisord). L’expiration passe par la file de messages Shopware standard.

Support et mises à jour

12 mois de mises à jour incluses (compatibilité Shopware, corrections de bugs, ajouts fonctionnels mineurs). Support par email en français et anglais sous 24 heures ouvrées. Code source PHP livré en clair, conforme PSR-4, auditable et modifiable.

Pour toute question ou remontée : contact@datafirefly.com.