PS PrestaShop Średnio zaawansowany

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

Instalacja modułu, połączenie Square, Zettle lub SumUp, powiązanie produktów i synchronizacja stanów i sprzedaży między kasą a PrestaShop.

Zaktualizowano Wersja modułu 2.0.0

Zasada działania

Moduł łączy PrestaShop z kasą Square, Zettle by PayPal lub SumUp. Importuje każdą sprzedaż, zwrot towaru i zwrot pieniędzy z kasy do dziennika, aktualizuje stany w wybranym kierunku i może zamienić każdą sprzedaż w zamówienie PrestaShop. Może też wysłać katalog PrestaShop do kasy.

Stany synchronizują się w jednym z trzech kierunków, ustawianym dla każdej kasy:

  • Ze sklepu do kasy: PrestaShop jest systemem nadrzędnym. Sprzedaż w kasie jest odejmowana w PrestaShop, a nowy stan wraca do kasy.
  • Z kasy do sklepu: kasa jest systemem nadrzędnym. PrestaShop przejmuje ilości z kasy przy każdym uruchomieniu crona i przy każdym webhooku stanów.
  • W obu kierunkach: zmiany wprowadzone po każdej stronie od ostatniej synchronizacji są sumowane. Sprzedaż internetowa i sprzedaż w sklepie są liczone po jednym razie.
Pulpit integracji z kasą: zaimportowana sprzedaż, zsynchronizowane stany, błędy, kolejka i ostatnia synchronizacja
Pulpit integracji z kasą

Co obsługuje każda kasa

  • Square: sprzedaż, zwroty towarów i zwroty pieniędzy, stany we wszystkich trzech kierunkach, kilka lokalizacji, wysyłka katalogu ze zdjęciem głównym, podpisane webhooki.
  • Zettle by PayPal: sprzedaż i zwroty pieniędzy, stany we wszystkich trzech kierunkach, wysyłka katalogu, podpisany webhook tworzony przez moduł.
  • SumUp: sprzedaż i zwroty pieniędzy, odejmowane od stanów PrestaShop. Publiczne API SumUp nie udostępnia stanów, katalogu ani webhooka dla sprzedaży w kasie. Import odbywa się przez crona, a stan widoczny w SumUp nie jest aktualizowany.

Moduł nie zastępuje kasy i nie czyni z niej kasy certyfikowanej. Paragony, zamknięcie dnia i obowiązki podatkowe pozostają po stronie Square, Zettle lub SumUp.

Wymagania

  • PrestaShop 1.7.8 do 9.x. Moduł został przetestowany na PrestaShop 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) i 9.1.5 (PHP 8.5).
  • Zadanie cron na hostingu.
  • Sklep działający na HTTPS dla webhooków i połączenia OAuth.
  • Konto Square, Zettle lub SumUp oraz dostęp do jego panelu deweloperskiego, jeśli łączysz się tokenem lub kluczem API.

Instalacja i aktualizacja

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

Aby przejść z wersji 1.x na 2.0.0, wyślij nowy plik ZIP w ten sam sposób. Aktualizacja zachowuje powiązania, dziennik sprzedaży, połączenia, znaczniki importu (żadna sprzedaż nie jest importowana ponownie) i ustawienia. Istniejące adresy URL webhooków pozostają ważne. Aktualizacja dodaje nowe tabele, ponownie szyfruje stare sekrety i usuwa ze statusu „Sprzedaż w kasie” flagę dostawy, która powodowała drugą płatność. Już utworzone zamówienia nie są zmieniane.

Połączenie kas

Zakładka Połączenia pokazuje stan każdej kasy i dostępne funkcje. Każda kasa ma własny kreator. Sekrety są przechowywane w postaci zaszyfrowanej. Nigdy nie są ponownie wyświetlane ani zapisywane w dzienniku. Puste pole zachowuje zapisaną wartość.

Połączenia Square, Zettle i SumUp z dostępnymi funkcjami
Połączenia Square, Zettle i SumUp z dostępnymi funkcjami

