Integracja Kasy z PrestaShop (Square, Zettle, SumUp): dokumentacja

Zasada działania

PrestaShop jest źródłem stanów magazynowych. Każda zmiana stanu powiązanego produktu trafia do kasy jako ilość bezwzględna. Każda sprzedaż z kasy jest importowana, odejmowana od stanów PrestaShop z powodem ruchu „Sprzedaż w kasie”, a nowy stan wraca do pozostałych kas. Zwroty przywracają pozycje na stan z powodem „Zwrot w kasie”.

• Square: stany w obu kierunkach, sprzedaż, zwroty, wysyłka katalogu.
• Zettle by PayPal: stany w obu kierunkach, sprzedaż, zwroty, wysyłka katalogu.
• SumUp: tylko import sprzedaży. Publiczne API SumUp nie udostępnia ani stanów, ani katalogu.

Wymagania

• PrestaShop 8.0 do 9.x.
• Zadanie cron na hostingu.
• HTTPS w sklepie dla webhooka Zettle.
• Konto Square, Zettle lub SumUp z dostępem deweloperskim.

Instalacja

1. W Moduły > Menedżer modułów kliknij Prześlij moduł i wyślij plik ZIP.
2. Moduł dodaje menu Katalog > Integracja kas.
3. Pulpit pokazuje listę „Pierwsze kroki”, która odhacza się w miarę konfiguracji.

Połączenie kas

Otwórz zakładkę Połączenia. Każda kasa ma własny panel z polem Włączone. Dane dostępowe są szyfrowane w bazie: puste pole zachowuje zapisaną wartość.

Square

1. Utwórz aplikację w Square Developer Dashboard i skopiuj jej produkcyjny token dostępu.
2. Wklej go w polu Token dostępu, wybierz środowisko, zapisz i kliknij Testuj połączenie.
3. Wybierz lokalizację, która otrzymuje stany. Jeśli masz ich kilka, zaznacz te, z których ma być importowana sprzedaż (maksymalnie 10).
4. Dla natychmiastowego importu utwórz subskrypcję webhooka na zdarzenie order.updated z wyświetlonym adresem URL powiadomień i wklej klucz podpisu w module. Adres URL musi być identyczny po obu stronach.

Zettle by PayPal

1. W Zettle Developer Portal utwórz klucz API self-hosted z zakresami READ:PURCHASE, READ:PRODUCT, READ:USERINFO i WRITE:PRODUCT.
2. Wpisz Client ID i klucz API, zapisz i przetestuj połączenie.
3. Kliknij Aktywuj webhook, aby otrzymywać sprzedaż w ciągu kilku sekund.
4. Śledzenie stanów musi być włączone dla produktów w Zettle. Produkty wysłane przez moduł mają je automatycznie.

SumUp

1. Wpisz tajny klucz API (sup_sk_...), zapisz i przetestuj połączenie. Kod sprzedawcy jest wykrywany automatycznie.
2. Sprzedaż z SumUp jest wiązana po nazwie pozycji: dokładny indeks lub dokładna nazwa produktu bez kombinacji.

Reguły synchronizacji

U góry zakładki Połączenia:

• Wysyłaj stany PrestaShop do kasy, opcjonalnie zaraz po każdej zmianie.
• Importuj sprzedaż z kasy i odejmuj ją od stanów PrestaShop.
• Przywracaj zwrócone pozycje na stan (Square i Zettle).
• Automatyczne powiązanie po indeksie, po EAN-13 / UPC oraz po nazwie dla SumUp.
• Importuj sprzedaż z kasy od: wcześniejsza sprzedaż jest pomijana. Już zaimportowana sprzedaż nigdy nie jest duplikowana.

Zadanie cykliczne i webhooki

Pulpit pokazuje dwa adresy URL. Zaplanuj pierwszy co 5 minut, a drugi (z full=1) raz na noc:

*/5 * * * * curl -s "https://twoj-sklep.pl/module/dfposconnector/cron?token=TWOJ_TOKEN" >/dev/null
0 3 * * * curl -s "https://twoj-sklep.pl/module/dfposconnector/cron?token=TWOJ_TOKEN&full=1" >/dev/null

Cron importuje nową sprzedaż, wysyła oczekujące stany i wykrywa różnice powstałe poza PrestaShop (import SQL, ERP). Nocna synchronizacja ponownie wysyła wszystkie powiązane stany. Cron i webhooki działają także w trybie konserwacji.

Powiązanie produktów

Zakładka Powiązania produktów:

• Odczytaj katalog Square lub Zettle: automatyczne powiązanie po SKU i kodzie kreskowym.
• Zaproponuj produkty po nazwie: proponuje produkt dla każdej pozostałej pozycji, z wynikiem. Sugestie z wynikiem 90 % lub wyższym można zaakceptować hurtowo, pozostałe pojedynczo.
• Powiązanie ręczne: wyszukaj produkt po nazwie, indeksie lub EAN.
• Wyślij wszystkie stany do kasy lub importuj stany z kasy do PrestaShop (tylko raz, przy konfiguracji, jeśli stany w kasie są wiarygodne).

