DfProforma Shopware: proforma offertes met klantacceptatie en automatische omzetting

Wat DfProforma doet

Shopware 6.7 kan facturen, pakbonnen en creditnota’s uitgeven, maar geen proforma offertes. In vrijwel elke B2B-context (industriële uitrusting, zakelijke dienstverlening, overheidsaankopen, verkoop via aanbestedingen) moet de klant echter een formeel document ontvangen dat hij aanvaardt voordat de bestelling definitief wordt.

DfProforma vult dat gat zonder omwegen: een echt native Shopware-documenttype df_proforma, een eigen nummerreeks PF{n}, een eigen PDF-sjabloon in Twig met uw huisstijl, een zelfstandige acceptatieworkflow voor de klant met een publieke URL ondertekend met HMAC-SHA256, en een automatische omzetting in een bestelling zodra de onderliggende transactie de status betaald krijgt.

Vereisten

• Shopware 6.7.0 of hoger (de plugin is niet achterwaarts compatibel met 6.6 vanwege de herzieningen van het documentsysteem)
• PHP 8.2 minimaal
• MySQL 8.0+ of MariaDB 10.6+
• Actieve Shopware message workers (aanbevolen voor het automatisch beheer van vervaldata)
• Geconfigureerde Shopware-maildienst (werkende SMTP voor transactionele verzendingen)

Installatie

1. De plugin uploaden

Ga in de Shopware-administration naar Extensies → Mijn extensies → Extensie uploaden en selecteer het bestand DfProforma-1.0.6.zip.

2. Installeren en activeren

Klik in de lijst met extensies op Installeren en daarna op Activeren. De Shopware-migraties draaien automatisch en maken het volgende aan:

• De SQL-tabel df_proforma en haar indexen op order_id, status en public_token
• Het documenttype df_proforma in document_type
• De nummerreeks document_df_proforma in het formaat PF{n}, configureerbaar
• Het transactionele e-mailsjabloon voor de generatie, de verzending en de acceptatie

3. De administration opnieuw compileren

De plugin levert een Vite-adminmodule die de bestelkaart uitbreidt (sw-order-detail-base). U moet de globale administratiebundel opnieuw compileren zodat het tabblad Proforma verschijnt:

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

Configuratie

Globale instellingen

Via Extensies → Mijn extensies → DfProforma → Configureren krijgt u toegang tot de volgende instellingen:

• Standaardgeldigheid: aantal dagen dat de acceptatielink geldig blijft (standaard 30). Elke offerte kan deze waarde afzonderlijk overschrijven.
• Automatische omzetting bij betaling: standaard ingeschakeld. Schakel dit uit als u de overgang Aanvaard → Omgezet handmatig wilt sturen.
• Naam van de afzender: de naam die als afzender van de transactionele e-mails wordt getoond (standaard: de naam van het sales channel).
• Merkaccent van de PDF: de accentkleur die in het meegeleverde PDF-sjabloon wordt gebruikt (kopbalk, scheidingslijn, statusbadge).

Configuratie per sales channel

Bovenstaande instellingen kunnen per sales channel worden overschreven via Instellingen → Sales channels → [uw kanaal] → Pluginconfiguratie. Handig als u meerdere shops beheert met een verschillend geldigheidsbeleid (bijvoorbeeld 30 dagen voor B2C en 60 dagen voor B2B).

Een proforma offerte genereren

Vanuit de bestelkaart (admin)

1. Open een bestelling via Bestellingen → Overzicht
2. Klik op het tabblad Proforma (naast Documenten)
3. Klik op Proforma offerte genereren
4. De PDF wordt aangemaakt en de offerte verschijnt in de lijst met een nummer PF-… en de status Concept

Vanuit de admin-API

Er zijn drie endpoints beschikbaar om de generatie in uw externe workflows te integreren:

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}

Standaard OAuth2-authenticatie van de Shopware-admin. Handig om DfProforma aan een extern CRM of een automatiseringspijplijn te koppelen.

Een offerte naar de klant sturen

Transactionele e-mail

Klik in de lijst met offertes (tabblad Proforma van de bestelkaart) op het envelopicoon naast de offerte. De module:

