← Alle Themen · Anbindungen

Anbindungen → OnCommerce (OnBuy)

Zurück zu Anbindungen | Zurück zur Übersicht

Hier verwalten Sie Ihre OnCommerce-Konten (OnBuy UK). Diese Anbindung überträgt Artikel in den OnBuy-Katalog, legt Listings an und hält Bestände synchron. Auftragsimport ist in dieser Phase nicht enthalten und kommt separat.

Konten-Übersicht

Die Tabelle zeigt alle angelegten OnCommerce-Konten:

Neues Konto anlegen

1. + Neues Konto anklicken.
2. Name, Mandant (siehe Einstellungen → Mandanten), Site und Modus wählen.
3. Consumer-Key und Secret-Key aus dem OnCommerce Seller Control Panel (API-Settings) einfügen.
4. Speichern. Konto bleibt zunächst inaktiv.
5. Verbindung testen → fordert einen Access-Token an. Erfolg = Status "ok".
6. Kategorien aktualisieren → einmalig alle Kategorien der Site in den lokalen Cache ziehen (dauert 30-60 Sekunden). Nötig damit die Pflichtfeld-Validierung Kategorie-Features auflösen kann.
7. Zum zentralen Anbindungen → Feld-Mapping wechseln, dort OnCommerce + das Konto wählen und für alle Pflichtfelder eine Quelle setzen (siehe Feld-Mapping).
8. Nach vollständigem Mapping Konto auf Aktiv schalten.

Modi

Hinweis zur IP-Bindung

Der Access-Token von OnCommerce ist an die ausgehende IP-Adresse des Servers gebunden und 15 Minuten gültig. Scanalot cached den Token automatisch pro Konto und erneuert ihn eigenständig. Läuft der Scheduler auf einem anderen Server als die Web-Oberfläche, wird für jede Egress-IP ein eigener Token gezogen. Falls Sie eine feste Egress-IP konfigurieren möchten, setzen Sie ONBUY_EGRESS_IP in der .env.

Feld-Mapping

Das Feld-Mapping für OnCommerce läuft nicht auf der Konto-Seite, sondern zentral unter Anbindungen → Feld-Mapping. Dort wählen Sie oben "OnCommerce" und darunter das jeweilige Konto. Für jedes OnCommerce-Zielfeld pflegen Sie eine Quelle aus dem Scanalot-Katalog.

Verfügbare Quellen (Standard-Scanalot-Quellen)

Die möglichen Quellen sind identisch zum Mapping aller anderen Marktplätze: SKU, Externe ID, Modell, Name/Name2-4, Beschreibung, Hersteller, Attribute, Eigenschaft, Barcode (Typ auswählen), Verkaufspreis (Preis-ID auswählen), Bestand (Lager auswählen), Bild, Alle Bilder, Eigener Text. Details siehe Anbindungen → Feld-Mapping.

Wichtig für OnCommerce: Beim EAN-Feld wählen Sie als Quelle "Barcode" und dann den gewünschten Barcode-Typ aus Artikel → Barcodes → so entscheiden Sie welcher Barcode-Typ als OnCommerce-EAN rausgeht.

Pflicht-Felder

Diese Felder müssen gesetzt sein bevor das Konto aktiv geschaltet werden kann:

Fehlt eines dieser Pflicht-Mappings, zeigt der Mapping-Dialog oben eine gelbe Warnbox mit der Liste der fehlenden Felder.

Optionale Felder

Bearbeitungszeit (handling_time)

Die Bearbeitungszeit wird nicht über das Feld-Mapping gepflegt, sondern kommt automatisch aus der Lager-Latency des aktiven Lagers (gleiches Pattern wie Amazon). Scanalot sendet den Wert bei jedem regulären Bestand-Sync (handling_time_override) direkt mit, eine Änderung der Latency im Lager-Setup schlägt beim nächsten Stock-Sync (alle 5 Minuten) auf OnCommerce durch.

Bilder

Bilder gehen nicht über das Feld-Mapping. Scanalot zieht automatisch das erste Bild aus Artikel → Bildern nach position. Zusatzbilder werden in späteren Phasen ergänzt.

Wichtig: OnCommerce lädt die Bilder von Ihrer URL. Die URL muss öffentlich erreichbar sein. OnCommerce nennt vier eigene IPs die bei einer Firewall freizugeben sind → siehe aktuelle Hinweise im Seller Control Panel.

Synchronisation

Carrier-Mapping

Für die vollständige Versandbestätigung (inkl. OnBuy-Carrier-Code) brauchst du einmalig ein Mapping zwischen deinen Scanalot-Carrier-Namen (z. B. DHL) und den OnBuy-Carrier-Codes.

