Custom Checkout Fields: dokumentacja

Omówienie

DataFirefly Custom Checkout Fields dodaje pola niestandardowe do procesu zamówienia i formularza rejestracji w PrestaShop 8 i 9: numer zamówienia zakupu, preferowaną datę dostawy, SIRET, branżę, załącznik lub dowolne inne pole, które utworzysz. Wartości są sprawdzane przed złożeniem zamówienia, a następnie przenoszone na stronę zamówienia, fakturę PDF, dokument dostawy, do e-maili, list w panelu, eksportów CSV i webservice.

Instalacja

1. W panelu otwórz Moduły > Menedżer modułów i kliknij Wgraj moduł.
2. Wybierz plik dfcheckoutfields.zip.
3. Instalacja tworzy trzy tabele, chroniony folder upload/dfcheckoutfields, menu Zamówienia > Pola niestandardowe i Zamówienia > Eksport pól oraz pięć gotowych pól.
4. Kliknij Konfiguruj, aby ustawić opcje ogólne.

Aby zaktualizować, wgraj nowy plik ZIP na poprzedni: skrypty aktualizacji dodają nowe kolumny bez zmiany Twoich pól i zapisanych wartości.

Pola tworzone przy instalacji

• Numer zamówienia zakupu (po_number): tekst do 50 znaków, zapisywany w zamówieniu, widoczny na fakturze, dokumencie dostawy i jako kolumna listy zamówień.
• Preferowana data dostawy (desired_date): najwcześniej dziś + 2 dni, tylko dni robocze.
• Numer SIRET (siret): sprawdzany kluczem Luhna, zapisywany na koncie klienta, wymagany przy rejestracji i zamówieniu, ograniczony do klientów z Francji.
• Branża (sector): lista ośmiu branż, zapisywana na koncie klienta, pytana przy rejestracji.
• Załącznik (attachment): PDF, obrazy i dokumenty Office, maks. 8 MB.

Żadne z tych pól nie jest domyślnie wymagane. Zmieniaj, wyłączaj lub usuwaj je według potrzeb.

Ustawienia ogólne

Moduły > Menedżer modułów > Pola niestandardowe zamówienia i rejestracji > Konfiguruj.

• Położenie bloku w procesie zamówienia: krok płatności, nad metodami płatności (domyślnie), lub krok dostawy, pod przewoźnikami. Koszyki zawierające wyłącznie produkty wirtualne zawsze używają kroku płatności.
• Tytuł bloku: wyświetlany przy zamówieniu, na stronach zamówienia, w PDF i e-mailach, dla każdego języka.
• Położenie na fakturze PDF: nagłówek pod numerem faktury albo dół faktury. Zobacz Faktura i dokument dostawy.
• Notatka prywatna, gdy brakuje wymaganego pola: dopisuje listę brakujących pól do notatki prywatnej zamówienia, gdy moduł płatności pomija kontrolę.
• Kopiuj pola SIRET do natywnego pola SIRET klienta: aktualizuje pole SIRET w karcie klienta, używane przez tryb B2B PrestaShop.

Tworzenie i edycja pola

Zamówienia > Pola niestandardowe, następnie Dodaj pole lub ikona ołówka w wierszu. Formularz pokazuje tylko opcje przydatne dla wybranego typu i miejsca zapisu.

Pole

• Etykieta, tekst zastępczy i tekst pomocy: dla każdego języka. Pusty język przejmuje etykietę języka domyślnego.
• Kod: identyfikator techniczny z małych liter, cyfr i podkreśleń. Służy też jako zmienna e-mail {dfcf_CODE} i w webservice.
• Typ: tekst, tekst wielowierszowy, liczba, e-mail, data, lista rozwijana, pole wyboru, SIRET lub plik.
• Zapisywane w: Zamówienie (jedna wartość na zamówienie) lub Konto klienta (wartość w karcie klienta, wstępnie wypełniana przy zamówieniu i kopiowana do każdego zamówienia).
• Opcje listy: jedna opcja na wiersz w formacie klucz|Etykieta, np. industry|Przemysł. Zachowaj te same klucze we wszystkich językach.

Gdzie i kiedy

