DfProforma Shopware: oferty pro forma z akceptacją klienta i automatyczną konwersją

Co robi DfProforma

Shopware 6.7 potrafi wystawiać faktury, dokumenty dostawy i korekty, ale nie oferty pro forma. Tymczasem w niemal każdym kontekście B2B (sprzęt przemysłowy, usługi dla firm, zakupy publiczne, sprzedaż w trybie przetargowym) klient musi otrzymać formalny dokument, który akceptuje zanim zamówienie stanie się wiążące.

DfProforma wypełnia tę lukę bez prowizorki: prawdziwy natywny typ dokumentu Shopware df_proforma, własny zakres numeracji PF{n}, własny brandowany szablon PDF w Twigu, samodzielny workflow akceptacji klienta z publicznym adresem URL podpisanym HMAC-SHA256 oraz automatyczna konwersja w zamówienie, gdy tylko powiązana transakcja przejdzie w stan opłaconej.

Wymagania

• Shopware 6.7.0 lub nowszy (plugin nie jest wstecznie zgodny z 6.6 z powodu przebudowy systemu dokumentów)
• PHP minimum 8.2
• MySQL 8.0+ lub MariaDB 10.6+
• Aktywne workery wiadomości Shopware (zalecane do automatycznej obsługi wygaśnięć)
• Skonfigurowany serwis mail Shopware (działający SMTP dla wysyłek transakcyjnych)

Instalacja

1. Przesłanie pluginu

W administracji Shopware przejdź do Rozszerzenia → Moje rozszerzenia → Prześlij rozszerzenie i wybierz plik DfProforma-1.0.6.zip.

2. Instalacja i aktywacja

Na liście rozszerzeń kliknij Zainstaluj, a następnie Aktywuj. Migracje Shopware wykonują się automatycznie i tworzą:

• Tabelę SQL df_proforma i jej indeksy na order_id, status, public_token
• Typ dokumentu df_proforma w document_type
• Zakres numeracji document_df_proforma w formacie PF{n}, konfigurowalny
• Podstawowy transakcyjny szablon e-mail dla generowania, wysyłki i akceptacji

3. Rekompilacja administracji

Plugin dostarcza moduł Vite dla administracji, który rozszerza kartę zamówienia (sw-order-detail-base). Trzeba przekompilować globalny bundle administracji, aby pojawiła się zakładka Pro forma:

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

Konfiguracja

Parametry globalne

W Rozszerzenia → Moje rozszerzenia → DfProforma → Konfiguruj masz dostęp do następujących ustawień:

• Domyślna ważność: liczba dni, przez które link akceptacji pozostaje ważny (domyślnie 30). Każda oferta może nadpisać tę wartość indywidualnie.
• Automatyczna konwersja przy zaksięgowaniu: włączona domyślnie. Wyłącz ją, jeśli chcesz zachować ręczną kontrolę nad przejściem Zaakceptowana → Skonwertowana.
• Nazwa nadawcy: nazwa wyświetlana jako nadawca e-maili transakcyjnych (domyślnie nazwa sales-channelu).
• Kolor akcentu marki w PDF: kolor akcentu używany w dostarczonym szablonie PDF (pasek nagłówka, linia separacji, plakietka statusu).

Konfiguracja per sales-channel

Powyższe parametry można nadpisać per sales-channel w Ustawienia → Sales channels → [Twój kanał] → Konfiguracja pluginu. Przydatne, gdy prowadzisz kilka sklepów z różnymi politykami ważności (na przykład 30 dni dla B2C, 60 dni dla B2B).

Generowanie oferty pro forma

Z karty zamówienia (administracja)

1. Otwórz zamówienie w Zamówienia → Przegląd
2. Kliknij zakładkę Pro forma (obok Dokumenty)
3. Kliknij Wygeneruj ofertę pro forma
4. PDF zostaje utworzony, oferta pojawia się na liście z numerem PF-… i statusem Szkic

Z API administracji

Udostępnione są trzy endpointy do zintegrowania generowania z Twoimi zewnętrznymi workflowami:

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}

Standardowe uwierzytelnianie OAuth2 administracji Shopware. Przydatne do podpięcia DfProforma pod zewnętrzny CRM albo pipeline automatyzacji.

Wysyłka oferty do klienta

E-mail transakcyjny

Z listy ofert (zakładka Pro forma na karcie zamówienia) kliknij ikonę koperty obok oferty. Moduł:

