# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-10-07
- Inne języki: [fr](https://www.datafirefly.com/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md), [pt](https://www.datafirefly.com/pt/documentation/pos-stock-sync-square-zettle-sumup-prestashop/index.md)
- Indeks:
## 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).
Nieznany wiersz sprzedaży można też powiązać z dziennika sprzedaży: reguła zostaje zapisana, a stany już zaimportowanej sprzedaży są wyrównywane.
## 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.
Zwroty nie zmieniają zamówień. Zwrócone pozycje wracają na stan, a do notatki wewnętrznej pierwotnego zamówienia dodawany jest wiersz.
## 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.