1. Zet de offerte op de status Verzonden (met tijdstempel)
2. Stuurt een e-mail naar de klant via de Shopware Mail Service, met het sjabloon df_proforma_sent, in de taal van het sales channel
3. Voegt de PDF van de offerte toe en neemt de publieke acceptatie-URL op
4. Vuurt het event ProformaGeneratedEvent af (trigger voor de Flow Builder)

Publieke acceptatie-URL

Elke verzonden offerte draagt een URL in de vorm:

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

Het token is versleuteld en ondertekend met HMAC-SHA256 met de geheime sleutel van Shopware (APP_SECRET / kernel.secret). Het is onmogelijk te vervalsen of te raden. De URL verloopt na de geldigheidsduur van de offerte (standaard 30 dagen).

Publieke acceptatiepagina voor de klant

De klant opent de URL, zonder dat een Shopware-account nodig is (de pagina omzeilt de standaardauthenticatie van het klantaccount). Hij ziet:

• Een net overzicht van de bestelling: regels, prijzen, btw, totalen, voorwaarden
• Een hoofdknop Deze offerte aanvaarden
• Een secundaire knop Weigeren met reden
• De weergegeven geldigheid (“Geldig tot 20-06-2026”)

Bij aanvaarding:

• Handtekening met tijdstempel tot op de milliseconde, opgeslagen in de database
• IP-adres van de klant opgeslagen als bewijs
• De status gaat naar Aanvaard met de overgang in de geschiedenis vastgelegd
• Het event ProformaAcceptedEvent wordt naar de Flow Builder gestuurd

Bij een weigering is het veld Reden verplicht, nuttig voor uw verkopers die de klant met een tegenvoorstel kunnen benaderen.

Statusworkflow

Zes statussen dekken de volledige levenscyclus van een offerte:

• Concept: offerte aangemaakt maar nog niet naar de klant verzonden
• Verzonden: e-mail verstuurd, in afwachting van het antwoord van de klant
• Aanvaard: de klant heeft op de publieke pagina op Aanvaarden geklikt
• Geweigerd: de klant heeft op Weigeren geklikt en een reden opgegeven
• Verlopen: geldigheid verstreken zonder antwoord (automatische overgang via een scheduled task)
• Omgezet: de onderliggende bestelling is betaald, automatische omzetting

Elke overgang wordt opgeslagen met de datum tot op de seconde, de identificatie van de actor, het type trigger (verkoper, klant, systeem, betaling) en een JSON-payload voor vrije metadata. U kunt op elk moment de exacte geschiedenis van een offerte reconstrueren.

Automatische omzetting bij betaling

De module registreert een subscriber op het event order_transaction.state.paid van de Shopware-statusmachine. Wanneer een transactie naar betaald gaat (Stripe, overschrijving, PayPal en dergelijke), doet de subscriber het volgende:

1. Hij zoekt alle proforma offertes met de status Aanvaard die aan de bestelling gekoppeld zijn
2. Hij zet ze op de status Omgezet
3. Hij legt de overgang in de geschiedenis vast met het triggertype betaling

Geen menselijke tussenkomst, geen cron, geen vertraging. Uw verkooprapporten blijven moeiteloos consistent.

Flow Builder, business events

De module zendt twee standaard Shopware-events uit:

• ProformaGeneratedEvent: bij het genereren van een offerte (implementeert BusinessEventInterface)
• ProformaAcceptedEvent: bij de aanvaarding door de klant (implementeert BusinessEventInterface)

Beide verschijnen automatisch in de lijst met triggers van de native Shopware Flow Builder. U kunt er elke Flow-actie aan koppelen:

• Slack-melding aan het verkoopteam bij aanvaarding
• Interne overzichtsmail naar de verantwoordelijke verkoper
• Webhook naar uw CRM (HubSpot, Salesforce, Pipedrive en andere)
• Bijwerken van een aangepast veld op de klant (bijvoorbeeld de tag quote-accepted)
• Mobiele pushmelding via een externe dienst

Er is geen ingreep in de code van de module nodig, alles wordt geconfigureerd via Instellingen → Shop → Flow Builder.

Aanpassing van het PDF-sjabloon

