Rohstoffberechnung: Kursimport StoneX

Einleitung

Mit Rohstoffberechnung: Kursimport StoneX holst du deine Rohstoffkurse bei StoneX ab, statt sie von Hand in die Kursdaten der Rohstoffberechnung zu tippen. Das Plugin ruft je Währungspaar den Briefkurs ab und schreibt ihn in deinem Takt in die passenden Kurseinträge.

Was du mit diesem Plugin erreichst

• Du tippst keine Kurse mehr ab. Sie kommen direkt in die Kursdaten unter Kataloge → Rohstoffberechnung → Kursdaten.
• Du bestimmst den Takt: von alle 5 Minuten bis einmal am Tag.
• Ein Abruf versorgt alle Kundentypen. Händler- und Endkunden-Einträge mit demselben Code bekommen denselben Kurs. Unterschiedliche Konditionen legst du wie gewohnt über die Kursmanipulation fest.
• Fehlwerte zerschießen keinen Preis. Ein Kurs von null, ein negativer oder ein nicht lesbarer Wert wird verworfen, der gespeicherte Kurs bleibt stehen.
• Nutzt du zusätzlich das Plugin Artikelankauf, folgen auch deine berechneten Ankaufspreise dem importierten Kurs.
• Du steuerst die Verbindung. Ab Werk ist der Abruf aus. Erst wenn du ihn einschaltest, nimmt dein Shop Kontakt zu StoneX auf.

Für wen ist dieses Plugin?

Für Shops, die ihre Preise mit der Rohstoffberechnung rechnen und ihre Kurse von StoneX beziehen — zum Beispiel Edelmetallhändler mit Barren und Münzen.

Was du brauchst

• Das Plugin Rohstoffberechnung in Version 6.7, installiert und aktiv. Der Kursimport schreibt in dessen Kursdaten. Ohne die Rohstoffberechnung hat er keinen Ort, an den er die Kurse schreiben kann.
• Einen Zugang zur StoneX-Kursschnittstelle: die Daten-URL, also die Adresse der Kursschnittstelle, und die Token-ID. Beides bekommst du von StoneX, nicht mit dem Plugin. Welche Kurse dein Zugang enthält und was er kostet, klärst du direkt mit StoneX.
• Einen Server, der den Abruf regelmäßig startet. Das richtet deine IT ein (Für Administratoren / Technische Details).

Gut zu wissen: Wie du Kursdaten, Kundentypen, Artikel und die Preisberechnung einrichtest, steht im Handbuch der Rohstoffberechnung: https://www.bui-hinsche.com/dokumentation/rohstoffberechnung. Diese Anleitung beschreibt nur, was der Kursimport dazu beiträgt.

Installation

Nach dem Kauf steht dir das Plugin direkt in deiner Administration zur Verfügung — du musst nichts herunterladen.

1. Melde dich in deiner Shopware-Administration an (DeinShop.de/admin).
2. Öffne Erweiterungen → Meine Erweiterungen.
3. Prüfe, ob die Rohstoffberechnung installiert und aktiviert ist. Falls nicht, installiere und aktiviere sie zuerst. Der Kursimport baut auf ihr auf.
4. Klicke neben Rohstoffberechnung: Kursimport StoneX auf Installieren.
5. Aktiviere das Plugin über den Schalter links neben dem Plugin-Symbol — fertig.

Abb. 1: Rohstoffberechnung: Kursimport StoneX unter Meine Erweiterungen — installiert und aktiviert

Nach der Installation ist der Abruf ausgeschaltet. Dein Shop verbindet sich erst mit StoneX, wenn du Kurse bei StoneX abrufen einschaltest (Einstellungen).

Taucht Rohstoffberechnung: Kursimport StoneX nicht in der Liste auf, ist dein Shopware-Account noch nicht mit dem Shop verbunden. Das erledigst du unter Erweiterungen → Meine Erweiterungen im Reiter Shopware Account über die Anmeldung mit deinem Shopware-Konto.

Erste Schritte

In fünf Schritten kommen die ersten Kurse von StoneX in deinen Shop:

1. Zugangsdaten bereitlegen: Halte die Daten-URL und die Token-ID von StoneX bereit.
2. Kursdaten vorbereiten: Trage unter Kataloge → Rohstoffberechnung → Kursdaten in jedem Eintrag, der seinen Kurs von StoneX bekommen soll, im Feld Code das Währungspaar ein, zum Beispiel XAUEUR (So bereitest du deine Kursdaten auf den Import vor).
3. Zugangsdaten eintragen: Klicke unter Erweiterungen → Meine Erweiterungen neben Rohstoffberechnung: Kursimport StoneX auf Konfigurieren. Trage in der Karte Zugangsdaten die Daten-URL und die Token-ID ein (Einstellungen).
4. Abruf einschalten: Schalte in der Karte Kursimport den Schalter Kurse bei StoneX abrufen ein, lege das Abrufintervall (Minuten) fest und klicke oben rechts auf Speichern.
5. Ergebnis prüfen: Sobald der erste Abruf gelaufen ist, öffnest du die Kursdaten. In den Spalten Aktueller Kurs und Zuletzt geändert siehst du, dass der Import gearbeitet hat (So prüfst du, ob der Import läuft). Deine IT kann den ersten Abruf auch sofort von Hand starten.

