Etsy-Synchronisation für PrestaShop — Dokumentation

Etsy-Synchronisation verbindet Ihren PrestaShop-Shop mit Ihrem Etsy-Shop: Sie exportiert Ihre Produkte als Angebote, hält Ihren Lagerbestand synchron und importiert Ihre Etsy-Bestellungen automatisch in PrestaShop. Diese Anleitung behandelt Installation, Verbindung zu Etsy, Einstellungen und den täglichen Betrieb.

Voraussetzungen

• Ein funktionierender PrestaShop-8- oder -9-Shop mit Zugang zum Back-Office.
• Ein aktiver Etsy-Shop.
• Eine im Etsy-Entwicklerportal registrierte App (kostenlos) — siehe nächster Schritt.
• Ein Server-Cron (oder ein externer Cron-Dienst), um Lagersynchronisation und Bestellimport zu automatisieren.

Installation

1. Gehen Sie im PrestaShop-Back-Office zu Module > Modul-Manager.
2. Klicken Sie auf Modul hochladen und legen Sie die Datei dfetsy.zip ab.
3. Klicken Sie nach der Installation auf Konfigurieren. Sie gelangen zur Verwaltungsseite des Moduls, gegliedert in Reiter: Verbindung, Produkte, Bestellungen, Einstellungen, Cron, Protokolle.

Ihre Etsy-App erstellen

Das Modul verbindet sich über Ihre eigene Entwickler-App mit Etsy. Der Vorgang ist kostenlos und dauert wenige Minuten.

1. Gehen Sie zum Etsy-Entwicklerportal (etsy.com/developers) und erstellen Sie eine neue Anwendung.
2. Etsy stellt Ihnen einen API-Schlüssel bereit, den sogenannten Keystring (Ihre Client-ID).
3. Geben Sie in der Konfiguration Ihrer Etsy-App die Weiterleitungs-URL (Callback-URL) genau so an, wie sie im Reiter Verbindung des Moduls angezeigt wird.

Verbindung zu Etsy

Im Reiter Verbindung:

1. Fügen Sie Ihren Keystring in das Feld ein und klicken Sie auf Speichern.
2. Klicken Sie auf Meinen Etsy-Shop verbinden. Ein Etsy-Tab öffnet sich und bittet Sie, die App zu autorisieren.
3. Nach der Autorisierung werden Sie zu einer Bestätigungsseite weitergeleitet. Kehren Sie ins Back-Office zurück und laden Sie die Seite neu: Das Banner sollte Verbunden mit Name und ID Ihres Shops anzeigen.
4. Nutzen Sie die Schaltfläche Verbindung testen, um zu prüfen, ob alles funktioniert.

Das Zugriffstoken wird vom Modul automatisch erneuert. Die Schaltfläche Trennen entfernt die Tokens und die Shop-Zuordnung.

Einstellungen

Der Reiter Einstellungen bündelt das Synchronisationsverhalten und die Etsy-Standardattribute.

Synchronisation

• PS-Lager an Etsy senden: Jede Mengenänderung wird in die Warteschlange gestellt und beim nächsten Cron-Lauf gesendet.
• Angebot bei jedem Produkt-Speichern aktualisieren: Exportiert das Angebot automatisch neu, wenn Sie ein verknüpftes Produkt bearbeiten.
• Etsy-Bestellungen importieren: Aktiviert den automatischen Import bezahlter Bestellungen.
• Produktbilder senden: Hängt beim Export die Produktbilder an das Angebot an.
• Preise synchronisieren: Sendet den PrestaShop-Preis an Etsy.
• Etsy-Preisaufschlag (%): Wendet einen Prozentsatz auf den exportierten Preis an, um Etsy-Gebühren aufzufangen, ohne Ihren PrestaShop-Preis zu ändern.
• Exportsprache: Sprache für Titel und Beschreibung der Angebote.

Etsy-Standardattribute

• Wer es hergestellt hat / Wann: Pflichtwerte von Etsy (who_made / when_made), die auf neue Angebote angewendet werden.
• Taxonomy ID: Etsy-Standardkategorie der Angebote (siehe Etsys Seller Taxonomy).
• Versandprofil und Rückgaberichtlinie: Listen, die nach der Verbindung automatisch aus Ihrem Etsy-Shop geladen werden.
• Angebotsstatus beim Export: Entwurf (empfohlen — Sie prüfen vor der Veröffentlichung) oder Aktiv (sofortige Veröffentlichung, Etsy-Einstellgebühren fallen an).

Bestellimport

