Axonaut-Connector für WooCommerce — Dokumentation
Axonaut-Connector für WooCommerce installieren, verbinden und konfigurieren: Rechnungen oder Angebote, Firmen und Kontakte, Gutschriften, Import der Historie.
Der Axonaut-Connector für WooCommerce verbindet Ihren WooCommerce-Shop mit dem französischen ERP/CRM Axonaut. Er überträgt Ihre Bestellungen automatisch als Rechnungen oder Angebote nach Axonaut, erstellt die zugehörigen Firmen und Kontakte, erzeugt Gutschriften bei Erstattungen und ermöglicht den Import Ihrer Historie. Die gesamte Verarbeitung läuft im Hintergrund über Action Scheduler, ohne Auswirkung auf den Checkout, und bleibt idempotent: Eine Bestellung wird nie zweimal synchronisiert.
Voraussetzungen
- WordPress 6.0 oder höher
- WooCommerce 7.0 oder höher
- PHP 7.4 oder höher
- Ein aktives Axonaut-Konto und dessen API-Schlüssel
Das Plugin benötigt keine Composer-Abhängigkeit auf Ihrem Server und ist mit High-Performance Order Storage (HPOS) sowie mit dem klassischen Speicher kompatibel.
Installation
- Gehen Sie in der WordPress-Verwaltung zu Plugins > Installieren > Plugin hochladen.
- Wählen Sie die ZIP-Datei des Plugins und klicken Sie auf Jetzt installieren.
- Aktivieren Sie das Plugin.
- Ein neues Menü WooCommerce > Axonaut erscheint in der Verwaltung.
Verbindung mit Axonaut
Gehen Sie zu WooCommerce > Axonaut, Registerkarte Einstellungen.
Ihren API-Schlüssel abrufen
Öffnen Sie in Ihrem Axonaut-Konto den Bereich Einstellungen und dann Entwickler. Kopieren Sie Ihren persönlichen API-Schlüssel.
Schlüssel eingeben und testen
Fügen Sie den Schlüssel in das Feld Axonaut-API-Schlüssel ein und klicken Sie auf Verbindung testen. Eine grüne Meldung bestätigt, dass die Verbindung hergestellt ist; eine rote Meldung weist auf einen ungültigen Schlüssel oder ein Netzwerkproblem hin.
Der Schlüssel wird sicher gespeichert und nach dem Speichern nie im Klartext angezeigt. Der Verbindungstest verwendet den im Feld eingegebenen Schlüssel, auch vor dem Speichern.
Konfiguration
Dokumenttyp
Wählen Sie das aus einer Bestellung in Axonaut erstellte Dokument: Rechnung oder Angebot. Diese Wahl gilt für alle synchronisierten Bestellungen.
Auslösestatus
Aktivieren Sie die Bestellstatus, die die Übertragung nach Axonaut auslösen (zum Beispiel Abgeschlossen). Sobald eine Bestellung einen dieser Status erreicht, wird sie zur Synchronisierung in die Warteschlange gestellt. Jede Bestellung wird nur einmal gesendet, auch wenn sie mehrmals den Status wechselt.
Kontakte
Aktivieren Sie diese Option, damit der Käufer als Kontakt (Employee) erstellt und der Firma in Axonaut zugeordnet wird. Die Firma wird immer erstellt: Axonaut benötigt sie, um Rechnungen und Angebote zuzuordnen.
Erstattungen
Aktivieren Sie diese Option, damit eine WooCommerce-Erstattung automatisch eine Gutschrift in Axonaut erzeugt. Dies gilt nur für bereits als Rechnungen synchronisierte Bestellungen.
Zahlungsdatum
Wenn aktiviert, wird das Zahlungsdatum für bereits bezahlte Bestellungen an Axonaut übermittelt.
Produkte
Optional: synchronisiert Ihre WooCommerce-Produkte mit dem Axonaut-Katalog beim Erstellen oder Aktualisieren.
Wartung
Legen Sie die Aufbewahrungsdauer des Protokolls (in Tagen) fest und aktivieren Sie den Debug-Modus, um die vollständigen API-Antworten zur Diagnose zu protokollieren.
Bestellsynchronisierung
Wenn eine Bestellung einen Auslösestatus erreicht, führt der Connector Folgendes aus:
- er ermittelt oder erstellt die zugehörige Axonaut-Firma;
- er erstellt das Dokument Position für Position mit dem für jede Position berechneten USt-Satz;
- er fügt Versandkosten und etwaige Gebühren als eigene Positionen hinzu;
- er übermittelt das Zahlungsdatum, wenn die Bestellung bereits bezahlt ist;
- er erstellt die Rechnung oder das Angebot in Axonaut und speichert dessen ID an der Bestellung.
Die Verarbeitung erfolgt asynchron (Action Scheduler): Sie verlängert die Checkout-Zeit nicht. Bei einem vorübergehenden API-Fehler (429 oder 5xx) wird die Übertragung automatisch mit zunehmender Verzögerung erneut versucht, bis zu fünfmal.
Firmen, Kontakte und EU-USt
Die Axonaut-Firma wird aus den Rechnungsdaten erstellt. Der Connector unterscheidet automatisch Geschäftskunden (Firmenfeld ausgefüllt) von Privatpersonen und übernimmt die aus den wichtigsten EU-USt-Plugins erkannte USt-IdNr.
Deduplizierung
Vor jedem API-Aufruf sucht der Connector nach einer bereits ermittelten Firma: zuerst an der Bestellung selbst, dann am Kundenkonto (falls vorhanden), dann an einer früheren Bestellung mit derselben Rechnungs-E-Mail. Wiederkehrende Käufer werden auch beim Gast-Checkout erkannt, ohne ein Duplikat zu erstellen.
Gutschriften und Erstattungen
Eine WooCommerce-Erstattung, ganz oder teilweise, an einer bereits als Rechnung synchronisierten Bestellung erzeugt automatisch eine Gutschrift in Axonaut, verknüpft mit der ursprünglichen Rechnung.
- Positionsbezogene Erstattungen werden Position für Position übernommen, mit neu berechneter USt.
- Betragsbezogene Erstattungen erzeugen eine einzige globale Gutschriftsposition.
- Erstattete Versandkosten werden als eigene Position hinzugefügt.
Jede Gutschrift ist idempotent: Dieselbe Erstattung erzeugt nie zwei Gutschriften.
Import der Historie
Über die Registerkarte Import können Sie Ihre bestehenden Bestellungen nach Axonaut übertragen.
- Wählen Sie einen Datumsbereich (optional) und die einzuschließenden Bestellstatus.
- Klicken Sie auf Import starten.
- Die Bestellungen werden im Hintergrund über Action Scheduler in Stapeln durchlaufen; bereits synchronisierte Bestellungen werden automatisch übersprungen.
Verfolgen Sie den Fortschritt in der Registerkarte Protokoll.
Sammelaktion in der Bestellliste
Wählen Sie in der Bestellliste (HPOS-Ansicht oder klassische Ansicht) eine oder mehrere Bestellungen aus und wählen Sie dann die Sammelaktion Mit Axonaut synchronisieren. Eine Meldung zeigt an, wie viele Bestellungen in die Warteschlange gestellt und wie viele als bereits synchronisiert übersprungen wurden.
Meta-Box und manuelle Resynchronisierung
Auf dem Bearbeitungsbildschirm einer Bestellung zeigt die Box Axonaut den Sync-Status an: Typ und Nummer des erstellten Dokuments, verknüpfte Firma und Datum. Ist die Bestellung noch nicht synchronisiert, ermöglicht eine Schaltfläche Jetzt synchronisieren eine sofortige Übertragung und zeigt gegebenenfalls den letzten Fehler an.
Aktivitätsprotokoll und Debug-Modus
Die Registerkarte Protokoll zeigt die letzten Vorgänge (Erstellung von Firmen, Rechnungen, Gutschriften, Fehler) mit einem direkten Link zur betreffenden Bestellung. Die Aufbewahrungsdauer ist konfigurierbar. Der Debug-Modus fügt dem Protokoll die vollständigen Details der API-Antworten hinzu, was bei der Diagnose eines Problems hilft.
Produktsynchronisierung (optional)
Wenn die Option aktiviert ist, wird jede Erstellung oder Aktualisierung eines WooCommerce-Produkts in den Axonaut-Katalog übernommen (Name, SKU-Referenz, Preis ohne Steuer, USt-Satz). Die Zuordnung wird gespeichert, um bei späteren Änderungen das richtige Axonaut-Produkt zu aktualisieren.
HPOS-Kompatibilität
Das Plugin deklariert die Kompatibilität mit High-Performance Order Storage. Alle Sync-Metadaten werden über die WooCommerce-Bestell-API gespeichert, was ein identisches Verhalten mit dem klassischen Speicher und mit HPOS gewährleistet.
Hooks für Entwickler
Der Connector stellt mehrere Erweiterungspunkte bereit, um die an Axonaut gesendeten Daten anzupassen:
df_axonaut_company_payload— filtert die Firmendaten vor der Erstellung.df_axonaut_employee_payload— filtert die Kontaktdaten vor der Erstellung.df_axonaut_document_payload— filtert die Daten der Rechnung oder des Angebots.df_axonaut_credit_note_payload— filtert die Daten der Gutschrift.df_axonaut_product_payload— filtert die Daten des synchronisierten Produkts.df_axonaut_vat_meta_keys— passt die Meta-Schlüssel an, in denen die USt-IdNr. gesucht wird.df_axonaut_order_synced— Aktion, die nach erfolgreicher Synchronisierung einer Bestellung ausgelöst wird.df_axonaut_refund_synced— Aktion, die nach Erstellung einer Gutschrift ausgelöst wird.
Fehlerbehebung
Der Verbindungstest schlägt fehl
Prüfen Sie, ob der API-Schlüssel korrekt und in Ihrem Axonaut-Konto aktiv ist und ob Ihr Server die Axonaut-API über ausgehendes HTTPS erreichen kann.
Eine Bestellung wird nicht synchronisiert
Stellen Sie sicher, dass ihr Status zu den Auslösestatus gehört und dass sie noch nicht synchronisiert wurde. Prüfen Sie das Protokoll und die Axonaut-Box der Bestellung auf den letzten Fehler. Überprüfen Sie außerdem, ob die Action-Scheduler-Warteschlange läuft (WooCommerce > Status > Geplante Aktionen).
Eine Gutschrift wurde nicht erstellt
Gutschriften werden nur für bereits als Rechnung (nicht als Angebot) synchronisierte Bestellungen und bei aktivierter Erstattungsoption erzeugt.
Ändern Sie die an einer Bestellung gespeicherte Axonaut-Dokument-ID nicht manuell: Sie gewährleistet, dass eine Bestellung nie zweimal gesendet wird.