Tipp: Mach den ersten Abruf mit deinem Zugang am besten in einem Testshop und wirf danach mit deiner IT einen Blick ins Protokoll. So siehst du in Ruhe, welche Paare dein Zugang liefert und welche Einträge der Import anlegt, bevor er in deinem Live-Shop Kurse schreibt.

Einstellungen

Die Einstellungen öffnest du unter Erweiterungen → Meine Erweiterungen: Klicke neben Rohstoffberechnung: Kursimport StoneX auf Konfigurieren. Nach jeder Änderung klickst du oben rechts auf Speichern.

Für welchen Verkaufskanal die Einstellungen gelten

Oben auf der Seite bietet Shopware die Auswahl Verkaufskanal an. Lass sie auf Alle Verkaufskanäle stehen und trage dort alles ein. Kurse gehören zu keinem Verkaufskanal. Deshalb gelten die Einstellungen dieses Plugins für deinen ganzen Shop. Werte, die du nur für einen einzelnen Verkaufskanal einträgst, nutzt das Plugin nicht.

In welchem Verkaufskanal aus den Kursen Preise berechnet werden, legst du weiterhin mit dem Schalter Plugin für diesen Verkaufskanal aktivieren der Rohstoffberechnung fest.

Dokumentation öffnen

Mit dem Button Dokumentation öffnen ganz oben in der Karte Kursimport gelangst du direkt zu dieser Anleitung im Internet.

Abb. 2: Die Karte Kursimport mit dem Button Dokumentation öffnen, dem eingeschalteten Schalter Kurse bei StoneX abrufen und dem Abrufintervall 15

Kurse bei StoneX abrufen

Mit dem Schalter Kurse bei StoneX abrufen legst du fest, ob dein Shop Kurse bei StoneX abholt. Eingeschaltet verbinden sich die geplante Aufgabe und der Befehl resourcecalc:stonex:import mit den Zugangsdaten aus der Karte Zugangsdaten zu StoneX. Ausgeschaltet findet keine Verbindung zu StoneX statt. Ab Werk ist der Schalter aus.

Wozu das gut ist: Du schaltest den Abruf erst ein, wenn Zugangsdaten und Kursdaten vorbereitet sind. Willst du den Import pausieren, schaltest du ihn wieder aus. Deine Kurse bleiben dann so stehen, wie sie zuletzt importiert wurden, und du kannst sie wie gewohnt von Hand pflegen.

Abrufintervall (Minuten)

Im Feld Abrufintervall (Minuten) legst du fest, wie oft die geplante Aufgabe die Kurse abruft. Erlaubt sind 5 bis 1440 Minuten, ab Werk sind es 15. Mit 60 holst du die Kurse stündlich, mit 1440 einmal am Tag. Bleibt das Feld leer, gilt 15.

Eine Änderung wirkt nicht sofort: Sie gilt ab dem übernächsten Lauf der geplanten Aufgabe.

Das Intervall setzt einen laufenden Worker für geplante Aufgaben auf deinem Server voraus. Startet deine IT den Befehl per Crontab, ruft er nur ab, was laut Zeitplan fällig ist (Für Administratoren / Technische Details).

Wozu das gut ist: Du stimmst den Takt darauf ab, wie oft du einen frischen Kurs brauchst. Reicht dir ein Kurs pro Tag, nimmst du 1440. Willst du nah am Markt verkaufen, gehst du bis auf 5 Minuten herunter.

Abrufintervall je Kundentyp

Die Rohstoffberechnung kann für einzelne Kundentypen ein eigenes Abrufintervall (Sekunden) führen (Kataloge → Rohstoffberechnung → Kundentypen). Dann holt dieses Plugin die Kurse dieses Kundentyps in dem Abstand, der dort eingetragen ist; alle übrigen Kundentypen bekommen ihre Kurse im Intervall hier. Die geplante Aufgabe läuft dann im kürzesten dieser Intervalle, frühestens alle 5 Minuten.

Für Intervalle unter 5 Minuten startet deine IT den Befehl resourcecalc:stonex:import jede Minute per System-Cronjob:

* * * * * cd /pfad/zum/shop && php bin/console resourcecalc:stonex:import

Der Befehl holt dann innerhalb der Minute alle Kurse, die fällig werden — bei Intervallen unter einer Minute mehrmals. Befehl und geplante Aufgabe teilen sich den Zeitplan: Jeder Kurs wird je Intervall nur einmal abgerufen, egal über welchen Weg. Ist nichts fällig, endet der Befehl sofort mit einem Hinweis. Mit php bin/console resourcecalc:stonex:import --force holst du die Kurse sofort für alle Kundentypen.

Daten-URL

In der Karte Zugangsdaten trägst du unter Daten-URL die Adresse der StoneX-Kursschnittstelle ein. Du bekommst sie von StoneX.

• Lässt du das Protokoll weg, verwendet das Plugin https://.
• Trag http:// nur ein, wenn StoneX die Schnittstelle ausschließlich unverschlüsselt anbietet. Die Token-ID wird dann unverschlüsselt übertragen.
• Schreib keine Zugangsdaten wie Benutzername oder Passwort in die Adresse. Eine solche Adresse lehnt das Plugin ab, und der Abruf startet nicht.

Abb. 3: Die Karte Zugangsdaten mit Beispielwerten. Die Daten-URL https://rates.example.com/stonex ist eine Beispieladresse, keine echte StoneX-Adresse. Die Token-ID ist maskiert.

Token-ID