1. Przenosi ofertę w status Wysłana (ze znacznikiem czasu)
2. Wysyła e-mail do klienta przez Mail Service Shopware, używając szablonu df_proforma_sent, w języku sales-channelu
3. Załącza PDF oferty i dołącza publiczny adres URL akceptacji
4. Emituje zdarzenie ProformaGeneratedEvent (wyzwalacz Flow Buildera)

Publiczny adres URL akceptacji

Każda wysłana oferta ma adres URL postaci:

https://twoj-sklep.com/proforma/accept/{token}

Token jest szyfrowany i podpisany HMAC-SHA256 tajnym kluczem Shopware (APP_SECRET / kernel.secret). Nie da się go sfałszować ani odgadnąć. Adres URL wygasa po upływie ważności oferty (domyślnie 30 dni).

Publiczna strona akceptacji klienta

Klient otwiera adres URL bez wymaganego konta Shopware (strona omija standardowe uwierzytelnianie konta klienta). Widzi:

• Czytelne podsumowanie zamówienia: pozycje, ceny, VAT, sumy, warunki
• Główny przycisk Akceptuję tę ofertę
• Drugorzędny przycisk Odrzuć z podaniem powodu
• Wyświetloną ważność (“Ważna do 20.06.2026”)

Przy akceptacji:

• Podpis ze znacznikiem czasu z dokładnością do milisekundy zapisany w bazie
• Adres IP klienta zapisany jako dowód
• Status przechodzi na Zaakceptowana z oznaczoną historią przejścia
• Zdarzenie ProformaAcceptedEvent wysłane do Flow Buildera

W przypadku odmowy pole Powód jest obowiązkowe, co przydaje się Twoim handlowcom, którzy mogą skontaktować się z klientem z kontrpropozycją.

Workflow statusów

Sześć statusów pokrywa cały cykl życia oferty:

• Szkic: oferta utworzona, ale jeszcze niewysłana do klienta
• Wysłana: e-mail wysłany, oczekiwanie na odpowiedź klienta
• Zaakceptowana: klient kliknął Akceptuję na publicznej stronie
• Odrzucona: klient kliknął Odrzuć z podaniem powodu
• Wygasła: ważność przekroczona bez odpowiedzi (automatyczne przejście przez scheduled task)
• Skonwertowana: powiązane zamówienie opłacone, konwersja automatyczna

Każde przejście jest zapisywane z datą co do sekundy, identyfikatorem aktora, typem wyzwalacza (handlowiec, klient, system, płatność) oraz payloadem JSON na dowolne metadane. Możesz odtworzyć dokładną historię oferty w dowolnym momencie.

Automatyczna konwersja przy zaksięgowaniu

Moduł rejestruje Subscriber na zdarzeniu order_transaction.state.paid maszyny stanów Shopware. Gdy transakcja przechodzi w opłaconą (Stripe, przelew, PayPal itd.), Subscriber:

1. Szuka wszystkich ofert pro forma o statusie Zaakceptowana powiązanych z zamówieniem
2. Przenosi je w status Skonwertowana
3. Oznacza historię przejścia typem wyzwalacza płatność

Żadnej interwencji człowieka, żadnego crona, żadnego opóźnienia. Twoje raporty handlowe pozostają spójne bez wysiłku.

Flow Builder: zdarzenia Business Event

Moduł emituje dwa standardowe zdarzenia Shopware:

• ProformaGeneratedEvent: przy generowaniu oferty (implementuje BusinessEventInterface)
• ProformaAcceptedEvent: przy akceptacji przez klienta (implementuje BusinessEventInterface)

Oba pojawiają się automatycznie na liście wyzwalaczy natywnego Flow Buildera Shopware. Możesz podpiąć pod nie dowolną akcję Flow:

• Powiadomienie na Slacku dla zespołu sprzedaży przy akceptacji
• Wewnętrzny e-mail podsumowujący do odpowiedzialnego handlowca
• Webhook do Twojego CRM (HubSpot, Salesforce, Pipedrive…)
• Aktualizacja pola niestandardowego na kliencie (na przykład tag quote-accepted)
• Powiadomienie push na mobile przez usługę zewnętrzną

Nie jest potrzebna żadna ingerencja w kod modułu: wszystko konfiguruje się w Ustawienia → Sklep → Flow Builder.

Personalizacja szablonu PDF