Square

  1. Wybierz sposób połączenia. Zalecany jest OAuth: autoryzujesz moduł na swoim koncie Square, a token jest odnawiany automatycznie. Dla jednego sklepu możesz też wkleić osobisty token dostępu.
  2. Przy OAuth wpisz identyfikator i sekret swojej aplikacji Square, a w tej aplikacji zarejestruj wyświetlony adres URL przekierowania. Moduł prosi tylko o niezbędne uprawnienia: odczyt lokalizacji, zamówień, płatności, katalogu, stanów i klientów oraz zapis katalogu i stanów.
  3. Kliknij Połącz z Square, zaakceptuj uprawnienia, a następnie kliknij Przetestuj połączenie.
  4. Wybierz lokalizację, która przechowuje stany, i zaznacz te, z których importowana jest sprzedaż (maksymalnie 10).
  5. Dla natychmiastowego importu dodaj w Webhooks > Subscriptions wyświetlony adres URL powiadomień ze zdarzeniami order.updated, refund.created, inventory.count.updated i oauth.authorization.revoked, a następnie wklej klucz podpisu w module. Adres URL musi być identyczny co do znaku po obu stronach.
Kreator połączenia Square: OAuth, minimalne uprawnienia, lokalizacje
Kreator połączenia Square

Przycisk połączenia OAuth przenosi Cię na stronę autoryzacji kasy, w jej własnym serwisie, a potem z powrotem do modułu. Poniższy zrzut ekranu wykonano w trybie demonstracyjnym, z symulowanym ekranem autoryzacji.

Symulowany ekran autoryzacji OAuth (tryb demonstracyjny)
Symulowany ekran autoryzacji OAuth (tryb demonstracyjny)
Lokalizacje Square: lokalizacja stanów i import sprzedaży
Lokalizacje Square

Zettle by PayPal

  1. Dla jednego sklepu zalecany jest klucz API typu self-hosted: utwórz go w Zettle Developer Portal i wklej wraz z identyfikatorem klienta (client ID). Dostępne jest też połączenie OAuth dla aplikacji partnerskiej, z automatycznym odnawianiem tokenów.
  2. Zapisz, a następnie przetestuj połączenie.
  3. Kliknij Aktywuj webhook. Moduł sam tworzy subskrypcję (PurchaseCreated, InventoryBalanceChanged) i przechowuje jej klucz podpisu w postaci zaszyfrowanej. Zettle wymaga sklepu działającego na HTTPS.
  4. Śledzenie stanów musi być włączone dla produktów w Zettle. Produkty wysłane przez moduł mają je automatycznie.
Kreator połączenia Zettle: klucz API lub OAuth i podpisany webhook
Kreator połączenia Zettle

SumUp

  1. Wklej tajny klucz API (panel SumUp, Developers > API keys) wraz z kodem sprzedawcy albo połącz się przez OAuth.
  2. Przetestuj połączenie. Jeśli brakuje kodu sprzedawcy, jest on odczytywany automatycznie.
  3. SumUp nie wysyła webhooka dla sprzedaży w kasie. Jest ona importowana przez crona co 5 minut. Sprzedaż jest wiązana po indeksie lub po nazwie pozycji.
Kreator połączenia SumUp: klucz API lub OAuth, import przez cron
Kreator połączenia SumUp

Odłączenie kasy

Przycisk Odłącz unieważnia tokeny, gdy kasa na to pozwala (Square, Zettle), i usuwa je z PrestaShop. Powiązania i dziennik sprzedaży zostają zachowane.

Kierunek synchronizacji stanów

W Ustawienia > Stany magazynowe wybierz kierunek synchronizacji stanów dla Square i dla Zettle: ze sklepu do kasy, z kasy do sklepu, w obu kierunkach lub bez synchronizacji stanów. W przypadku SumUp sprzedaż jest odejmowana od stanów PrestaShop, ale kasa nie otrzymuje stanów.

  • Tylko jedna kasa może być nadrzędna dla stanów. Jeśli wybierzesz drugą, moduł ustawi ją na W obu kierunkach.
  • W trybie w obu kierunkach źródło prawdy decyduje o pierwszym wyrównaniu i o konfliktach.
  • Stan zapisany przez moduł nigdy nie jest odsyłany z powrotem, aby uniknąć echa. Gdy kasa sama uwzględnia już własną sprzedaż, import nie odejmuje jej drugi raz.
  • Opcja Wysyłaj od razu po każdej zmianie stanu w PrestaShop wysyła stan natychmiast. W przeciwnym razie jest on wysyłany przy następnym uruchomieniu crona.