Wysyłka katalogu do kasy

Zakładka Wysyłka katalogu: wybierz kasę, kategorię (z podkategoriami), wysyłaną cenę (brutto lub netto, bez rabatów) i to, czy uwzględnić tylko aktywne produkty.

1. Sprawdź, co zostanie wysłane najpierw odczytuje katalog kasy i wiąże to, co już istnieje, a potem pokazuje liczbę produktów i wariantów do utworzenia.
2. Utwórz je w kasie wysyła produkty partiami z paskiem postępu. Kombinacje stają się wariantami. Każda utworzona pozycja jest powiązana i otrzymuje swój stan.

Nie są wysyłane: produkty już powiązane w tej kasie, produkty wirtualne, zestawy, zdjęcia i kategorie. Zettle przyjmuje maksymalnie 99 wariantów na produkt.

Kontrola stanów

Zakładka Kontrola stanów odczytuje rzeczywiste ilości z Square lub Zettle i wyświetla różnice względem PrestaShop, od największych. Dla każdego wiersza:

• Wyślij stan PrestaShop: kasa otrzymuje wartość z PrestaShop.
• Przyjmij stan z kasy: PrestaShop otrzymuje wartość z kasy, z ruchem magazynowym.

Zamówienia PrestaShop dla sprzedaży w sklepie

Panel Zamówienia PrestaShop, domyślnie wyłączony. Po włączeniu każda sprzedaż ze wszystkimi powiązanymi pozycjami tworzy zamówienie:

• dedykowany klient ladowy z adresem sklepu;
• darmowy przewoźnik „Sprzedaż w kasie”, nigdy nieoferowany przy składaniu zamówienia;
• ceny z paragonu, a rabat na cały paragon jest rozkładany na wiersze;
• zamówienie z datą sprzedaży i numerem paragonu w notatce wewnętrznej;
• status „Sprzedaż w kasie” (opłacone, dostarczone, bez faktury i e-maila), do zmiany w ustawieniach.

Wtedy to zamówienie odejmuje stan. Podczas tworzenia nie jest wysyłany żaden e-mail. Sprzedaż z niepowiązanymi pozycjami nie dostaje zamówienia: jej powiązane pozycje są odejmowane bezpośrednio.

Dziennik sprzedaży

Zakładka Sprzedaż z kasy wyświetla każdą sprzedaż z wierszami, kasą, lokalizacją, płatnością i ewentualnie linkiem do zamówienia. Filtry: kasa, status (do powiązania, powiązane, zwroty, z zamówieniem), wyszukiwanie po paragonie, pozycji lub lokalizacji, zakres dat. Przycisk Eksportuj CSV eksportuje wybór, jeden wiersz na pozycję.

Alerty e-mail

Panel Alerty e-mail: e-mail jest wysyłany, gdy zaplanowana synchronizacja nie powiedzie się 3 razy z rzędu (najwyżej jeden na 6 godzin), a potem kolejny, gdy znów zadziała. Pozostaw adres pusty, aby użyć adresu sklepu. Przycisk Wyślij alert testowy sprawdza wysyłkę.

Rozwiązywanie problemów

„Magazyn niezainicjowany” w Zettle

Włącz śledzenie stanów dla co najmniej jednego produktu w Zettle lub wyślij produkt z zakładki Wysyłka katalogu.

Odrzucony webhook Square (nieprawidłowy podpis)

Adres URL powiadomień podany w Square musi być identyczny co do znaku z adresem modułu, a klucz podpisu musi należeć do tej subskrypcji.

Stan nie jest wysyłany po zmianie w panelu

PrestaShop nie uruchamia hooków modułu dla pracownika bez uprawnienia „Wyświetl” do tego modułu. Kontrola różnic w cronie wyłapuje te zmiany przy następnym uruchomieniu. Możesz też nadać uprawnienie w Zaawansowane > Zespół > Uprawnienia.

Sprzedaż nie utworzyła zamówienia

Dziennik techniczny podaje przyczynę: niepowiązane pozycje, brak waluty sprzedaży w PrestaShop, ograniczenie przewoźnika na produkcie lub ilość mniejsza niż jedna sztuka. Stan został wtedy odjęty bezpośrednio.

Odinstalowanie

Odinstalowanie usuwa tabele modułu (powiązania, dziennik sprzedaży, kolejkę, dziennik techniczny) i jego ustawienia oraz wyłącza przewoźnika „Sprzedaż w kasie”. Utworzone zamówienia, status zamówienia, klient ladowy i powody ruchów magazynowych zostają zachowane, ponieważ odwołuje się do nich historia.