Unter Token-ID trägst du den Schlüssel ein, mit dem sich dein Shop bei StoneX ausweist. Auch ihn bekommst du von StoneX. Das Plugin schickt die Token-ID bei jedem Abruf an StoneX, aber nie als Teil der Adresse. Ins Protokoll schreibt es sie nie.

Fehlt die Daten-URL oder die Token-ID, startet der Abruf nicht.

Wichtig: In der Administration wird die Token-ID maskiert angezeigt. Gespeichert wird sie aber im Klartext in der Systemkonfiguration deines Shops. Gib Zugänge zur Administration und zur Datenbank deshalb nur an Personen, denen du auch die Token-ID anvertrauen würdest.

So bereitest du deine Kursdaten auf den Import vor

Was dir das bringt: Der Import schreibt den Kurs genau in die Einträge, die du dafür vorsiehst — auch in deine bestehenden Einträge, mit denen deine Artikel schon rechnen. An deinen Artikeln musst du nichts ändern.

So erkennt der Import deine Kurseinträge

Die Antwort von StoneX enthält je Kurs ein Währungspaar, zum Beispiel XAUEUR, und den Briefkurs dazu. Der Import sucht in den Kursdaten jeden Eintrag, dessen Code genau diesem Paar entspricht. In der Liste der Kursdaten steht der Code in der Spalte Kurscode.

Deine Artikel verweisen dagegen auf das Feld Interner Code, zum Beispiel GOLD. Den Internen Code eines vorhandenen Eintrags fasst der Import nicht an. So bleibt die Verbindung zu deinen Artikeln erhalten.

Wichtig: Im Handbuch der Rohstoffberechnung steht beim Feld Code, dass es für die Berechnung keine Rolle spielt. Für die Preisberechnung stimmt das. Für den Kursimport ist der Code aber der Schlüssel: Nur Einträge, deren Code zum Paar passt, bekommen den Kurs von StoneX.

Einen bestehenden Kurseintrag mit StoneX verbinden

1. Öffne Kataloge → Rohstoffberechnung → Kursdaten und dort den Eintrag, zum Beispiel Gold.
2. Trage unter Code das Währungspaar ein, zum Beispiel XAUEUR. Schreib es genau so, wie es in der Antwort von StoneX steht.
3. Lass den Internen Code unverändert, zum Beispiel GOLD. Daran hängen deine Artikel.
4. Klicke auf Speichern.

Beim nächsten Abruf bekommt der Eintrag im Feld Aktueller Marktkurs den Briefkurs. Das Feld Währung setzt der Import passend zum Paar: Die letzten drei Buchstaben sind die Kurswährung, bei XAUEUR also EUR.

Abb. 4: Der Kurseintrag Gold im Kundentyp Händler nach dem Import: Code XAUEUR, Interner Code GOLD, Aktueller Marktkurs 2513.1

Gut zu wissen: Die Kurswerte in den Abbildungen dieser Anleitung sind Beispielwerte, nicht von StoneX.

Tipp: Der Kurs gilt für die Mengeneinheit, in der dein Zugang die Kurse liefert. Welche das ist, klärst du mit StoneX. Am Artikel müssen Anzahl an Einheiten und Formel dazu passen. Wie das geht, steht im Handbuch der Rohstoffberechnung in Abschnitt 5.1 und Kapitel 7.

Händler und weitere Kundentypen versorgen

Der Import schreibt den Kurs in jeden Eintrag mit passendem Code, in jedem Kundentyp. Führst du für Händler einen eigenen Eintrag, gib ihm denselben Code wie dem Eintrag im Kundentyp Default. Dann bekommen beide in einem Durchgang denselben Kurs — es sei denn, der Händler-Kundentyp hat ein eigenes Abrufintervall; dann bekommt er seinen Kurs in seinem Takt. Wie bisher trägt der Händler-Eintrag außerdem denselben Internen Code wie der Default-Eintrag (Handbuch der Rohstoffberechnung, Abschnitt 6.2).

Einen von Hand gepflegten Händlerkurs überschreibt der Import dabei. Den Unterschied zwischen Händlern und Endkunden legst du deshalb über die Kursmanipulation des Händler-Eintrags fest. Im Beispiel ist dort Berechnung aktiv eingeschaltet und unter Aufschlag in Prozent −1 eingetragen. Händler rechnen so mit einem Kurs 1 % unter dem importierten Marktkurs.

Soll ein Eintrag seinen von Hand gepflegten Kurs behalten, gib ihm einen Code, der in der Antwort von StoneX nicht vorkommt. Dann lässt der Import ihn in Ruhe.

Wenn du die Paare deines Zugangs noch nicht kennst

Für jedes Paar, zu dem es noch keinen Eintrag mit passendem Code gibt, legt der Import einmal einen neuen Eintrag im Kundentyp Default an (Neue Paare, neue Kurseinträge). Das kannst du nutzen: Führe den ersten Abruf in einem Testshop aus, in dem noch kein Eintrag einen solchen Code trägt. Danach stehen alle Paare der Antwort als neue Einträge in der Liste der Kursdaten. Den Code übernimmst du dann in deine eigenen Einträge.

Tipp: Bereite deine Einträge im Live-Shop vor, bevor du dort den Abruf einschaltest. Sonst legt der Import für jedes Paar zuerst einen zusätzlichen Eintrag an, und deine eigenen Einträge bekommen noch keinen Kurs.

So läuft der Kursimport

