Konektor Axonaut dla WooCommerce: dokumentacja

Konektor Axonaut dla WooCommerce łączy Twój sklep WooCommerce z francuskim ERP/CRM Axonaut. Automatycznie wypycha zamówienia do Axonaut jako faktury albo oferty, tworzy odpowiadające im firmy i kontakty, generuje faktury korygujące przy zwrotach i pozwala zaimportować historię. Całe przetwarzanie odbywa się w tle przez Action Scheduler, bez wpływu na checkout, i pozostaje idempotentne: zamówienie nigdy nie jest synchronizowane dwa razy.

Wymagania

• WordPress 6.0 lub nowszy
• WooCommerce 7.0 lub nowszy
• PHP 7.4 lub nowszy
• Aktywne konto Axonaut i jego klucz API

Instalacja

1. W administracji WordPressa przejdź do Wtyczki > Dodaj nową > Wyślij wtyczkę na serwer.
2. Wybierz plik ZIP wtyczki i kliknij Zainstaluj teraz.
3. Włącz wtyczkę.
4. W administracji pojawia się nowe menu WooCommerce > Axonaut.

Połączenie z Axonaut

Przejdź do WooCommerce > Axonaut, zakładka Ustawienia.

Pobranie klucza API

Na swoim koncie Axonaut otwórz sekcję Paramètres, a następnie Développeurs. Skopiuj swój osobisty klucz API.

Wpisanie i przetestowanie klucza

Wklej klucz w pole Klucz API Axonaut, a następnie kliknij Testuj połączenie. Zielony komunikat potwierdza nawiązanie połączenia; czerwony wskazuje nieprawidłowy klucz albo problem sieciowy.

Konfiguracja

Typ dokumentu

Wybierz dokument tworzony w Axonaut z zamówienia: Faktura albo Oferta. Ten wybór dotyczy wszystkich synchronizowanych zamówień.

Statusy wyzwalające

Zaznacz statusy zamówień, które wyzwalają wysyłkę do Axonaut (na przykład Zrealizowane). Gdy tylko zamówienie osiągnie jeden z tych statusów, trafia do kolejki synchronizacji. Każde zamówienie wysyłane jest tylko raz, nawet jeśli kilkukrotnie zmieni status.

Kontakty

Włącz tę opcję, aby kupujący był tworzony jako kontakt (employee) przypięty do firmy w Axonaut. Firma tworzona jest zawsze: Axonaut potrzebuje jej do przypinania faktur i ofert.

Zwroty

Włącz tę opcję, aby zwrot w WooCommerce automatycznie generował fakturę korygującą w Axonaut. Dotyczy to wyłącznie zamówień już zsynchronizowanych jako faktura.

Data płatności

Gdy jest włączona, data płatności przekazywana jest do Axonaut dla zamówień już opłaconych.

Produkty

Opcja fakultatywna: synchronizuje Twoje produkty WooCommerce do katalogu Axonaut przy ich tworzeniu albo aktualizacji.

Konserwacja

Ustaw czas retencji dziennika (w dniach) i włącz tryb debug, aby logować pełne odpowiedzi API na potrzeby diagnostyki.

Synchronizacja zamówień

Gdy zamówienie osiąga status wyzwalający, konektor:

1. odnajduje albo tworzy odpowiadającą firmę Axonaut;
2. buduje dokument pozycja po pozycji, ze stawką VAT liczoną dla każdej pozycji;
3. dodaje koszty wysyłki i ewentualne opłaty jako dedykowane pozycje;
4. przekazuje datę płatności, jeśli zamówienie jest już opłacone;
5. tworzy fakturę albo ofertę w Axonaut i zapisuje jej identyfikator na zamówieniu.

Firmy, kontakty i VAT wewnątrzwspólnotowy

Firma Axonaut tworzona jest z danych rozliczeniowych. Konektor automatycznie odróżnia klientów firmowych (wypełnione pole firmy) od osób prywatnych i przepisuje numer VAT wewnątrzwspólnotowy wykryty z głównych wtyczek VAT UE.

Deduplikacja

Przed każdym wywołaniem API konektor szuka już rozpoznanej firmy: najpierw na samym zamówieniu, potem na koncie klienta (jeśli istnieje), a następnie na wcześniejszym zamówieniu z tym samym e-mailem rozliczeniowym. Klienci powracający, nawet w zamówieniu gościnnym, są dzięki temu rozpoznawani bez tworzenia duplikatów.