• Bestellstatus: PrestaShop-Status, der importierten Bestellungen zugewiesen wird.
• Versanddienstleister: standardmäßig zugeordneter Versanddienstleister.
• PrestaShop-E-Mails beim Import senden: standardmäßig deaktiviert, da Etsy den Käufer bereits benachrichtigt. In den meisten Fällen deaktiviert lassen.

Produkte zu Etsy exportieren

Suchen Sie im Reiter Produkte einen Artikel nach Name, Referenz oder ID.

• Zu Etsy exportieren erstellt ein Angebot mit Titel, Beschreibung, Tags, Bildern und Preis des Produkts. Das Angebot wird als Entwurf erstellt (oder aktiv, je nach Einstellungen), dann wird der Bestand (SKU, Preis, Menge) gesendet.
• Aktualisieren sendet die Informationen erneut an ein bereits verknüpftes Angebot.
• Verknüpfen (Listing-ID) verbindet ein PrestaShop-Produkt manuell mit einem bestehenden Etsy-Angebot durch Eingabe der Listing-ID.
• Trennen entfernt die Verknüpfung (das Etsy-Angebot wird nicht gelöscht).

Lagersynchronisation

Wenn sich die Menge eines verknüpften Produkts in PrestaShop ändert, wird ein Synchronisations-Job in eine deduplizierte Warteschlange eingereiht. Während des Browsens erfolgt kein Aufruf an Etsy: Die Warteschlange wird vom Cron verarbeitet, was jede Verlangsamung von Front- und Back-Office vermeidet. Sie können die Verarbeitung auch manuell über den Reiter Cron auslösen.

Bestellimport

Bezahlte Etsy-Bestellungen werden als PrestaShop-Bestellungen importiert:

• Ein Gastkunde wird erstellt (oder wiederverwendet, wenn bereits einer für diese E-Mail existiert).
• Die Etsy-Lieferadresse wird übernommen. Wird das Land nicht erkannt, wird die Bestellung übersprungen und eine Meldung erscheint in den Protokollen.
• Der bezahlte Betrag wird centgenau angewendet: Die PrestaShop-Bestellsumme entspricht dem auf Etsy bezahlten Betrag.
• Die Käufernotiz wird als Nachricht im Support-Thread der Bestellung angehängt.
• Die Deduplizierung per Etsy-Bestell-ID (Receipt) verhindert jeden Doppelimport.

Cron einrichten

Der Reiter Cron zeigt eine token-gesicherte URL an. Rufen Sie sie alle 5 bis 15 Minuten auf, um die Warteschlange (Lager und Produkte) zu verarbeiten und neue Bestellungen zu importieren.

*/10 * * * * curl -s "https://ihr-shop/index.php?fc=module&module=dfetsy&controller=cron&token=IHR_TOKEN" > /dev/null

Mit der Schaltfläche Warteschlange jetzt ausführen können Sie einen manuellen Lauf zum Testen auslösen.

Protokolle und Diagnose

Der Reiter Protokolle zeigt das Ereignisprotokoll (Export, Lager, Import, Fehler). Wenn eine Synchronisation fehlschlägt, prüfen Sie es zuerst: Jeder Etsy-Fehler wird dort mit seiner Meldung erfasst. Einträge, die älter als 30 Tage sind, werden automatisch bereinigt.

Einschränkungen der Version 1.0

• Ein Produkt = ein Angebot mit einer einzigen Referenz (keine nativen Etsy-Variationen).
• Ein einzelner Etsy-Shop (jeweils ein verbundener Shop).
• Die Sendungsverfolgung wird noch nicht an Etsy zurückgegeben.
• Die detaillierte Aufschlüsselung der Versandkosten pro Position wird nicht rekonstruiert (der auf Etsy bezahlte Gesamtbetrag ist maßgeblich).

Häufige Fragen

Werden meine Angebote automatisch veröffentlicht?

Standardmäßig nein: Sie werden als Entwurf erstellt, damit Sie sie vor der Veröffentlichung auf Etsy prüfen können. In den Einstellungen können Sie den Status „Aktiv“ wählen, um sofort zu veröffentlichen.

Wie vermeide ich Überverkauf zwischen beiden Kanälen?

Aktivieren Sie die Lagersynchronisation und einen regelmäßigen Cron: Jeder Verkauf oder jede Mengenänderung in PrestaShop aktualisiert die Etsy-Menge beim nächsten Cron-Lauf.

Wo finde ich den Quellcode?

Der vollständige Code ist im ZIP enthalten, unverschlüsselt (PSR-4, SPL-Autoloader), für Audit oder Anpassung.