Was dir das bringt: Wenn du weißt, was der Import schreibt und was er unberührt lässt, kannst du jeden Kurs in deinen Kursdaten nachvollziehen.

Der Abruf läuft als geplante Aufgabe in deinem Abrufintervall oder auf Befehl, den deine IT zum Beispiel per Crontab startet.

Was der Import in deine Kursdaten schreibt

Bei jedem Abruf liest das Plugin aus der Antwort von StoneX je Eintrag das Währungspaar und den Briefkurs. Jeder Kurseintrag mit passendem Code bekommt dann:

• im Feld Aktueller Marktkurs den Briefkurs,
• im Feld Währung die Kurswährung aus den letzten drei Buchstaben des Paars,
• die Zeit des Imports, die du in der Spalte Zuletzt geändert siehst.

Kursbezeichnung, Interner Code und die Einstellungen der Kursmanipulation bleiben, wie du sie angelegt hast. Deine Shop-Währungen ändert der Import nicht.

Abb. 5: Die Kursdaten nach dem Import: zweimal Gold mit 2513.1 (Kundentyp Default und Händler), Silber mit 30,15, Platin mit 906,3 und der neu angelegte Eintrag XPD_EUR mit 970,7. Die Spalte Zuletzt geändert zeigt den Tag des Imports.

Liegt ein Kurs in einer anderen Währung vor als deine Standardwährung, rechnet die Rohstoffberechnung über den Faktor um, den du in Shopware unter Einstellungen → Regional → Währungen für diese Währung pflegst (Handbuch der Rohstoffberechnung, Abschnitt 5.1). Diesen Faktor setzt der Import nicht.

Neue Paare, neue Kurseinträge

Gibt es zu einem Paar noch keinen Eintrag mit passendem Code, legt der Import einmal einen neuen Eintrag an:

• Kundentyp: Default
• Kursbezeichnung: das Paar mit Unterstrich, zum Beispiel XPD_EUR
• Code und Interner Code: das Paar, zum Beispiel XPDEUR
• Variable in der Formel: x
• Aktueller Marktkurs: der Briefkurs

Abb. 6: Der vom Import angelegte Eintrag XPD_EUR im Kundentyp Default mit Code und Internem Code XPDEUR, Variable x und Aktuellem Marktkurs 970,7

Ein solcher Eintrag wirkt erst, wenn ein Artikel ihn als Rohstoff nutzt. Du hast diese Möglichkeiten:

• Nutzen: Wähle den Eintrag am Artikel unter Rohstoff aus (Handbuch der Rohstoffberechnung, Abschnitt 7.2). Die Kursbezeichnung darfst du ändern, zum Beispiel in Palladium. Der Import überschreibt sie nicht.
• Stehen lassen: Brauchst du das Paar nicht, lass den Eintrag einfach stehen. Er bekommt bei jedem Abruf den neuen Kurs, wirkt aber auf keinen Preis.
• Löschen: Das bringt wenig. Solange das Paar in der Antwort steht und kein anderer Eintrag seinen Code trägt, legt der nächste Import den Eintrag wieder an.

Hat der Import einen Eintrag angelegt, obwohl du schon einen eigenen für diesen Rohstoff hast? Dann fehlte deinem Eintrag der passende Code. Trag ihn dort nach (Einen bestehenden Kurseintrag mit StoneX verbinden). Den angelegten Eintrag kannst du danach löschen. Weil jetzt dein eigener Eintrag den Code trägt, legt der Import ihn nicht wieder an.

Wichtig: Gibt es im Kundentyp Default schon einen Eintrag, dessen Interner Code dem Paar entspricht, legt der Import keinen zweiten an. Er verwirft dann den Kurs für dieses Paar. Trag in diesem Fall im vorhandenen Eintrag das Paar als Code ein.

Was mit fehlerhaften Kursen passiert

• Kommt ein Kurs als null, negativ oder nicht als Zahl an, verwirft der Import ihn. Der gespeicherte Kurs bleibt stehen. Das ist wichtig, denn ohne Kurs rechnet die Rohstoffberechnung mit dem Wert 1.
• Einträge der Antwort ohne Währungspaar überspringt der Import und vermerkt sie im Protokoll.
• Ist StoneX nicht erreichbar oder die Antwort nicht lesbar, ändert der Import nichts an deinen Kursdaten. Den Grund findet deine IT im Protokoll des Plugins (Für Administratoren / Technische Details).

Wann deine Kunden den neuen Kurs sehen

Die Rohstoffberechnung rechnet die Preise auf der Produktseite, in Kategorien und Slidern bei jedem Aufruf neu. Deine Kunden sehen den neuen Kurs deshalb beim nächsten Seitenaufruf.

Sortierung nach Preis, Preisfilter und Exporte nutzen dagegen den gespeicherten Artikelpreis. Den schreibt der Import nicht. Dafür ist weiterhin der Befehl resourcecalc:cron der Rohstoffberechnung zuständig, den deine IT regelmäßig laufen lässt (Handbuch der Rohstoffberechnung, Kapitel 14).

Verkauf und Ankauf am selben Kurs

Nutzt du zusätzlich das Plugin Artikelankauf und rechnen deine Ankaufspreise mit dem Rohstoffkurs, folgen auch sie dem importierten Kurs. Wie du einen berechneten Ankaufspreis einrichtest, steht im Handbuch Artikelankauf in Abschnitt 6.3. Auf der Produktseite steht dann unter dem Kaufbereich Aktueller Ankaufspreis mit dem berechneten Betrag. Verkaufspreis und Ankaufspreis steigen und fallen mit jedem Import, ohne dass du einen Preis anfasst.

