Konektor Axonaut PrestaShop: dokumentacja
Instalacja i konfiguracja konektora Axonaut dla PrestaShop: klucz API, synchronizacja klientów, faktur/ofert, produktów, cron i rozwiązywanie problemów.
Moduł Konektor Axonaut PrestaShop (dfaxonaut, wydawca DataFirefly) automatycznie synchronizuje klientów, zamówienia i produkty między PrestaShop a Axonaut, francuskim oprogramowaniem do zarządzania firmą (CRM, fakturowanie, oferty, przepływy pieniężne). Ten przewodnik obejmuje instalację, konfigurację, działanie synchronizacji oraz rozwiązywanie problemów.
Wymagania
- PrestaShop 8.x lub 9.x, PHP 7.4 do 8.3.
- Aktywne konto Axonaut z dostępem do API v2.
- Twój klucz API Axonaut (userApiKey), dostępny w Axonaut w Paramètres > Développeurs > Clé API.
Instalacja
- W panelu administracyjnym PrestaShop otwórz Moduły > Menedżer modułów > Załaduj moduł i upuść plik ZIP modułu.
- Po instalacji kliknij Konfiguruj.
- Nowa zakładka Axonaut Connector pojawia się także w Zaawansowane: daje dostęp do panelu i dzienników.
Moduł nie instaluje żadnych zależności Composer przy wdrożeniu: autoloader PSR-4 jest wbudowany. Po stronie serwera nie jest wymagane nic więcej.
Konfiguracja
Klucz API i test połączenia
Wklej klucz API Axonaut w pole Klucz API Axonaut i zapisz. Następnie przejdź do panelu (Zaawansowane > Axonaut Connector) i kliknij Testuj połączenie: moduł odpytuje endpoint /me Axonaut i wyświetla powiązane konto, jeśli wszystko jest poprawne.
Synchronizacja klientów
Włącz Synchronizuj klientów, aby każde utworzenie konta, aktualizacja konta lub zmiana adresu tworzyła albo aktualizowała firmę w Axonaut wraz z jej kontaktem. Moduł automatycznie rozpoznaje klientów firmowych (wypełniona nazwa firmy lub VAT UE) i indywidualnych (B2C), a także przekazuje adres, VAT UE i numer przedsiębiorstwa, gdy są dostępne.
Synchronizacja zamówień
Włącz Synchronizuj zamówienia, a następnie wybierz:
- Tryb: tworzenie faktury lub oferty Axonaut.
- Statusy wyzwalające: zamówienie jest wysyłane, gdy po raz pierwszy osiągnie jeden z wybranych statusów (na przykład „Płatność zaakceptowana”).
- Ceny brutto: wysyłanie cen jednostkowych z podatkiem zamiast netto.
Każde przekazane zamówienie zawiera pozycje produktowe (referencja, stawka VAT, ilość) i dodaje koszty wysyłki jako osobną pozycję. Już wysłane zamówienie nigdy nie jest duplikowane.
Synchronizacja produktów (opcjonalna)
Włącz Synchronizuj produkty, aby odzwierciedlać katalog (referencja, nazwa, cena, VAT, krótki opis) w produktach Axonaut. Synchronizacja uruchamia się przy każdej aktualizacji karty produktu.
Zadanie cron
Synchronizacje trafiają do kolejki i są przetwarzane w tle. Lekkie przetwarzanie inline jest próbowane na bieżąco w hookach, ale dla niezawodnego działania zaplanuj zadanie cron wyświetlane w konfiguracji:
curl -s "https://twoj-sklep.pl/index.php?fc=module&module=dfaxonaut&controller=cron&token=TWOJ_TOKEN"Zalecana częstotliwość: co 5 do 15 minut. Cron przetwarza kolejkę, czyści zakończone elementy (7 dni) i stare dzienniki (30 dni). Token można wygenerować ponownie ze strony konfiguracji.
Jeśli wygenerujesz token ponownie, pamiętaj o aktualizacji adresu w harmonogramie zadań (cron serwera, zadanie PrestaShop lub usługa zewnętrzna).
Panel i dzienniki
Zakładka Axonaut Connector pokazuje liczniki (oczekujące / zsynchronizowane / nieudane) oraz pełny dziennik operacji, z możliwością filtrowania i eksportu. Dostępne są dwie akcje:
- Przetwórz kolejkę teraz: wymusza natychmiastowe przetworzenie oczekujących elementów.
- Ponów nieudane: ponownie kolejkuje elementy, które zakończyły się niepowodzeniem po 5 próbach.
Działanie kolejki i ponowień
Każda synchronizowana encja (klient, zamówienie, produkt) trafia do kolejki. W razie błędu przejściowego (sieć, limit API) moduł automatycznie ponawia próbę do 5 razy, po czym oznacza element jako nieudany. Błędy są rejestrowane wraz z komunikatem, co ułatwia diagnozę. Tryb debug dodaje do dzienników pełne ładunki i odpowiedzi API.
Rozwiązywanie problemów
- „Pusty klucz API”: wpisz klucz w konfiguracji przed testem połączenia.
- Błąd HTTP 401/403: klucz API jest nieprawidłowy lub unieważniony. Wygeneruj go ponownie w Axonaut.
- Zamówienia nie są wysyłane: sprawdź, czy osiągnięty status należy do statusów wyzwalających i czy synchronizacja zamówień jest włączona.
- Elementy nieudane: otwórz dziennik, przeczytaj komunikat błędu, usuń przyczynę, a następnie kliknij Ponów nieudane.
- Nic nie synchronizuje się w tle: sprawdź, czy zadanie cron jest zaplanowane i czy token w adresie odpowiada temu z konfiguracji.
Uwagi techniczne
- Używane API: Axonaut REST API v2, uwierzytelnianie nagłówkiem userApiKey.
- Endpointy: /me, /companies, /companies/{id}/employees, /employees/{id}, /products, /invoices, /quotations.
- Tworzone tabele: dfaxonaut_map (powiązania PrestaShop ↔ Axonaut), dfaxonaut_queue (kolejka), dfaxonaut_log (dzienniki).
- Zgodność z multisklepem PrestaShop.