De PDF van de offerte wordt gerenderd via DocumentFileRendererRegistry (het nieuwe systeem voor bestandsweergave van Shopware 6.7), op basis van het Twig-sjabloon @DfProforma/documents/proforma.html.twig dat in de module wordt meegeleverd.

Om het aan te passen maakt u een eigen plugin of overschrijft u het vanuit uw thema, met respect voor de standaard Twig-sjabloonhiërarchie van Shopware:

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

Het meegeleverde sjabloon biedt deze benoemde Twig-blokken:

• Koptekst met logo en bedrijfsgegevens
• Klantblok
• Overzicht van de bestelregels
• Totalen exclusief en inclusief btw met btw-uitsplitsing
• Samenvattende balk in de voettekst (PF-nummer, uitgifte- en vervaldatum)
• Watermerk PRO FORMA
• Merkaccent instelbaar via config.accentColor

Beschikbare variabelen in het sjabloon: order (de OrderEntity geladen met al haar associaties), config (documentconfiguratie met onder meer documentNumber, documentDate, validUntil, validityDays) en context.

Meertaligheid

FR, EN, DE en ES worden standaard meegeleverd, met snippets voor Storefront en Admin. Om andere talen toe te voegen, maakt u per locale een snippetbestand aan in src/Resources/snippet/ volgens de standaardconventie van Shopware.

De transactionele e-mailsjablonen zijn eveneens meertalig: het juiste sjabloon wordt automatisch gekozen op basis van de taal van het sales channel van de klant op het moment van verzending. U kunt de sjablonen per taal aanpassen via Instellingen → Shop → E-mailsjablonen.

API, beschikbare admin-endpoints

POST   /api/_action/df-proforma/generate         # Genereert een offerte voor een bestelling
POST   /api/_action/df-proforma/mark-sent        # Markeert als verzonden (handmatige overgang)
GET    /api/_action/df-proforma/by-order/{id}    # Toont de offertes van een bestelling

De entiteiten df_proforma zijn ook bereikbaar via de standaard DAL-API van Shopware (/api/df-proforma) voor zoekopdrachten, exports of geavanceerde integraties.

Verwijderen

Standaard blijven de bedrijfsgegevens bij het verwijderen bewaard (de optie Keep User Data staat aan). Zo behoudt u de auditgeschiedenis van de uitgegeven offertes, nuttig voor compliance en commerciële traceerbaarheid.

Om een volledige verwijdering af te dwingen (tabel df_proforma, documenttype, nummerreeks, e-mailsjabloon), schakelt u de optie Keep User Data uit in het verwijderscherm.

Probleemoplossing

Het tabblad Proforma verschijnt niet op de bestelkaart

De administratiebundel is na de installatie niet opnieuw gecompileerd. Voer bin/build-administration.sh uit en daarna bin/console cache:clear.

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

De servicetag van de renderer klopt niet; deze bug is sinds 1.0.2 opgelost. Gebruik een versie ≥ 1.0.2 van de plugin.

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

Historische oorzaak: de oude constructorhandtekening van RenderedDocument. Opgelost in 1.0.4. Werk bij naar 1.0.6.

Twig-fout “Cannot rewind a generator that was already run”

Opgelost in 1.0.6, het sjabloon is aangepast zodat het een generator uit |filter() niet twee keer verbruikt.

De klant ontvangt de e-mail maar de acceptatie-URL geeft een 404-fout

Controleer of het Storefront sales channel daadwerkelijk als domein is geregistreerd voor het verkoopkanaal van de bestelling. De publieke route /proforma/accept/{token} is op de Storefront geregistreerd en werkt niet als u de URL via het admindomein benadert.

De automatische vervaldatum werkt niet

Controleer of de Shopware message workers op de achtergrond draaien (bin/console messenger:consume of via een supervisor zoals systemd of supervisord). Het verlopen verloopt via de standaard berichtenwachtrij van Shopware.

Support en updates

12 maanden updates inbegrepen (Shopware-compatibiliteit, bugfixes, kleine functionele toevoegingen). E-mailsupport in het Frans en het Engels binnen 24 werkuren. De PHP-broncode wordt open geleverd, conform PSR-4, controleerbaar en aanpasbaar.

Voor vragen of meldingen: contact@datafirefly.com.