Abb. 7: Die Produktseite Goldbarren 1 oz mit dem aus dem Kurs berechneten Preis und darunter „Aktueller Ankaufspreis“ aus Artikelankauf

So prüfst du, ob der Import läuft

Was dir das bringt: Du siehst auf einen Blick, ob deine Kurse frisch sind — ohne Server-Zugang.

1. Öffne Kataloge → Rohstoffberechnung → Kursdaten.
2. Sieh dir die Spalte Zuletzt geändert an. Sie zeigt bei jedem Eintrag, wann sein Kurs zuletzt geschrieben wurde. Bei Einträgen, die der Import versorgt, ist das der letzte Abruf.
3. Vergleiche die Spalte Aktueller Kurs mit den Kursen deines StoneX-Zugangs.
4. Achte auf neue Einträge mit Unterstrich in der Kursbezeichnung, zum Beispiel XPD_EUR. Sie zeigen Paare, für die es noch keinen Eintrag mit passendem Code gab (Neue Paare, neue Kurseinträge).

Bleibt Zuletzt geändert über mehrere Abrufintervalle unverändert, hilft dir Fehlerbehebung weiter.

Den genauen Ablauf jedes Abrufs hält das Plugin im Protokoll fest: welche Codes es aktualisiert hat, welche es neu angelegt hat und wie viele Kurse es verworfen hat. Lass dir das Protokoll nach dem ersten Abruf von deiner IT zeigen (Für Administratoren / Technische Details).

So stellst du von einer früheren Version um

Was dir das bringt: Du weißt vor dem Update, was gleich bleibt und wo du einmal nachsehen solltest.

Hast du den Kursimport schon vor Version 6.7.0 genutzt, gilt nach dem Update:

• Der Abruf läuft weiter. War eine Daten-URL eingetragen, schaltet das Update Kurse bei StoneX abrufen von selbst ein.
• Daten-URL und Token-ID bleiben erhalten. Du musst sie nicht neu eintragen.
• Dein Crontab läuft weiter. Der Befehl heißt jetzt resourcecalc:stonex:import. Der frühere Name resourcecalcstonex:cron funktioniert weiter.
• Neu ist die geplante Aufgabe. Läuft auf deinem Server ein Worker für geplante Aufgaben, ruft sie die Kurse zusätzlich im Abrufintervall (Minuten) ab. Crontab und geplante Aufgabe teilen sich einen Zeitplan und rufen nie doppelt ab (Für Administratoren / Technische Details).
• Der ungenutzte Schalter „Plugin für diesen Kanal aktivieren“ entfällt.
• Der Import setzt keine Währungsfaktoren mehr. Bis Version 6.06.00 hat er die Umrechnungsfaktoren von USD und EUR mitgesetzt und fehlende Währungen angelegt. Seit 6.7.0 tut er das nicht mehr. Prüfe deine Faktoren unter Einstellungen → Regional → Währungen und pflege sie dort selbst.
• Neue Paare werden jetzt angelegt. Für Paare ohne passenden Eintrag legt der Import einmal einen Eintrag im Kundentyp Default an. In früheren Versionen griff dieser Schritt nie. Sieh nach dem ersten Abruf in die Kursdaten (Neue Paare, neue Kurseinträge).

Fehlerbehebung

Die Kurse ändern sich nicht

Woran es liegt: Meist ist eine dieser Ursachen der Grund:

• Kurse bei StoneX abrufen ist ausgeschaltet.
• Die Daten-URL oder die Token-ID fehlt. Oder die Daten-URL ist ungültig, zum Beispiel weil Zugangsdaten in der Adresse stehen.
• Auf dem Server läuft weder ein Worker für geplante Aufgaben noch ein Crontab.
• Die Verbindung zu StoneX klappt nicht, oder die Antwort ist keine lesbare Kursliste.
• Kein Eintrag in deinen Kursdaten trägt den passenden Code. Dann legt der Import neue Einträge an, statt deine zu aktualisieren (nächster Abschnitt).

So behebst du es:

1. Prüfe in der Konfiguration unter Alle Verkaufskanäle, ob Kurse bei StoneX abrufen eingeschaltet ist (Einstellungen).
2. Prüfe Daten-URL und Token-ID in der Karte Zugangsdaten und vergleiche sie mit den Angaben von StoneX. In der Adresse dürfen weder Benutzername noch Passwort stehen.
3. Bitte deine IT, den Abruf einmal von Hand zu starten. Der Befehl nennt den Grund direkt, zum Beispiel fehlende Zugangsdaten oder einen Verbindungsfehler (Für Administratoren / Technische Details).
4. Bitte deine IT zu prüfen, ob der Worker für geplante Aufgaben oder der Crontab läuft.

Der Import legt neue Einträge an, statt meine zu aktualisieren

Woran es liegt: Der Code deines Eintrags passt nicht zum Paar in der Antwort von StoneX. Für ein Paar ohne passenden Code legt der Import einen neuen Eintrag im Kundentyp Default an.

So behebst du es: Übernimm den Code aus dem angelegten Eintrag in deinen eigenen Eintrag, zum Beispiel XAUEUR (Einen bestehenden Kurseintrag mit StoneX verbinden). Den angelegten Eintrag kannst du danach löschen.