Kierunek synchronizacji stanów dla każdej kasy i źródło prawdy
Kierunek synchronizacji stanów dla każdej kasy i źródło prawdy

Powiązanie produktów

Zakładka Powiązania łączy każdą pozycję kasy z produktem lub kombinacją PrestaShop.

  • Odczytaj katalog Square lub Zettle: pozycje są wiązane automatycznie po SKU (indeks produktu lub kombinacji) i po kodzie kreskowym EAN-13 / UPC.
  • Sugestie po nazwie: dla każdej pozostałej pozycji moduł proponuje najbardziej podobny produkt z wynikiem. Sugestie z wynikiem 90 % lub wyższym można zaakceptować za jednym razem, pozostałe pojedynczo. Żadna sugestia nie jest zapisywana bez Twojego zatwierdzenia.
  • Powiązanie ręczne: wyszukaj produkt po nazwie, indeksie lub kodzie EAN.
  • Pozycja sprzedana w kasie, której nie ma w odczytanym katalogu, również pojawia się w kolejce. Możesz ją ukryć, jeśli nie jest sprzedawana online.
Powiązania pozycji kasy z produktami PrestaShop z sugestiami
Powiązania pozycji kasy z produktami PrestaShop z sugestiami

Powiązanie pozycji jednorazowo wyrównuje stan dla już zaimportowanej sprzedaży. Wcześniejsze wiersze sprzedaży zostają połączone z nową regułą.

Wysyłka katalogu do kasy

Zakładka Katalog tworzy produkty PrestaShop w Square lub Zettle: kombinacje jako warianty, ceny, SKU, kod kreskowy, opcjonalnie zdjęcie główne, a następnie stan. 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, wiąże po SKU lub kodzie kreskowym to, co już istnieje, a potem pokazuje liczbę produktów i wariantów do utworzenia.
  2. Zaznacz potwierdzenie, a następnie kliknij Utwórz je w kasie. Produkty są wysyłane partiami z paskiem postępu, a każda utworzona pozycja jest od razu powiązana.
Wysyłka katalogu PrestaShop do kasy z podglądem przed utworzeniem
Wysyłka katalogu PrestaShop do kasy z podglądem przed utworzeniem

Istniejące pozycje w kasie nigdy nie są zmieniane. W Square każda pozycja jest przypisywana do istniejącego podatku Square o tej samej stawce. Żaden podatek nie jest tworzony. Produkty wirtualne i zestawy są pomijane, a kategorie nie są wysyłane. Zettle przyjmuje maksymalnie 99 wariantów na produkt. SumUp nie może otrzymywać produktów przez swoje API.

Kontrola stanów i uzgadnianie

Zakładka Stany magazynowe porównuje stan PrestaShop ze stanem kasy dla każdej powiązanej pozycji i wyświetla różnice. Dla każdej różnicy lub dla zaznaczonych wierszy:

  • Zachowaj PrestaShop: kasa otrzymuje ilość z PrestaShop.
  • Zachowaj kasę: PrestaShop otrzymuje ilość z kasy, z ruchem magazynowym.

Nocna pełna synchronizacja uruchamia uzgadnianie i zachowuje jego raport. Wcześniejsze raporty pozostają dostępne. Importuj wszystkie stany z kasy nadpisuje stan PrestaShop każdego powiązanego produktu. Używaj tej opcji tylko raz, przy konfiguracji, jeśli stany w kasie są najbardziej wiarygodne.

Uzgodnienie stanów między PrestaShop a kasą z raportem różnic
Uzgodnienie stanów między PrestaShop a kasą z raportem różnic

Sprzedaż w kasie