• Pokaż przy rejestracji i wymagane przy rejestracji: tylko pola konta klienta, bez typu plik. Pojawiają się też w formularzu Moje dane.
• Pokaż przy zamówieniu i wymagane przy zamówieniu.
• Pokaż tylko, jeśli: zobacz Wyświetlanie warunkowe.
• Kraje: kraj adresu rozliczeniowego przy zamówieniu, kraj odwiedzającego przy rejestracji. Puste dla wszystkich krajów.
• Grupy klientów: wszystko niezaznaczone dla wszystkich grup.

Walidacja

• Maksymalna długość: 0 dla wartości domyślnej (255 znaków, 2000 dla tekstu wielowierszowego).
• Wzorzec walidacji: wyrażenie regularne bez ograniczników, np. ^[A-Z]{2}[0-9]{6}$.
• Minimalny czas realizacji i maksymalny horyzont w dniach dla daty zapisywanej w zamówieniu.
• Tylko dni robocze: odrzuca sobotę i niedzielę.
• Dni zamknięcia: jeden na wiersz, 2026-12-24 dla dnia, 2026-08-01:2026-08-21 dla okresu, 12-25 dla każdego roku.
• Dozwolone rozszerzenia i maksymalny rozmiar dla pliku. Skrypty i pliki wykonywalne są zawsze odrzucane.

Dokumenty i eksporty

Pokaż klientowi (potwierdzenie, konto klienta, e-maile do klienta), na fakturze PDF, na dokumencie dostawy, jako kolumna z wyszukiwaniem na listach panelu, w eksportach CSV.

Lista pól

Ikony na liście włączają lub wyłączają ustawienie jednym kliknięciem. Przeciągaj wiersze, aby zmienić kolejność. Akcja Duplikuj tworzy wyłączoną kopię z kodem code_copy. Pola z wartościami w zamówieniach nie można usunąć: wyłącz je, aby zachować historię.

Wyświetlanie warunkowe

Przykład: pokazywanie SIRET tylko firmom.

1. Utwórz pole wyboru zapisywane na koncie klienta, kod is_company, etykieta Jestem firmą.
2. Edytuj pole SIRET, sekcja Gdzie i kiedy, i wybierz Pokaż tylko, jeśli: Jestem firmą. Pozostaw puste „ma jedną z tych wartości”: dla pola wyboru oznacza to zaznaczone.

Dla listy rozwijanej podaj oczekiwane klucze oddzielone przecinkami, np. health,public. Warunki można łączyć w łańcuch: pole, którego pole nadrzędne jest ukryte, również jest ukryte. Ukryte pole nigdy nie jest wymagane, a jego wartość nie jest zapisywana. Pole nadrzędne musi być wyświetlane w tym samym miejscu (rejestracja lub zamówienie) albo już wypełnione na koncie klienta.

Po stronie klienta

Przy zamówieniu

Blok pojawia się w wybranym kroku. Każda wartość zapisuje się podczas wpisywania. Dopóki wymagane pole jest puste lub niepoprawne, kliknięcie Złóż zamówienie (lub Dalej w kroku dostawy) jest zablokowane, komunikat pojawia się pod polem, a strona przewija się do niego. Załącznik wysyła się przez przeciągnięcie lub kliknięcie, z paskiem postępu. Klient może go usunąć i wysłać inny.

Przy rejestracji i w Moich danych

Pola konta klienta oznaczone Pokaż przy rejestracji są dodawane do natywnego formularza zakładania konta, formularza gościa przy zamówieniu i formularza Moje dane. Błędy są wyświetlane tak jak dla pól PrestaShop.

Po zamówieniu

Wartości oznaczone Pokaż klientowi pojawiają się na stronie potwierdzenia i w szczegółach zamówienia na koncie klienta. Klient, do którego należy zamówienie, może tam pobrać załącznik.

Faktura i dokument dostawy

Dół faktury: moduł używa hooka displayPDFInvoice i drukuje tabelę po sumach. Żaden plik nie jest modyfikowany.

Nagłówek, pod numerem faktury: PrestaShop nie ma tam hooka. Po zapisaniu tego ustawienia moduł dodaje blok ograniczony znacznikami {* dfcf:start *} i {* dfcf:end *} na końcu pliku themes/TWÓJ_MOTYW/pdf/invoice.summary-tab.tpl. Jeśli plik nie istnieje, powstaje na podstawie pliku PrestaShop. Jeśli już istnieje, moduł go uzupełnia i zachowuje kopię .dfcf-backup. Powrót do ustawienia Dół faktury lub odinstalowanie usuwa blok. Jeśli pliku nie można zapisać, komunikat podaje jego ścieżkę.

