Konektor Sellsy PrestaShop: dokumentacja

Prezentacja

Konektor Sellsy od DataFirefly łączy Twój sklep PrestaShop z Sellsy, francuskim rozwiązaniem SaaS do CRM, fakturowania i zarządzania. Automatycznie synchronizuje klientów, produkty, zamówienia, faktury, płatności i korekty z PrestaShop do Sellsy przez API Sellsy v2. Synchronizacja jest jednokierunkowa: PrestaShop → Sellsy.

Instalacja

1. W panelu administracyjnym PrestaShop przejdź do Moduły > Menedżer modułów.
2. Kliknij Załaduj moduł i prześlij plik dfsellsy.zip.
3. Po instalacji kliknij Konfiguruj.

Moduł tworzy dwie tabele (dfsellsy_link dla powiązań PrestaShop ↔ Sellsy, dfsellsy_log dla dziennika) oraz zakładkę „Sellsy Connector” w menu Moduły.

Utworzenie dostępu API w Sellsy

Konektor korzysta z uwierzytelniania OAuth2 (client credentials) API v2.

1. W Sellsy otwórz Menu > Ustawienia > Portal deweloperski.
2. W zakładce API V2 kliknij Utwórz dostęp API.
3. Wybierz współpracownika powiązanego z dostępem (najlepiej administratora, aby mieć wszystkie uprawnienia) i zaznacz potrzebne scope’y (klienci, dokumenty, katalog, płatności).
4. Zapisz, a następnie skopiuj Client ID i Client Secret.

Konfiguracja modułu

Na stronie konfiguracji modułu wypełnij:

• Client ID i Client Secret: dane OAuth2 utworzone w Sellsy. Zostaw pole secret puste, aby zachować już zapisaną wartość.
• Synchronizuj klientów: tworzy/aktualizuje kontrahenta Sellsy przy rejestracji i aktualizacji klienta.
• Synchronizuj zamówienia: przekształca zamówienia w dokumenty Sellsy.
• Typ dokumentu Sellsy dla zamówień: faktura lub zamówienie zakupu.
• Wyzwalacz synchronizacji zamówień: przy potwierdzeniu płatności lub przy zatwierdzeniu zamówienia.
• Zatwierdzaj dokumenty Sellsy: automatycznie zatwierdza faktury i korekty po utworzeniu (w przeciwnym razie pozostają w Sellsy jako szkice).
• Rejestruj płatności: zapisuje wpłaty PrestaShop na fakturze Sellsy (tylko w trybie faktury).
• Synchronizuj zwroty jako korekty: tworzy korektę Sellsy przy każdej korekcie PrestaShop i wiąże ją z fakturą pierwotną.
• Synchronizuj produkty: wypycha katalog do pozycji Sellsy.

Użyj przycisku Testuj połączenie API, aby zweryfikować dane dostępowe przed włączeniem synchronizacji.

Synchronizacja klientów

Przy rejestracji lub aktualizacji klienta moduł tworzy albo aktualizuje kontrahenta Sellsy. Klienci z wypełnionym polem „firma” stają się w Sellsy firmami (z numerem SIRET, jeśli dostępny), pozostali osobami prywatnymi. Wyszukiwanie po adresie e-mail zapobiega duplikatom, a główny adres rozliczeniowy jest przekazywany przy utworzeniu.

Synchronizacja zamówień

W zależności od wybranego wyzwalacza zatwierdzone lub opłacone zamówienie staje się dokumentem Sellsy zawierającym pozycje produktowe, koszty wysyłki i rabaty koszykowe (jako pozycja ujemna). Stawki VAT PrestaShop są automatycznie mapowane na podatki Sellsy. Każde zamówienie jest synchronizowane tylko raz (idempotencja).

Faktury, zatwierdzanie i płatności

Gdy typem dokumentu jest „faktura”:

• jeśli opcja Zatwierdzaj dokumenty jest aktywna, faktura jest zatwierdzana automatycznie po utworzeniu;
• jeśli opcja Rejestruj płatności jest aktywna, każda wpłata PrestaShop jest zapisywana na fakturze bez duplikatów, łącznie z płatnościami częściowymi i wielokrotnymi;
• jeśli zamówienie zostało utworzone przy zatwierdzeniu, a płatność nadejdzie później, moduł rejestruje tylko nowe wpłaty na istniejącej fakturze.

Korekty przy zwrotach

Przy wygenerowaniu korekty w PrestaShop moduł tworzy korektę Sellsy na podstawie zwracanych pozycji (produkty i wysyłka), zatwierdza ją, jeśli opcja jest aktywna, a następnie wiąże z fakturą pierwotną, o ile ta istnieje po stronie Sellsy.

Synchronizacja produktów

Synchronizacja produktów jest opcjonalna. Po włączeniu produkty są wypychane do katalogu Sellsy przy tworzeniu i aktualizacji. Możesz też uruchomić synchronizację masową ze strony „Sellsy Connector” (przetwarzanie partiami po 20).

Zadania zaplanowane (cron)

Wbudowany cron pozwala nadrobić to, co mogłoby umknąć hookom działającym w czasie rzeczywistym. Zaplanuj adresy wyświetlane na stronie konfiguracji:

• .../module/dfsellsy/cron?token=TWOJ_TOKEN&job=orders
• ...&job=customers
• ...&job=products
• ...&job=retry (ponawia encje z błędem, jeszcze niepowiązane)

Parametr limit (domyślnie 20, maks. 100) kontroluje rozmiar partii na wykonanie.

Dziennik synchronizacji

Strona „Sellsy Connector” wyświetla filtrowany dziennik (po encji i statusie) każdej operacji, wraz z komunikatem zwróconym przez Sellsy w razie błędu. Przycisk Ponów błędy ponawia nieudane operacje jednym kliknięciem.

Rozwiązywanie problemów

• „Połączenie nieudane”: sprawdź Client ID / Client Secret oraz czy potrzebne scope’y są zaznaczone w Sellsy.
• Błąd pola dokumentu (HTTP 422): niektóre konta Sellsy mają specyficzne wymagania (adnotacje e-fakturowania, pola obowiązkowe). Sprawdź komunikat w dzienniku, aby zidentyfikować problematyczne pole.
• Duplikaty kontrahentów: moduł wyszukuje po adresie e-mail przed utworzeniem; upewnij się, że e-mail klienta jest wypełniony.
• Nic się nie synchronizuje: sprawdź, czy odpowiednie opcje są aktywne, i przetestuj połączenie API.