Axonaut PrestaShop Connector — Dokumentation

Das Modul Axonaut PrestaShop Connector (dfaxonaut, von DataFirefly) synchronisiert Ihre Kunden, Bestellungen und Produkte automatisch zwischen PrestaShop und Axonaut, der französischen Unternehmenssoftware (CRM, Rechnungsstellung, Angebote, Liquidität). Dieser Leitfaden behandelt Installation, Konfiguration, Funktionsweise der Synchronisationen und Fehlerbehebung.

Voraussetzungen

• PrestaShop 8.x oder 9.x, PHP 7.4 bis 8.3.
• Ein aktives Axonaut-Konto mit Zugriff auf die API v2.
• Ihr Axonaut-API-Schlüssel (userApiKey), in Axonaut unter Einstellungen > Entwickler > API-Schlüssel.

Installation

1. Öffnen Sie im PrestaShop-Backoffice Module > Modul-Manager > Modul hochladen und legen Sie die ZIP-Datei des Moduls ab.
2. Klicken Sie nach der Installation auf Konfigurieren.
3. Unter Erweiterte Parameter erscheint zudem ein neuer Reiter Axonaut Connector: Er gibt Zugriff auf das Dashboard und die Protokolle.

Konfiguration

API-Schlüssel und Verbindungstest

Fügen Sie Ihren Axonaut-API-Schlüssel in das Feld Axonaut-API-Schlüssel ein und speichern Sie. Gehen Sie dann zum Dashboard (Erweiterte Parameter > Axonaut Connector) und klicken Sie auf Verbindung testen: Das Modul ruft den /me-Endpunkt von Axonaut auf und zeigt das verknüpfte Konto an, wenn alles korrekt ist.

Kundensynchronisation

Aktivieren Sie Kunden synchronisieren, damit jede Kontoerstellung, Kontoaktualisierung oder Adressänderung eine Axonaut-Firma samt Kontakt anlegt oder aktualisiert. Das Modul erkennt automatisch Geschäftskunden (Firmenname oder gesetzte USt-IdNr.) und Privatkunden (B2C) und überträgt die Adresse, die USt-IdNr. und die Unternehmensnummer, sofern verfügbar.

Bestellsynchronisation

Aktivieren Sie Bestellungen synchronisieren und wählen Sie dann:

• Modus: eine Axonaut-Rechnung oder ein Angebot erstellen.
• Auslösende Status: Die Bestellung wird beim ersten Erreichen eines der ausgewählten Status übertragen (zum Beispiel „Zahlung akzeptiert“).
• Preise brutto: Einzelpreise inklusive Steuer statt netto senden.

Jede übertragene Bestellung übernimmt die Produktzeilen (Referenz, USt-Satz, Menge) und fügt den Versand als eigene Zeile hinzu. Eine bereits übertragene Bestellung wird nie dupliziert.

Produktsynchronisation (optional)

Aktivieren Sie Produkte synchronisieren, um Ihren Katalog (Referenz, Name, Preis, USt, Kurzbeschreibung) in die Axonaut-Produkte zu spiegeln. Die Synchronisation wird bei jeder Aktualisierung eines Produkts ausgelöst.

Cron-Aufgabe

Synchronisationen werden in die Warteschlange gestellt und im Hintergrund verarbeitet. Ein leichter Inline-Versuch läuft spontan innerhalb der Hooks, aber für einen zuverlässigen Betrieb planen Sie die in der Konfiguration angezeigte Cron-Aufgabe:

curl -s "https://ihr-shop.tld/index.php?fc=module&module=dfaxonaut&controller=cron&token=IHR_TOKEN"

Empfohlene Frequenz: alle 5 bis 15 Minuten. Der Cron verarbeitet die Warteschlange, bereinigt abgeschlossene Elemente (7 Tage) und alte Protokolle (30 Tage). Der Token kann über die Konfigurationsseite neu generiert werden.

Dashboard und Protokolle

Der Reiter Axonaut Connector zeigt die Zähler (offen / synchronisiert / fehlgeschlagen) und das vollständige, filter- und exportierbare Vorgangsprotokoll. Zwei Aktionen stehen zur Verfügung:

• Warteschlange jetzt verarbeiten: erzwingt die sofortige Verarbeitung offener Elemente.
• Fehlgeschlagene erneut versuchen: stellt nach 5 Versuchen fehlgeschlagene Elemente erneut in die Warteschlange.

Funktionsweise von Warteschlange und Retries

Jede zu synchronisierende Entität (Kunde, Bestellung, Produkt) wird in eine Warteschlange gelegt. Bei einem temporären Fehler (Netzwerk, API-Kontingent) versucht das Modul es automatisch bis zu 5-mal und markiert das Element dann als fehlgeschlagen. Fehler werden mit ihrer Meldung protokolliert, was die Diagnose erleichtert. Der Debug-Modus fügt die vollständigen API-Payloads und -Antworten zu den Protokollen hinzu.

Fehlerbehebung

• „API-Schlüssel ist leer“: Geben Sie den Schlüssel in der Konfiguration ein, bevor Sie die Verbindung testen.
• HTTP-Fehler 401/403: Der API-Schlüssel ist ungültig oder widerrufen. Generieren Sie ihn in Axonaut neu.
• Bestellungen werden nicht übertragen: Prüfen Sie, ob der erreichte Status zu den auslösenden Status gehört und ob die Bestellsynchronisation aktiviert ist.
• Fehlgeschlagene Elemente: Öffnen Sie das Protokoll, um die Fehlermeldung zu lesen, beheben Sie die Ursache und klicken Sie auf Fehlgeschlagene erneut versuchen.
• Nichts synchronisiert im Hintergrund: Prüfen Sie, ob die Cron-Aufgabe geplant ist und der URL-Token mit dem in der Konfiguration übereinstimmt.

Technische Hinweise

• Verwendete API: Axonaut REST API v2, Authentifizierung über den userApiKey-Header.
• Endpunkte: /me, /companies, /companies/{id}/employees, /employees/{id}, /products, /invoices, /quotations.
• Erstellte Tabellen: dfaxonaut_map (Zuordnung PrestaShop ↔ Axonaut), dfaxonaut_queue (Warteschlange), dfaxonaut_log (Protokolle).
• PrestaShop-Multishop-kompatibel.