Z DataFirefly Invoice Editor, który zastępuje renderowanie faktury, używaj ustawienia Dół faktury: edytor zachowuje treści modułów w wybranym przez Ciebie miejscu.

Dokument dostawy używa hooka displayPDFDeliverySlip, pole po polu.

E-maile

W e-mailach zawierających ID zamówienia, m.in. order_conf i new_order, dostępne są dwa rodzaje zmiennych:

• {dfcf_fields}: wszystkie wartości w tabeli. W order_conf tylko pola oznaczone Pokaż klientowi, w new_order, wysyłanym do sprzedawcy, wszystkie pola.
• {dfcf_CODE}: jedna wartość, np. {dfcf_po_number} lub {dfcf_desired_date}.

Dodaj je w Wygląd > Motyw e-maili lub w plikach e-maili swojego motywu.

Panel administracyjny

• Strona zamówienia: karta Pola niestandardowe ze wszystkimi wartościami. Przycisk Edytuj pozwala poprawić wartość lub zastąpić załącznik.
• Karta klienta: karta z polami konta klienta, edytowalna w ten sam sposób.
• Listy: każde pole oznaczone jako kolumna z wyszukiwaniem pojawia się na liście zamówień z filtrem tekstowym. Pola konta klienta pojawiają się także na liście klientów.

Eksport CSV

Zamówienia > Eksport pól. Wybierz Zamówienia lub Klienci, okres, statusy zamówień (wszystko niezaznaczone dla wszystkich), separator i czy eksportować tylko wiersze z co najmniej jedną wartością. Plik jest w UTF-8 z BOM i otwiera się bezpośrednio w Excelu. Zamówienia są eksportowane z numerem referencyjnym, datą, statusem, klientem, sumami netto i brutto oraz walutą, a następnie z polami oznaczonymi Uwzględnij w eksportach CSV.

Webservice

1. Zaawansowane > Webservice: włącz webservice i utwórz lub edytuj klucz.
2. Zaznacz GET dla zasobu dfcf_values.
3. Wywołaj /api/dfcf_values?filter[id_order]=[123]&display=full.

Każda wartość jest zwracana z id_dfcf_field, id_order, id_customer, id_cart, value, value_display, field_code, field_label i has_file. Wartości profilu klienta mają id_order i id_cart równe 0.

Załączniki i bezpieczeństwo

Każdy plik jest sprawdzany pod kątem rozszerzenia (lista pola) i rzeczywistej zawartości: skrypt przemianowany na .pdf zostanie odrzucony. Plik jest zapisywany w upload/dfcheckoutfields pod losową nazwą, bez rozszerzenia, w folderze, do którego plik .htaccess blokuje dostęp bezpośredni. Na Nginx dodaj regułę location ^~ /upload/dfcheckoutfields/ { deny all; }. Pobieranie zawsze przechodzi przez moduł, który sprawdza, czy odwiedzający jest klientem zamówienia lub pracownikiem.

RODO

Wartości zapisane na koncie klienta są usuwane razem z klientem. Moduł odpowiada na żądania eksportu i usunięcia danych z oficjalnego modułu RODO PrestaShop. Wartości skopiowane do zamówień pozostają z zamówieniem.

Rozwiązywanie problemów

Blok nie pojawia się przy zamówieniu

Sprawdź, czy pole jest aktywne i oznaczone Pokaż przy zamówieniu oraz czy grupa i kraj klienta odpowiadają jego ograniczeniom. Jeśli wybrano krok dostawy, sprawdź, czy motyw wywołuje hook displayAfterCarrier.

Przycisk Złóż zamówienie nie jest blokowany

Moduł rozpoznaje przycisk motywów Classic i Hummingbird. Motyw, który zastępuje ten przycisk innym elementem, lub płatność ekspresowa uruchamiana z karty produktu nie są objęte kontrolą: włącz notatkę prywatną, aby otrzymywać informację o niepełnych zamówieniach.

Pola nie pojawiają się w nagłówku faktury

Sprawdź, czy plik motywu pdf/invoice.summary-tab.tpl jest zapisywalny, zapisz ponownie ustawienia i wyczyść pamięć podręczną w Zaawansowane > Wydajność.

Zmienna e-mail wyświetla się dosłownie

Jest wypełniana tylko w e-mailach zawierających ID zamówienia. Sprawdź też, czy kod dokładnie odpowiada kodowi pola.