Ein Paar bekommt nie einen Kurs

Woran es liegt:

• Im Kundentyp Default gibt es schon einen Eintrag mit dem Paar als Internem Code, aber mit einem anderen Code. Dann verwirft der Import den Kurs (Neue Paare, neue Kurseinträge).
• Der Kurs kommt als null, negativ oder nicht als Zahl an. Dann verwirft der Import ihn und der gespeicherte Kurs bleibt.
• Das Paar steht nicht in der Antwort deines Zugangs. Welche Paare dein Zugang enthält, regelt StoneX, nicht das Plugin.

So behebst du es: Trag im vorhandenen Eintrag das Paar als Code ein. Verworfene Kurse vermerkt zusätzlich die Rohstoffberechnung in ihrem Protokoll — deine IT kann dort den Grund nachlesen (Für Administratoren / Technische Details). Fehlt das Paar in der Antwort, wende dich an StoneX.

Der Händlerkurs wurde überschrieben

Woran es liegt: Der Händler-Eintrag trägt denselben Code wie der Default-Eintrag. Dann bekommt er bei jedem Abruf denselben importierten Kurs.

So behebst du es: Lege den Unterschied über die Kursmanipulation des Händler-Eintrags fest. Soll der Eintrag seinen von Hand gepflegten Kurs behalten, gib ihm einen Code, der in der Antwort von StoneX nicht vorkommt (Händler und weitere Kundentypen versorgen).

Die Preise passen nicht zum importierten Kurs

Woran es liegt: Meist passen Mengeneinheit, Währung oder Kursmanipulation nicht zusammen.

So behebst du es:

• Prüfe, ob Anzahl an Einheiten und Formel am Artikel zur Mengeneinheit deines StoneX-Kurses passen (Einen bestehenden Kurseintrag mit StoneX verbinden).
• Prüfe den Faktor der Kurswährung unter Einstellungen → Regional → Währungen. Den setzt der Import nicht.
• Prüfe die Kursmanipulation: Aufschläge und Rückfallkurs ändern den Kurs, bevor er in die Formel geht.
• Weitere Ursachen beschreibt das Handbuch der Rohstoffberechnung in Kapitel 11.

Sortierung nach Preis, Preisfilter oder Exporte zeigen alte Preise

Woran es liegt: Diese Funktionen lesen den gespeicherten Artikelpreis. Den schreibt nicht der Import, sondern der Befehl resourcecalc:cron der Rohstoffberechnung.

So behebst du es: Bitte deine IT, diesen Befehl regelmäßig laufen zu lassen, zum Beispiel kurz nach dem Kursimport (Handbuch der Rohstoffberechnung, Kapitel 14).

Eine Änderung am Abrufintervall wirkt nicht

Woran es liegt: Die geplante Aufgabe übernimmt ein neues Intervall nicht sofort, es gilt ab ihrem übernächsten Lauf. Startet deine IT den Abruf per Crontab, gilt ohnehin der Takt des Crontabs.

So behebst du es: Warte einige Abrufe ab. Läuft der Abruf per Crontab, bitte deine IT, den Takt dort anzupassen.

Die Konfiguration oder das Plugin fehlt

Woran es liegt: Das Plugin ist vermutlich noch nicht aktiviert, die Rohstoffberechnung ist nicht aktiv, oder der Zwischenspeicher (Cache) ist veraltet.

So behebst du es:

1. Öffne Erweiterungen → Meine Erweiterungen.
2. Prüfe, ob die Schalter neben Rohstoffberechnung und neben Rohstoffberechnung: Kursimport StoneX eingeschaltet sind.
3. Leere den Cache: Einstellungen → System → Caches & Indizes → Cache löschen.

FAQ

F: Was brauche ich von StoneX?

A: Eine Daten-URL, also die Adresse der StoneX-Kursschnittstelle, und eine Token-ID. Beides bekommst du von StoneX, nicht mit dem Plugin. Welche Kurse dein Zugang enthält und was er kostet, klärst du direkt mit StoneX.

F: Welche Kurse holt das Plugin?

A: Das, was in der Antwort deines Zugangs steht: je Eintrag ein Währungspaar und den Briefkurs dazu. Welche Paare das sind, regelt dein Zugang bei StoneX, nicht das Plugin.

F: Funktioniert das Plugin ohne die Rohstoffberechnung?

A: Nein. Das Plugin schreibt die Kurse in die Kursdaten der Rohstoffberechnung. Ohne die Rohstoffberechnung 6.7, installiert und aktiv, hat es keinen Ort, an den es die Kurse schreiben kann.

F: Welche Kurseinträge bekommen den neuen Kurs?

A: Jeder Eintrag in den Kursdaten, dessen Code zum Währungspaar passt, und zwar in jedem Kundentyp. Für ein Paar ohne passenden Eintrag legt der Import einmal einen neuen Eintrag im Kundentyp Default an.

F: Kann ich einzelne Paare vom Import ausschließen?

A: Nein, dafür gibt es keine Einstellung. Ein Paar, das du nicht brauchst, landet einmal als eigener Eintrag im Kundentyp Default. Solange kein Artikel diesen Eintrag nutzt, wirkt er auf keinen Preis.

F: Kann ich Kurse weiterhin von Hand pflegen?

A: Ja. Einträge, deren Code nicht in der Antwort von StoneX vorkommt, fasst der Import nicht an. Einträge mit passendem Code überschreibt er beim nächsten Abruf. Ist Kurse bei StoneX abrufen ausgeschaltet, pflegst du alle Kurse von Hand.