Zakładka Sprzedaż w kasie wyświetla każdy paragon z wierszami, kasą, lokalizacją, płatnością, VAT dla każdego wiersza, napiwkiem i ewentualnie zamówieniem PrestaShop. Filtry: kasa, typ (sprzedaż, zwroty towarów i zwroty pieniędzy, zamówienia PrestaShop), różnice kwot, wyszukiwanie po paragonie, pozycji, lokalizacji lub numerze zamówienia oraz zakres dat. Eksportuj do CSV eksportuje wybór.

Dziennik sprzedaży w kasie z zamówieniem PrestaShop, VAT i napiwkiem
Dziennik sprzedaży w kasie z zamówieniem PrestaShop, VAT i napiwkiem

Import jest idempotentny: już zaimportowana sprzedaż nigdy nie jest duplikowana, nawet jeśli dociera jednocześnie przez kilka webhooków i przez crona. Paragony zarejestrowane w kasie w trybie offline i przesłane później również są importowane. Sprzedaż sprzed daty ustawionej w Importuj sprzedaż w kasie od jest pomijana.

Zamówienia PrestaShop dla sprzedaży w sklepie

W Ustawienia > Zamówienia i zwroty opcja Twórz zamówienie PrestaShop dla każdej sprzedaży w kasie, której wszystkie pozycje są powiązane jest domyślnie wyłączona. Po jej włączeniu:

  • jeden klient przypadkowy na sklep, z adresem sklepu;
  • darmowy przewoźnik „Sprzedaż w kasie”, nigdy nieoferowany przy składaniu zamówienia;
  • metoda płatności „Kasa – Square / Zettle / SumUp”, jedna płatność i zamówienie z datą i godziną sprzedaży;
  • ceny i rabaty z paragonu, rozłożone na wiersze;
  • napiwek poza sumą zamówienia, zapisany w jego notatce;
  • żadnych e-maili, ani do klienta, ani do Ciebie.

Domyślny status to „Sprzedaż w kasie” (opłacone, dostarczone, bez e-maila i bez faktury). Jeśli PrestaShop przeliczy sumę inną niż na paragonie (reguły podatkowe, zaokrąglenia), różnica jest wyświetlana przy sprzedaży i zapisywana w dzienniku.

Ustawienia zamówień, faktur, zwrotów i rozpoznanych klientów
Ustawienia zamówień, faktur, zwrotów i rozpoznanych klientów
  • Zezwalaj na faktury dla zamówień z kasy: domyślnie wyłączone, ponieważ kasa wystawia już paragon. Bez tej opcji status, który generuje fakturę, jest odrzucany. Z tą opcją faktura jest tworzona na podstawie istniejącej płatności i odnotowywana w dzienniku.
  • Zidentyfikowani klienci (Square): zamówienie może zostać przypisane do istniejącego klienta PrestaShop, który ma ten sam adres e-mail co klient Square. Używany jest tylko istniejący klient z adresem. Nie jest tworzony żaden klient ani żaden adres.
Zamówienie PrestaShop utworzone dla sprzedaży w kasie z podsumowaniem paragonu
Zamówienie PrestaShop utworzone dla sprzedaży w kasie z podsumowaniem paragonu

Sprzedaż zawierająca niepowiązane pozycje nie otrzymuje zamówienia. Jej powiązane pozycje są odejmowane bezpośrednio od stanów.

Zwroty towarów i zwroty pieniędzy

Zwroty towarów Square, zwroty pieniędzy Zettle i zwroty pieniędzy SumUp są importowane, również częściowe. Zwrócone pozycje wracają na stan tylko raz, przez wiersz zwrotu. Zwrot pieniędzy bez zwróconej pozycji nie zmienia stanów. Dla pierwotnego zamówienia wybierz:

  • Tylko notatka w zamówieniu (domyślnie);
  • Korekta dla zwróconych pozycji lub zwróconej kwoty;
  • Korekta oraz status „Zwrot pieniędzy” po pełnym zwrocie za zamówienie.
Częściowy zwrot w kasie przywrócony na stan z korektą
Częściowy zwrot w kasie przywrócony na stan z korektą

Zaplanowane zadania i webhooki

