# 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…
- Strona:
- Język: pl
- Zaktualizowano: 2026-07-29
- Inne języki: [fr](https://www.datafirefly.com/documentation/axonaut-connector-woocommerce/index.md), [en](https://www.datafirefly.com/en/documentation/axonaut-connector-woocommerce/index.md), [es](https://www.datafirefly.com/es/documentation/axonaut-connector-woocommerce/index.md), [de](https://www.datafirefly.com/de/documentation/axonaut-connector-woocommerce/index.md), [it](https://www.datafirefly.com/it/documentation/axonaut-connector-woocommerce/index.md), [nl](https://www.datafirefly.com/nl/documentation/axonaut-connector-woocommerce/index.md), [pt](https://www.datafirefly.com/pt/documentation/axonaut-connector-woocommerce/index.md)
- Indeks:
**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
Wtyczka nie wymaga żadnych zależności Composera na Twoim serwerze i jest zgodna zarówno z wydajnym magazynem zamówień (HPOS), jak i ze starym magazynem.
## 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.
Klucz jest przechowywany w sposób bezpieczny i po zapisaniu nigdy nie jest wyświetlany otwartym tekstem. Test połączenia używa klucza wpisanego w pole, nawet przed zapisaniem.
## 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.
Przetwarzanie jest asynchroniczne (Action Scheduler): nie wydłuża czasu przejścia przez kasę. Przy tymczasowym błędzie API (429 albo 5xx) wysyłka jest automatycznie ponawiana z rosnącym opóźnieniem, do pięciu razy.
## 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.
Nie modyfikuj ręcznie identyfikatora dokumentu Axonaut zapisanego na zamówieniu: to on gwarantuje, że zamówienie nigdy nie zostanie wysłane dwa razy.