Integracja z PrestaShop

PrestaShop — przegląd

Integracja z PrestaShop (popularny CMS e-commerce open-source) pozwala automatycznie importować zamówienia ze sklepu i wystawiać faktury VAT bez ręcznej pracy.

Dostępność: pakiet MAX.

---

Co integracja umożliwia?

• Auto-import zamówień z PrestaShop do panelu Mobilna Faktura
• Auto-faktury VAT dla każdego zamówienia (lub wybranych)
• Lista kupujących w bazie kontrahentów
• Sync stanów magazynowych — zmiana stanu w panelu = aktualizacja stanu w PrestaShop
• Statusy zamówień — synchronizacja statusów (nowe / opłacone / wysłane / dostarczone)
• Multi-shop — kilka sklepów PrestaShop na jednym koncie

---

Konfiguracja w PrestaShop

Krok 1: Włącz Webservice

1. Panel admina PrestaShop → Zaawansowane → Webservice
2. Włącz Webservice (radio button “Tak”)
3. Włącz CGI dla PHP (jeśli wymagane przez hosting)

Krok 2: Wygeneruj klucz API

1. Webservice → + Dodaj klucz
2. Klucz: kliknij “Generate” — dostajesz np. XYZ123ABC456...
3. Opis: “Mobilna Faktura - integracja”
4. Status: Aktywny
5. Uprawnienia (zaznacz):
   • customers (klienci)
   • orders (zamówienia)
   • products (produkty)
   • stock_availables (stany magazynowe)
   • addresses (adresy)
6. Zapisz

Krok 3: Sprawdź URL Webservice

Adres ma format: https://twojsklep.pl/api/

Test: otwórz https://twojsklep.pl/api/orders?ws_key=KLUCZ w przeglądarce — powinno zwrócić XML z zamówieniami.

---

Konfiguracja w panelu Mobilna Faktura

1. Sklepy → PrestaShop → + Dodaj sklep
2. Wypełnij:

Pole	Wartość
Nazwa sklepu	”Sklep główny” (do identyfikacji)
URL Webservice	https://twojsklep.pl/api/
Klucz API	(wklejony z PrestaShop)
Auto-faktury	Tak / Nie
Sync stanów	Tak / Nie
Częstotliwość	Co 5 / 15 / 30 / 60 min

3. Zapisz → system testuje połączenie
4. Jeśli OK — pojawia się komunikat ”✅ Połączono z PrestaShop”

---

Import zamówień

Auto-import (cron)

Zgodnie z konfiguracją (np. co 15 min):

1. System pyta PrestaShop o nowe zamówienia (od ostatniego sprawdzenia)
2. Dla każdego nowego zamówienia:
   • Sprawdza czy klient jest w bazie (po e-mail/NIP) — jeśli nie, dodaje
   • Tworzy zamówienie ZK w panelu (status = z PrestaShop, np. “Płatność przyjęta”)
   • Jeśli włączone “Auto-faktury” → wystawia fakturę VAT

Ręczny import

1. Sklepy → PrestaShop → Sprawdź teraz
2. Lista nowych zamówień
3. Wybór które zaimportować (checkbox) → Importuj wybrane

---

Auto-faktury VAT

Dla każdego importowanego zamówienia system automatycznie wystawia fakturę:

• Numer faktury z własnej numeracji (panel Mobilna Faktura — nie PrestaShop)
• Pozycje mapowane: produkt PrestaShop → towar w panelu (po SKU lub EAN)
• Stawka VAT wg karty produktu w panelu
• Adres dostawy + adres rozliczeniowy z zamówienia PrestaShop
• Dane do faktury (NIP, nazwa firmy) jeśli klient zaznaczył “Faktura na firmę”
• Wysyłka e-mail do klienta (PDF) + opcjonalnie do KSeF

---

Synchronizacja stanów magazynowych

Z panelu do PrestaShop (cron co 5 min)