1. Auf der OnCommerce-Konten-Seite den Button Carrier-Mapping öffnen.
2. Konto wählen und Carrier aktualisieren klicken, pullt die bei OnBuy registrierten Carrier für die Site des Kontos (häufige Prefixe: DHL, DPD, GLS, UPS, Hermes, Royal, Fedex, TNT, PostNL, USPS, Evri, Yodel).
3. Pro OnBuy-Carrier das Feld Scanalot-Carrier (Alias) mit dem Namen füllen den Scanalot in scanalot_orders_shipments.carrier verwendet. Mehrere OnBuy-Carrier können denselben Alias nicht teilen, pro Alias einen OnBuy-Carrier wählen.
4. Mapping speichern.

Beim nächsten OnCommerce Versand bestätigen-Event matched Scanalot zuerst gegen den Alias; wenn kein Alias eingetragen ist, fällt der Match auf den OnBuy-Namen zurück. Wenn weder noch greift, läuft Stufe 1 (Dispatch mit supplier_name-Freitext) trotzdem, nur Stufe 2 (expliziter Carrier-Code) wird dann übersprungen.

Ablauf Produktanlage

1. Artikel wird in Scanalot gespeichert, scanalot_items_markets enthält market="onbuy", active=1.
2. Beim nächsten Detektor-Lauf wird der Artikel in die OnCommerce-Queue geschrieben.
3. Export-Worker prüft die EAN → existiert bereits ein OnCommerce-Produkt mit dieser EAN, wird nur das Listing (SKU/Preis/Bestand) daran gehängt.
4. Falls das Produkt noch nicht existiert, wird es angelegt. OnCommerce verarbeitet die Anlage asynchron → das kann einige Minuten dauern.
5. Status-Watcher pollt den OnCommerce-Fortschritt und speichert die OnCommerce-Produkt-ID (OPC) am Artikel.
6. Varianten: Scanalot-Parent-Artikel mit Child-Artikeln werden als Variant-Group übergeben. Fehlt an einem Child ein Wert, nimmt Scanalot automatisch den Parent-Wert.

72-Stunden-Regel

OnCommerce löscht angelegte Produkte automatisch nach 72 Stunden, wenn sie nicht veröffentlicht sind. Scanalot setzt neu angelegte Produkte sofort auf veröffentlicht, sofern das Mapping vollständig ist.

Queue-Status einsehen

Unter Einstellungen → Queues sehen Sie:

• OnCommerce · Produkt-Queue → interne Scanalot-Queue (Create/Update-Jobs vor Übergabe an OnCommerce)
• OnCommerce · Asynchrone Tasks → Spiegel der OnCommerce-Seite (queue_id → OPC-Zuordnung, Status pending/done/failed)

Konto bearbeiten / löschen

• Bearbeiten: Name, Mandant, Site, Modus und Aktiv-Flag jederzeit änderbar. Consumer-Key und Secret-Key sind beim Bearbeiten leer → nur bei Änderung eingeben. Ein Credential-Wechsel invalidiert den gecachten Token automatisch.
• Verbindung testen: Fordert einen frischen Access-Token an. Setzt den Status am Konto.
• Kategorien aktualisieren: Pullt alle Kategorien der Site erneut in den lokalen Cache. Sinnvoll wenn OnCommerce neue Kategorien veröffentlicht hat.
• Löschen: Entfernt Konto, Mapping, Produkt-Zuordnungen und offene Queue-Einträge. Bereits bei OnCommerce angelegte Produkte bleiben dort bestehen.

Troubleshoot

Erstes Live-Produkt und Approve-Schritt

Jedes Produkt das Scanalot via API an OnCommerce schickt landet zunächst unter "Approve Products" (Pending Approval) im OnCommerce Seller Control Panel. Erst wenn Sie es dort manuell auf Approve/Publish setzen, werden Preis und Bestand im Marktplatz sichtbar. Das ist ein von OnCommerce vorgegebener Schritt und läuft nicht über die API ab.

Workflow:

1. Mit Test-Keys das Mapping prüfen und ein Test-Produkt erfolgreich anlegen lassen (Status "created").
2. Konto auf Modus "Live" wechseln, Live-Keys hinterlegen, erneut speichern.
3. Konto aktivieren → das Produkt wird angelegt und erscheint im Seller Control Panel unter "Approve Products".
4. Beim allerersten Produkt: in OnCommerce ein Support-Ticket aufmachen mit der Bitte, das Konto für Live-Produkt-Anlage freizuschalten. Erst nach OnCommerce-Freigabe erscheint der Approve-Button für Sie überhaupt.
5. Nach Konto-Freigabe: Jedes neue Produkt im Seller Control Panel manuell approven → erst dann sind Preis und Stock öffentlich sichtbar, vorher zeigt der Katalog 0,00 € und out of stock.

Scanalot kann diesen Schritt nicht automatisieren. Es gibt keinen offiziellen OnBuy-API-Endpoint zum Approven. Scanalots Job ist mit dem erfolgreichen Queue-Status (onbuy_product_tasks.status = 'done' + OPC gesetzt) abgeschlossen.