PDF oferty jest renderowany przez DocumentFileRendererRegistry (nowy system renderowania plików w Shopware 6.7), na podstawie szablonu Twig @DfProforma/documents/proforma.html.twig dostarczonego w module.

Aby go spersonalizować, utwórz własny plugin albo nadpisz go w swoim motywie, respektując standardową hierarchię szablonów Twig Shopware:

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

Dostarczony szablon udostępnia następujące bloki Twig:

• Nagłówek z logo i danymi firmy
• Blok klienta
• Podsumowanie pozycji zamówienia
• Sumy netto/brutto z rozbiciem VAT
• Pasek podsumowania w stopce (numer PF, daty wystawienia i wygaśnięcia)
• Znak wodny PRO FORMA
• Konfigurowalny akcent marki przez config.accentColor

Zmienne dostępne w szablonie: order (OrderEntity wczytana ze wszystkimi asocjacjami), config (konfiguracja dokumentu, w tym documentNumber, documentDate, validUntil, validityDays), context.

Wielojęzyczność

FR, EN, DE i ES są dostarczane domyślnie, snippety Storefrontu i administracji. Aby dodać kolejne języki, utwórz plik snippetów per locale w src/Resources/snippet/, zgodnie ze standardową konwencją Shopware.

Transakcyjne szablony e-mail również są wielojęzyczne: właściwy szablon jest wybierany automatycznie zgodnie z językiem sales-channelu klienta w momencie wysyłki. Szablony per język możesz personalizować w Ustawienia → Sklep → Szablony e-mail.

API: dostępne endpointy administracji

POST   /api/_action/df-proforma/generate         # Generate a quote for an order
POST   /api/_action/df-proforma/mark-sent        # Mark as sent (manual transition)
GET    /api/_action/df-proforma/by-order/{id}    # List an order's quotes

Encje df_proforma są także dostępne przez standardowe API DAL Shopware (/api/df-proforma) do wyszukiwań, eksportów lub zaawansowanych integracji.

Odinstalowanie

Domyślnie dane biznesowe są zachowywane przy odinstalowaniu (opcja Keep User Data włączona). Zachowujesz w ten sposób historię audytową wystawionych ofert, przydatną dla zgodności i śledzenia handlowego.

Aby wymusić pełne usunięcie (tabela df_proforma, typ dokumentu, zakres numeracji, szablon e-mail), wyłącz opcję Keep User Data w oknie odinstalowania.

Rozwiązywanie problemów

Zakładka Pro forma nie pojawia się na karcie zamówienia

Bundle administracji nie został przekompilowany po instalacji. Uruchom bin/build-administration.sh, a następnie bin/console cache:clear.

Błąd “Unable to find a document generator with type df_proforma”

Tag serwisu renderera jest nieprawidłowy: ten błąd jest naprawiony od wersji 1.0.2. Upewnij się, że używasz wersji pluginu ≥ 1.0.2.

Błąd “Call to undefined method Context::getSalesChannelId()”

Przyczyna historyczna: stara sygnatura konstruktora RenderedDocument. Naprawione w 1.0.4. Zaktualizuj do 1.0.6.

Błąd Twig “Cannot rewind a generator that was already run”

Naprawione w 1.0.6: szablon został dostosowany tak, aby nie konsumować dwa razy generatora pochodzącego z |filter().

Klient otrzymuje e-mail, ale adres URL akceptacji zwraca błąd 404

Sprawdź, czy sales-channel Storefrontu jest zarejestrowany jako domena kanału sprzedaży użytego w zamówieniu. Publiczna trasa /proforma/accept/{token} jest zarejestrowana w Storefroncie: nie działa, jeśli wchodzisz na adres URL przez domenę administracji.

Automatyczne wygasanie nie działa

Sprawdź, czy message workery Shopware działają w tle (bin/console messenger:consume albo przez supervisor typu systemd/supervisord). Wygasanie przechodzi przez standardową kolejkę wiadomości Shopware.

Wsparcie i aktualizacje

12 miesięcy aktualizacji w cenie (zgodność z Shopware, poprawki błędów, drobne dodatki funkcjonalne). Wsparcie e-mail po francusku i angielsku w ciągu 24 godzin roboczych. Kod źródłowy PHP dostarczany jawnie, zgodny z PSR-4, możliwy do audytu i modyfikacji.

W razie pytań lub zgłoszeń: contact@datafirefly.com.