F: Ändern sich meine Artikelpreise sofort?

A: Die Anzeige im Shop ja, beim nächsten Seitenaufruf. Die Rohstoffberechnung rechnet sie bei jedem Aufruf mit dem aktuellen Kurs. Sortierung nach Preis, Preisfilter und Exporte ziehen erst nach, wenn der Befehl resourcecalc:cron der Rohstoffberechnung gelaufen ist.

F: Aktualisiert das Plugin auch meine Shop-Währungen?

A: Nein. Der Import schreibt nur Rohstoffkurse. Die Umrechnungsfaktoren deiner Währungen pflegst du in Shopware unter Einstellungen → Regional → Währungen.

F: Was passiert, wenn ein Kurs fehlt oder StoneX nicht erreichbar ist?

A: Ein Kurs von null, ein negativer oder ein nicht numerischer Wert wird verworfen, der gespeicherte Kurs bleibt. Ist StoneX nicht erreichbar oder die Antwort unlesbar, ändert der Import nichts. Den Grund findet deine IT im Protokoll des Plugins.

F: Kann ich den Abruf je Verkaufskanal steuern?

A: Nein. Kurse haben keinen Verkaufskanal, deshalb gelten die Einstellungen für den ganzen Shop. In welchem Verkaufskanal Preise aus den Kursen berechnet werden, entscheidet weiterhin der Schalter der Rohstoffberechnung.

F: Werden Daten an externe Dienste übertragen?

A: Ja, an StoneX, und nur dorthin. Das Plugin ruft ausschließlich die eingetragene Daten-URL auf, nur bei eingeschaltetem Abruf, und sendet dabei die Token-ID mit. Kunden- oder personenbezogene Daten verlassen deinen Shop nicht. Cookies setzt das Plugin keine.

F: Was passiert bei der Deinstallation?

A: Das Plugin legt keine eigenen Tabellen an. Die Konfiguration entfernt Shopware, wenn du die Daten nicht behältst. Die importierten Kurse bleiben in den Kursdaten der Rohstoffberechnung stehen und lassen sich dort weiter von Hand pflegen.

Für Administratoren / Technische Details

Dieser Abschnitt richtet sich an technische Administratoren. Für die normale Nutzung brauchst du ihn nicht.

Systemanforderungen

• Shopware: 6.7.7 oder höher (Voraussetzung der Rohstoffberechnung)
• PHP: 8.2 oder neuer
• Rohstoffberechnung (SwpResourceCalcSix) 6.7, installiert und aktiv
• Der Server muss die eingetragene Daten-URL erreichen können.

Installation über die Kommandozeile

Liegt das Plugin bereits im Shop, installierst und aktivierst du es so. Die zweite Zeile entfällt, wenn die Rohstoffberechnung schon aktiv ist:

php bin/console plugin:refresh
php bin/console plugin:install --activate SwpResourceCalcSix
php bin/console plugin:install --activate SwpResourceCalcStonexSix
php bin/console cache:clear

Abruf über die geplante Aufgabe

Die geplante Aufgabe heißt swp.resource_calc_stonex.rate_import, ihr Standardintervall beträgt 900 Sekunden. Bei jedem Lauf übernimmt sie das konfigurierte Abrufintervall (Minuten) (5 bis 1440) in ihren Eintrag in der Tabelle scheduled_task, sofern es sich geändert hat. Weil der Scheduler den nächsten Termin schon berechnet hat, gilt ein geändertes Intervall erst ab dem übernächsten Lauf.

Voraussetzung ist ein laufender Scheduler mit Worker, zum Beispiel:

php bin/console scheduled-task:run
php bin/console messenger:consume

Ist der Abruf ausgeschaltet, verbindet sich die Aufgabe nicht. Fehlen Zugangsdaten, schreibt sie eine Warnung ins Protokoll. Verbindungs- und Formatfehler stehen als Fehler im Protokoll.

Abruf per Befehl oder Crontab

php bin/console resourcecalc:stonex:import

Der frühere Name resourcecalcstonex:cron funktioniert weiter. Beispiel für einen Crontab-Eintrag alle 15 Minuten:

*/15 * * * * cd /pfad/zum/shop && php bin/console resourcecalc:stonex:import

Entscheide dich für einen Weg: Läuft zusätzlich der Worker für geplante Aufgaben, ruft auch die geplante Aufgabe im Abrufintervall ab. Die gespeicherten Artikelpreise schreibt weiterhin php bin/console resourcecalc:cron der Rohstoffberechnung, mit eigenem Crontab-Eintrag (Handbuch der Rohstoffberechnung, Kapitel 14).

Meldungen und Exit-Codes des Befehls

Situation	Ausgabe	Exit-Code
Abruf ausgeschaltet	Warnung Fetching rates from StoneX is switched off in the plugin configuration. No connection was made.	0
Zugangsdaten unvollständig oder Daten-URL ungültig	StoneX access data incomplete, missing: url, token (genannt wird, was fehlt)	1
Verbindung fehlgeschlagen	StoneX request to <host> failed: <Grund>	1
HTTP-Status außerhalb von 2xx	StoneX (<host>) answered with HTTP status <Status>	1
Antwort ist keine Kursliste	StoneX response is not a rate list: <Grund>	1
Kurse geschrieben	Übersicht mit Updated codes, Created codes und Discarded quotes, danach StoneX rates imported. Product prices are stored by the command resourcecalc:cron.	0
Antwort gelesen, aber kein Kurs geschrieben	dieselbe Übersicht, danach Warnung No rate was written. Details: log file SwpResourceCalcSix of the resource calculation.	1