Faktury korygujące i zwroty

Zwrot w WooCommerce, całkowity albo częściowy, na zamówieniu już zsynchronizowanym jako faktura automatycznie generuje fakturę korygującą w Axonaut, powiązaną z fakturą źródłową.

• Zwroty per pozycja są odwzorowywane pozycja po pozycji, z przeliczonym VAT.
• Zwroty kwotowe tworzą jedną globalną pozycję korekty.
• Zwrócone koszty wysyłki dodawane są jako dedykowana pozycja.

Każda korekta jest idempotentna: ten sam zwrot nigdy nie generuje dwóch faktur korygujących.

Import historii

Zakładka Import pozwala wypchnąć istniejące zamówienia do Axonaut.

1. Wybierz zakres dat (opcjonalny) i statusy zamówień do objęcia.
2. Kliknij Rozpocznij import.
3. Zamówienia przetwarzane są partiami w tle przez Action Scheduler; zamówienia już zsynchronizowane są automatycznie pomijane.

Postęp śledzisz w zakładce Dziennik.

Akcja masowa na liście zamówień

Z listy zamówień (ekran HPOS albo stary ekran) zaznacz jedno lub więcej zamówień, a następnie wybierz akcję masową Synchronizuj do Axonaut. Komunikat wskazuje liczbę zamówień dodanych do kolejki i tych pominiętych, bo już zsynchronizowanych.

Meta box i ręczna resynchronizacja

Na karcie zamówienia box Axonaut pokazuje stan synchronizacji: typ i numer utworzonego dokumentu, powiązaną firmę i datę. Jeśli zamówienie nie jest jeszcze zsynchronizowane, przycisk Synchronizuj teraz pozwala na natychmiastową wysyłkę, z ewentualnym wyświetleniem ostatniego błędu.

Dziennik aktywności i tryb debug

Zakładka Dziennik pokazuje ostatnie operacje (utworzenia firm, faktur, korekt, błędy), z bezpośrednim linkiem do danego zamówienia. Czas retencji jest konfigurowalny. Tryb debug dopisuje do dziennika pełne szczegóły odpowiedzi API, przydatne przy diagnozowaniu problemu.

Synchronizacja produktów (opcjonalna)

Gdy opcja jest włączona, każde utworzenie albo aktualizacja produktu WooCommerce odbija się w katalogu Axonaut (nazwa, SKU, cena netto, stawka VAT). Powiązanie jest zapamiętywane, aby przy kolejnych zmianach aktualizować właściwy produkt Axonaut.

Zgodność z HPOS

Wtyczka deklaruje zgodność z wydajnym magazynem zamówień (High-Performance Order Storage). Wszystkie metadane synchronizacji zapisywane są przez API zamówień WooCommerce, co gwarantuje identyczne działanie na starym magazynie i na HPOS.

Hooki dla deweloperów

Konektor udostępnia kilka punktów rozszerzeń do dostosowania danych wysyłanych do Axonaut:

• df_axonaut_company_payload: filtruje dane firmy przed utworzeniem.
• df_axonaut_employee_payload: filtruje dane kontaktu przed utworzeniem.
• df_axonaut_document_payload: filtruje dane faktury albo oferty.
• df_axonaut_credit_note_payload: filtruje dane faktury korygującej.
• df_axonaut_product_payload: filtruje dane synchronizowanego produktu.
• df_axonaut_vat_meta_keys: dostosowuje klucze meta, w których szukany jest numer VAT.
• df_axonaut_order_synced: akcja wyzwalana po udanej synchronizacji zamówienia.
• df_axonaut_refund_synced: akcja wyzwalana po utworzeniu faktury korygującej.

Rozwiązywanie problemów

Test połączenia się nie udaje

Sprawdź, czy klucz API jest poprawny i aktywny na Twoim koncie Axonaut oraz czy serwer może osiągnąć API Axonaut wychodzącym HTTPS.

Zamówienie nie jest synchronizowane

Upewnij się, że jego status należy do statusów wyzwalających i że nie zostało już zsynchronizowane. Sprawdź dziennik oraz box Axonaut na zamówieniu, gdzie widnieje ostatni błąd. Zweryfikuj też, czy kolejka Action Scheduler działa (WooCommerce > Status > Zaplanowane akcje).

Faktura korygująca nie powstała

Korekty generowane są wyłącznie dla zamówień już zsynchronizowanych jako faktura (nie oferta) i gdy opcja zwrotów jest włączona.