Każda zmiana stanu w panelu (sprzedaż, PZ, MM, korekta) → auto-aktualizacja w PrestaShop:

1. System śledzi zmiany stanów w panelu
2. Co 5 minut wysyła batch update do PrestaShop
3. Nowy stan widoczny w sklepie (frontend + admin)

Z PrestaShop do panelu (przy imporcie zamówień)

Każde zamówienie w PrestaShop → auto-zmniejszenie stanu w panelu (przez generowanie WZ).

→ Brak nadsprzedaży (oversold) — gdy w sklepie zostanie 0, klient nie kupi.

---

Mapowanie produktów

Najważniejsza sprawa — jak system rozpoznaje że “Produkt 123 z PrestaShop” = “Towar XYZ z panelu”:

Mapowanie po SKU

1. W PrestaShop każdy produkt ma SKU (referencja)
2. W panelu każdy towar ma Symbol/SKU
3. Identyczne SKU → automatyczne dopasowanie

Mapowanie ręczne

Jeśli SKU różne (np. produkt importowany z różnych źródeł):

1. Sklepy → PrestaShop → Mapowanie produktów
2. Lista wszystkich produktów PrestaShop + dropdown “Towar w panelu”
3. Wybierz właściwy z listy → zapisz

Auto-tworzenie nowych

Jeśli produkt z PrestaShop nie ma odpowiednika w panelu:

• Opcja “Auto-tworzenie towarów” w ustawieniach
• Każdy nowy produkt z PrestaShop → automatycznie dodawany do magazynu (nazwa, cena, opis, zdjęcie)

---

Multi-shop (wiele sklepów PrestaShop)

Jeśli prowadzisz kilka sklepów (np. PrestaShop dla różnych kategorii lub krajów):

1. Sklepy → PrestaShop → + Dodaj sklep
2. Każdy sklep z osobnym URL + kluczem API
3. Każdy sklep z niezależną konfiguracją (auto-faktury, sync stanów, mapowanie)
4. Faktury z różnych sklepów → wszystkie w panelu, ale z oznaczeniem źródła (kolumna “Sklep”)

---

Statusy zamówień

System synchronizuje statusy:

Status PrestaShop	Status w panelu
Awaiting bank payment	Nowe (niepopłacone)
Payment accepted	Opłacone (faktura wystawiona)
Preparation in progress	W realizacji
Shipped	Wysłane
Delivered	Dostarczone
Canceled	Anulowane (faktura korygująca)

Zmiana statusu w PrestaShop → automatycznie w panelu (i odwrotnie - opcjonalnie).

---

Troubleshooting

Błąd “401 Unauthorized”

• Sprawdź klucz API (czy aktywny w PrestaShop)
• Sprawdź czy klucz ma uprawnienia do customers, orders, products

Błąd “Connection refused”

• Sprawdź URL (czy /api/ na końcu)
• Sprawdź czy Webservice włączony w PrestaShop
• Sprawdź firewall (czy hosting nie blokuje)

Zamówienia nie importują się

• Sprawdź datę ostatniej synchronizacji (czy cron działa)
• W logach ~/logs/prestashop_sync.log znajdź szczegóły błędów
• Spróbuj ręcznej synchronizacji (przycisk Sprawdź teraz)

Stany się różnią (PrestaShop vs panel)

• Wymuś pełną synchronizację (Sklepy → PrestaShop → Sync wszystko)
• Sprawdź czy w PrestaShop nie ma zamówień nieprzeimportowanych do panelu (mogły zmniejszyć stan tam, ale nie tu)

---

Korzyści

• Zero ręcznego przepisywania zamówień ze sklepu
• Auto-faktury VAT = oszczędność godzin tygodniowo
• Sync stanów = brak nadsprzedaży
• Multi-shop = jeden panel dla kilku sklepów
• Integracja z księgowością — auto-KPiR, JPK, deklaracje