Als ungültig gilt eine Daten-URL mit Benutzername oder Passwort und jede Adresse, die nicht mit http:// oder https:// arbeitet.

Abruf und Antwortformat

• Anfrage: GET auf die Daten-URL mit den Headern TokenID: <Token-ID> und Accept: application/json. Ohne Protokoll wird https:// vorangestellt.
• Erwartet wird JSON mit der Liste result, je Eintrag mit Pair und Ask:

{
    "result": [
        { "Pair": "XAUEUR", "Ask": 2513.1 },
        { "Pair": "XPDEUR", "Ask": 970.7 }
    ]
}

• Zuordnung: Code = Pair. Kursbezeichnung bei Neuanlage = Pair mit Unterstrich nach dem dritten Zeichen (XAU_EUR). Kurswährung = letzte drei Zeichen in Großbuchstaben. Kurs = Ask als Zahl oder numerischer Text; alles andere wird als 0 übergeben und verworfen.
• Einträge ohne Pair werden übersprungen (Warnung im Protokoll). Enthält die Antwort keinen Eintrag mit Pair, gilt sie als ungültig.
• Grenzen je Abruf: 10 Sekunden je Verbindung, 30 Sekunden insgesamt, Antwort höchstens 5 MB, höchstens 3 Weiterleitungen.
• Das Plugin liest das Format, das schon die Vorgängerversionen gelesen haben. Geprüft ist der Import mit nachgestellten Antworten in diesem Format. Mach den ersten Abruf mit einem echten Zugang deshalb in einem Testshop.

Was der Import schreibt

• Geschrieben wird ausschließlich über den Kursimport der Rohstoffberechnung in deren Kursdaten, in einem Schreibvorgang je Abruf.
• Abgleich über das Feld Code (resourceCode) in allen Kundentypen. Geschrieben werden Kurs, Kurswährung und Änderungszeit.
• Unbekannte Codes werden einmal im Kundentyp Default angelegt (Interner Code = Code, Variable x). Ist der Interne Code dort schon vergeben, wird der Kurs verworfen.
• Kurse von null, negative und nicht numerische Kurse werden verworfen; der gespeicherte Kurs bleibt. Den Grund protokolliert die Rohstoffberechnung.
• Shop-Währungen und gespeicherte Artikelpreise bleiben unberührt.
• Die einzige weitere Schreibstelle ist das Intervall der geplanten Aufgabe.

Protokoll

Das Plugin schreibt in var/log/SwpResourceCalcStonexSix-<Datum>.log:

• StoneX rates imported — Zusammenfassung je Import mit Anzahl der Kurse, aktualisierten und angelegten Codes sowie verworfenen Kursen mit Grund
• StoneX rate import skipped: access data incomplete — fehlende Zugangsdaten
• StoneX rates could not be fetched — Verbindungsfehler mit Hostname und Fehlercode
• StoneX response could not be read — unlesbare Antwort
• StoneX rate skipped: Pair missing — übersprungener Eintrag mit seiner Position

Verworfene Kurse stehen zusätzlich in var/log/SwpResourceCalcSix-<Datum>.log der Rohstoffberechnung. Protokolliert wird nur der Hostname der Daten-URL, nie die Token-ID. Wie lange Shopware die Dateien aufbewahrt, bestimmt der Shopware-Parameter shopware.logger.file_rotation_count.

Datenschutz und Einstellungen

• Externer Aufruf ausschließlich an die eingetragene Daten-URL und nur bei eingeschaltetem Kurse bei StoneX abrufen. Gesendet wird die Token-ID als Header, keine Kunden- und keine personenbezogenen Daten.
• Keine Storefront-Erweiterung, keine Cookies.
• Die Token-ID ist in der Administration maskiert, liegt aber im Klartext in der Systemkonfiguration.
• Die Einstellungen werden ohne Verkaufskanal gelesen, also aus Alle Verkaufskanäle. Werte für einzelne Verkaufskanäle bleiben ohne Wirkung.

Update von Versionen vor 6.7.0

• Die Einstellungen Daten-URL und Token-ID behalten ihre Werte.
• Der frühere Kanal-Schalter wird aus der Konfiguration entfernt.
• Ist eine Daten-URL eingetragen, schaltet das Update Kurse bei StoneX abrufen ein.
• Fehlt der Schalter in der Konfiguration ganz, etwa weil der Plugin-Code ohne Plugin-Update ausgetauscht wurde, gilt: eingetragene Daten-URL bedeutet Abruf an.

Deaktivieren und Deinstallieren

• Deaktivieren: Das Plugin ruft keine Kurse mehr ab. Die importierten Kurse bleiben in den Kursdaten.
• Deinstallieren: Das Plugin hat keine eigenen Tabellen. Die Konfiguration samt Token-ID entfernt Shopware, wenn du die Daten nicht behältst; die geplante Aufgabe entfernt Shopware ebenfalls. Die importierten Kurse und die vom Import angelegten Einträge bleiben in den Kursdaten der Rohstoffberechnung.

---

Diese Anleitung wurde für Rohstoffberechnung: Kursimport StoneX Version 6.7.0 erstellt.