Ustawienia > Zaplanowane zadania pokazuje adres URL crona. Wywołuj go co 5 minut, a ten sam adres 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 przetwarza kolejkę webhooków, importuje nową sprzedaż, odnawia tokeny i wysyła oczekujące stany. Dwa przebiegi nigdy się nie nakładają. Przebieg nocny ponownie wysyła wszystkie powiązane stany i generuje raport uzgadniania.

Każdy webhook jest sprawdzany przed przyjęciem:

  • własny klucz URL dla webhooków, odrębny od tokenu crona;
  • podpis kasy;
  • maksymalny rozmiar 256 KB;
  • maksymalny wiek 96 godzin;
  • identyfikator zdarzenia, który nie pojawił się wcześniej.

Moduł odpowiada od razu, a potem przetwarza zdarzenie. Powiadomienie bez podpisu, z błędnym podpisem lub odtworzone ponownie jest odrzucane i zapisywane w dzienniku.

Dziennik techniczny

Zakładka Dziennik wyświetla błędy, ostrzeżenia i informacje, z filtrami po kasie, poziomie, problemie, tekście i dacie. Każdy znany błąd podaje przyczynę i rozwiązanie, z linkiem do odpowiedniego ekranu. Tokeny, klucze i podpisy są maskowane przed zapisaniem. Wpisy są domyślnie przechowywane przez 30 dni (wartość do zmiany), a ostatnie otrzymane zdarzenia webhook są wyświetlane na liście.

Filtrowalny dziennik techniczny z przyczyną i rozwiązaniem każdego błędu
Filtrowalny dziennik techniczny z przyczyną i rozwiązaniem każdego błędu

Alerty

Zakładka Alerty zbiera bieżące problemy wraz z ich przyczyną, rozwiązaniem i przyciskiem Napraw teraz. Alert zamyka się sam, gdy problem znika.

  • synchronizacja nieudana podczas 3 kolejnych przebiegów, a potem wiadomość, gdy znów działa;
  • token odrzucony lub niemożliwy do odnowienia, brak uprawnienia, odrzucone podpisy webhooków;
  • porzucone aktualizacje stanów, cron, który przestał się uruchamiać;
  • pozycje sprzedane w kasie bez produktu PrestaShop;
  • różnice wykryte przez nocne uzgadnianie.
Centrum alertów z przyczyną, rozwiązaniem i e-mailami
Centrum alertów z przyczyną, rozwiązaniem i e-mailami

Alerty mogą być też wysyłane e-mailem, najwyżej jeden na 6 godzin dla każdego alertu. Pozostaw adres pusty, aby użyć adresu sklepu. Wyślij alert testowy sprawdza wysyłkę.

E-mail z alertem integracji z kasą z wyjaśnieniem i rozwiązaniem
E-mail z alertem integracji z kasą z wyjaśnieniem i rozwiązaniem

Rozwiązywanie problemów

„Magazyn nie został zainicjowany” w Zettle

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

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.

Token odrzucony lub brak uprawnienia

Otwórz Połączenia, połącz ponownie kasę za pomocą jej kreatora i zaakceptuj wszystkie wymienione uprawnienia.

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. W kierunku ze sklepu do kasy kontrola różnic w cronie wyłapuje te zmiany przy następnym uruchomieniu. Możesz też nadać to uprawnienie w Zaawansowane > Zespół > Uprawnienia.

Sprzedaż nie utworzyła zamówienia

Dziennik podaje przyczynę: niepowiązane pozycje, waluta sprzedaży nieaktywna w PrestaShop, produkt ograniczony do określonych przewoźników lub ilość mniejsza niż jedna sztuka. Stan został wtedy obsłużony bezpośrednio. Usuń przyczynę dla kolejnych sprzedaży. Przycisk Utwórz zamówienie PrestaShop jest dostępny tylko dla sprzedaży, której stan nie został jeszcze odjęty, aby nigdy nie odjąć go dwa razy.

Suma zamówienia różni się od paragonu

Sprawdź, czy reguła podatkowa PrestaShop dla produktów odpowiada stawce VAT używanej w kasie. Różnica jest wyświetlana przy sprzedaży.

Odinstalowanie

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

Czy ta strona była pomocna?

Nadal utknąłeś? Napisz do wsparcia