Feld-Mapping Dokumentation: reybex → Cosmoshop
Übersicht
Diese Dokumentation beschreibt, welche Felder CosmoshopClient mit Cosmoshop austauscht. Quelle ist der aktuelle Stand von wsendpoint/client/CosmoshopClient.groovy. Die Übertragung läuft über die Cosmoshop SOAP API (XML).
⚠️ WICHTIGER HINWEIS
Diese Dokumentation unterliegt kontinuierlichen Änderungen.
Die Integration zwischen reybex und Cosmoshop befindet sich in ständiger Entwicklung. Daher kann es vorkommen, dass:
- Neue Felder hinzugefügt werden - Um zusätzliche Funktionen zu unterstützen oder neue Cosmoshop-Features zu nutzen
- Felder temporär entfernt werden - Wenn unerwartete Probleme auftreten, die negative Auswirkungen auf die Artikel haben
Empfehlung:
Bitte überprüfen Sie regelmäßig die aktuelle Dokumentation und testen Sie Änderungen in einer Testumgebung, bevor Sie sie in der Produktion einsetzen.
Verwendung dieser Dokumentation
Diese Dokumentation zeigt, welche Felder von reybex nach Cosmoshop übertragen werden und welche Felder beim Bestell- und Artikelimport zurückgelesen werden. Für jedes Cosmoshop-Feld wird angegeben:
- Welches reybex-Feld die Quelle ist
- Unter welcher Bedingung es übertragen wird (Export-Gruppe)
- Besondere Hinweise zur Übertragung
Wichtige Konzepte
reybex-Artikelstruktur
- Material: Ein Artikel/Produkt in reybex (entspricht Cosmoshop Article)
- MaterialVariant: Eine Variante eines Artikels in reybex (z.B. Größe, Farbe)
- MaterialMarktplace: Marktplatz-spezifische Einstellungen für einen Artikel
Cosmoshop-Produktstruktur
- Article: Das Hauptprodukt in Cosmoshop
- Language Content: Mehrsprachige Inhalte
- Media: Produktbilder
Authentifizierung
Jeder Aufruf außer checkConnection holt zuerst eine Session über SOAP login:
| SOAP-Feld | reybex-Quelle |
|---|---|
shopId |
authentication.storeId |
user |
authentication.username |
password |
authentication.password |
Die Antwort liefert shopId, sessionId, signature und time. Diese vier Werte gehen als authInfo in die folgenden Aufrufe. Zusätzlich setzt der Client HTTP-Basic mit authentication.authUsername und authentication.authPassword.
checkConnection ruft nur login auf. Enthält der Body incorrect, gilt der Login als falsch. Ein HTTP 401 wird als ungültiger API-Key bzw. Basic-Auth gemeldet, jede andere Exception als falsche URL.
Timeouts: Connect 50 Sekunden, Read 150 Sekunden. sslTrustAllCerts ist true.
1. Produkt-Felder (Article Level)
updateMaterials sendet die Artikel eines Laufs in einem SOAP-Aufruf setArticles. Ist materialFieldsToExport exakt Bestand, leitet updateMaterials an setStocks weiter. setStocks schreibt dann nur den Bestand. setPrices ruft updateMaterials auf.
articleNumber ist immer material.sku. Alle anderen Blöcke hängen an der Export-Gruppe.
Ist material.isSynchronized gesetzt, gilt der Artikel als vorhanden. Sonst prüft getArticles mit der SKU, ob er in Cosmoshop schon existiert. Ist der Artikel neu und isIgnoredExportFields wahr, werden die Export-Gruppen ignoriert und alle Blöcke gesendet. Ist materialFieldsToExport leer oder null, werden ebenfalls alle Blöcke gesendet. Sonst muss die kommagetrennte Liste das deutsche Label der Gruppe enthalten (Artikeldaten, Kategorie, Preis, Bestand, Beschreibung, SEO, Bild).
1.1 Basis-Informationen
Export-Gruppe: Artikeldaten (ARTIKEL_DATA).
| Cosmoshop Feld | reybex Feld | Beschreibung |
|---|---|---|
article.articleNumber |
material.sku |
Artikelnummer, immer |
article.ean |
material.gtin |
EAN/GTIN |
article.asin |
material.asin |
ASIN |
article.baseUnitId |
Immer 1 |
Basiseinheit-ID |
article.ignoreStockInVariants |
Immer 0 |
Bestand in Varianten ignorieren |
article.maxOrderQuantity |
Immer 100 |
Maximale Bestellmenge |
article.download |
Immer 0 |
Download |
article.displayStock |
Immer 'default' |
Bestandsanzeige |
article.liveshoppingActive |
Immer 0 |
Live-Shopping aktiv |
article.productGroupId |
Immer 0 |
Produktgruppen-ID |
article.notActive |
material.isMarketplaceActive == false ? 1 : 0 |
Inaktiv nur bei explizit false |
article.requestable |
material.isRequestable ? '1' : '0' |
Anfrageartikel |
article.hideArticleOutOfStock |
material.isOnlySellableWithPositiveStock ? '1' : '0' |
Bei Bestand unter 0 ausblenden |
article.stocking |
material.stock.value |
Bestand |
article.onHomepage |
Immer 1 |
Auf Startseite |
article.erpExported |
Immer 0 |
ERP exportiert |
article.vatId |
MwSt.-Satz aus getVatRates |
Cosmoshop-Steuer-ID |
article.packagingUnit |
Immer 1 |
Verpackungseinheit |
article.grossWeight |
material.grossWeight |
Bruttogewicht |
article.netWeight |
material.netWeight |
Nettogewicht |
article.condition |
Immer 0 |
Zustand |
article.manufacturer |
material.brand.name |
Hersteller |
article.liveshoppingStart |
aktuelles Datum/Uhrzeit | Live-Shopping-Start |
article.changed |
aktuelles Datum/Uhrzeit | Änderungszeitpunkt |
vatId ist die id aus SOAP getVatRates, deren value gleich material.vatRate ist. Gibt es keinen Treffer, wird null gesendet. liveshoppingEnd wird nicht gesendet.
material.brand.name wird ohne Nullprüfung gelesen. Fehlt brand, bricht der SOAP-Aufbau für den Lauf ab.
1.2 Kategorien
Export-Gruppe: Kategorie.
| Cosmoshop Feld | reybex Feld | Beschreibung |
|---|---|---|
article.categories.item[].categoryId |
material.categories[].id |
Kategorie-ID |
1.3 Preise
Export-Gruppe: Preis. Es wird genau eine Preisstaffel gesendet.
| Cosmoshop Feld | reybex Feld | Beschreibung |
|---|---|---|
article.recommendedRetailPrice |
material.price.rrp |
UVP |
article.priceSuggest |
Immer 0 |
Preisvorschlag |
article.specialPrice |
Immer 0 |
Sonderpreis |
article.prices.item.price |
material.price.value |
Verkaufspreis |
article.prices.item.currency |
material.price.currency |
Währung |
article.prices.item.percent |
Immer 0 |
Prozent |
article.prices.item.filter |
Immer 'default' |
Filter |
article.prices.item.scaleId |
Immer 1 |
Skalen-ID |
article.prices.item.auto |
Immer 0 |
Automatisch |
article.prices.item.scale |
Immer 1 |
Staffelmenge |
article.prices.item.displayMethod |
Immer 'brutto' |
Anzeige brutto |
Kundengruppenpreise und weitere Staffeln werden nicht übertragen.
1.4 Bestand
Export-Gruppe: Bestand.
| Cosmoshop Feld | reybex Feld | Beschreibung |
|---|---|---|
article.stock.actual |
material.stock.value |
Aktueller Bestand |
article.stock.ignore |
material.isStocked ? 0 : 1 |
1 ignoriert den Bestand, wenn der Artikel nicht bestandsgeführt ist |
article.stock.minStock |
material.reorderStockLevel |
Meldebestand |
Ein Zeitstempel wird nicht mehr gesendet. Zusätzlich steht derselbe Bestand bei aktiver Artikeldaten-Gruppe in article.stocking.
Ist die Exportliste exakt Bestand, übernimmt setStocks den Schreibvorgang. Gibt es Varianten mit SKU (material.variants.items), wird je Variante ein Artikel geschrieben: articleNumber ist variant.sku, stock.actual ist variant.stock. ignore und minStock kommen weiterhin vom Hauptartikel (isStocked, reorderStockLevel). Ohne solche Varianten ist articleNumber die Artikel-SKU und stock.actual ist material.stock.value. Preise, Texte und Bilder gehen in diesem Zweig nicht mit.
1.5 Beschreibung (mehrsprachig)
Export-Gruppe: Beschreibung. Eine languageContent.item-Zeile pro Eintrag in material.translations.
| Cosmoshop Feld | reybex Feld | Beschreibung |
|---|---|---|
languageCode |
translation.language |
Sprachcode |
descriptionIsPlain |
Immer 0 |
Beschreibung nicht als Plain-Text-Flag |
urlkey |
translation.urlkey |
URL-Schlüssel, siehe Hinweis |
imagesAltText |
translation.imagesAltText |
Bild-Alt-Text |
name |
material.name, sonst translation.name |
Produktname, derselbe Artikelname für jede Sprache |
description |
Text aus HTML, siehe Hinweis | Beschreibung ohne Tags |
descriptionShort |
material.description |
Kurztext, nicht je Übersetzung |
descriptionHtml |
material.detailDescription, sonst translation.detailDescription |
HTML-Beschreibung |
description ist Jsoup.parse(...).text() von material.detailDescription, sonst material.description, sonst translation.description. urlkey ersetzt Leerzeichen durch - und danach Umlaute (ä→ae, ö→oe, ü→ue, ß→ss, inklusive Großschreibung).
1.6 SEO-Felder
Export-Gruppe: SEO. Nur Übersetzungen mit language == "de".
| Cosmoshop Feld | reybex Feld |
|---|---|
article.seo.title.item.languageCode / value |
de / translation.metaTitle |
article.seo.description.item.languageCode / value |
de / translation.metaDescription |
article.seo.keywords.item.languageCode / value |
de / translation.keyWord |
Andere Sprachen erzeugen keinen seo-Block.
1.7 Verteilung
Export-Gruppe: Artikeldaten, innerhalb desselben Blocks wie die Basisdaten.
| Cosmoshop Feld | reybex Feld |
|---|---|
distributionInfo.avgDeliveryTime |
immer leer |
distributionInfo.salesPerDay |
immer leer |
distributionInfo.articleNumber |
material.manufacturer.number |
distributionInfo.distributorId |
immer 0 |
distributionInfo.price |
material.purPrice |
distributionInfo.deliveryDate |
leeres Element |
1.8 Bilder
Export-Gruppe: Bild. Der Client prüft hier das Label Bild, nicht den Enum-Namen. Zusätzlich muss material.refreshPictures wahr sein und material.images gesetzt sein.
Ablauf: zuerst deleteArticleMedia für diese SKUs, danach setArticleMedia.
| Cosmoshop Feld | Inhalt |
|---|---|
articleNumber |
material.sku |
media.item.type |
immer image |
media.item.id |
immer 0 |
preview / normal / detail |
Dateiname und Base64-Daten |
Genau ein Bild (material.images.size() == 1): das Bild wird von der URL geladen und auf drei Quadrate skaliert.
| Variante | Kantenlänge | Dateiname |
|---|---|---|
preview |
160 px | preview_ + Originaldateiname |
normal |
500 px | normal_ + Originaldateiname |
detail |
800 px | detail_ + Originaldateiname |
Mehr als ein Bild: es wird nichts skaliert. material.images.image wird anhand des Dateinamens sortiert. Enthält der Name preview, geht die Datei nach preview, enthält er detail, nach detail, sonst nach normal. filename und fileContent werden so gesendet, wie sie am Bild stehen.
2. Export-Felder-Gruppen
Label in materialFieldsToExport |
Enum | Cosmoshop-Felder |
|---|---|---|
Artikeldaten |
ARTIKEL_DATA | Basisblock inkl. distributionInfo |
Beschreibung |
DESCRIPTION | languageContent |
SEO |
SEO | seo nur für de |
Preis |
PRICE | recommendedRetailPrice, eine prices-Zeile |
Bestand |
STOCK | im vollen Export stock am Artikel; ist die Liste exakt Bestand, nur setStocks |
Kategorie |
CATEGORY | categories |
Bild |
IMAGE | deleteArticleMedia und setArticleMedia |
Leere Liste oder neuer Artikel mit isIgnoredExportFields: alle Gruppen.
Die Export-Gruppe Variant wird in updateMaterials nicht ausgewertet. Varianten-SKUs gehen nur im reinen Bestandsaufruf setStocks mit, und dort nur als Bestandszeile.
3. Artikel deaktivieren
disableMaterials sendet setArticles mit nur zwei Feldern je SKU:
| Cosmoshop Feld | Wert |
|---|---|
articleNumber |
material.sku |
notActive |
1 |
Bilder, Preise und Bestände bleiben unangetastet. deleteArticles ist im Client vorhanden, wird von keiner Methode aufgerufen.
4. Artikelimport (listMaterials)
SOAP getArticleNumbers mit rowCount (Standard 500) und offset (Standard 0). Ist articleNumbers gesetzt, werden diese SKUs direkt verwendet, ohne Nummernabruf. maxMaterialCountToImport schneidet die Liste ab. Artikel werden in Blöcken von 500 über getArticles geladen. Schlägt ein Block fehl, wird jede SKU einzeln geladen. Eine einzelne fehlerhafte Antwort wird übersprungen.
| reybex-Feld | Cosmoshop-Feld |
|---|---|
matCode, sku |
articleNumber |
gtin |
ean |
name |
languageContent.item.name |
description |
languageContent.item.descriptionShort |
detailDescription |
languageContent.item.descriptionHtml |
purchasePrice |
distributionInfo.price, sonst 0.0 |
currency |
Währung der Preiszeile mit filter = default |
salesPrice |
price dieser Zeile, sonst 0.0 |
isPriceGross |
displayMethod == brutto |
manufacturer |
manufacturer |
manufacturerNumber |
distributionInfo.articleNumber |
vatRate |
value aus getVatRates zur vatId |
asin |
asin |
netWeight, grossWeight |
gleichnamige Felder |
rrp |
recommendedRetailPrice, sonst 0.0 |
stock |
stock.actual |
minOrderQuantity |
stock.minStock (Export schreibt hierher reorderStockLevel) |
categories[].marketplaceCategoryId |
categories.item.categoryId |
isRequestable |
requestable |
isOnlySellableWithPositiveStock |
hideArticleOutOfStock |
images |
getArticleMedia, Typen normal, preview, detail, nur id = 0 |
translations[] |
languageContent plus SEO-Texte des Artikels |
normal ist das Hauptbild (isMainPicture = true). detail und preview sind Nebenbilder. Die Bilddaten stehen in data, url bleibt leer.
Kombinationen (combinations.item) werden je Artikelnummer über ein weiteres getArticles als Varianten gelesen. Der Variantenpreis bleibt netto, wenn displayMethod nicht brutto ist, und wird sonst mit dem MwSt.-Satz auf zwei Stellen brutto gerechnet. Attribute kommen aus options: label als attributeCode, variantLabel als optionCode.
5. Bestellimport (listOrders)
SOAP getOrders. Ohne startValue/endValue filtert statusId. Standard ist 1, überschrieben durch marktplaceOrderTypeIds (kommagetrennt, je Status ein Filter). Mit startValue und endValue wird jede Bestellnummer in diesem Bereich als orderNumber abgefragt. maxOrderCountToImport bricht die Schleife ab.
Eine Bestellung wird nur übernommen, wenn sie mindestens eine echte Position und ein Adresselement hat. Positionen mit baseArticleNumber versand oder zahlung sind keine Artikelpositionen.
5.1 Kopf
| reybex-Feld | Cosmoshop-Feld |
|---|---|
order.id |
orderNumber |
order.orderDate |
created, Format yyyy-MM-dd HH:mm:ss |
order.email |
extraInvoicemail der Rechnungsadresse, sonst email |
order.isPriceTypeGross |
priceDisplayMethod der Bestellung, siehe Preisbasis |
order.transactionNumber |
paymentTransactionId |
order.customerComment |
notice |
order.paymentType |
name der Position baseArticleNumber = zahlung, sonst Offen |
order.shippingType |
logisticsCompany |
order.costs.shippingPriceForOrder |
netTotal der Position versand, plus vatPerItem nur bei Bruttobasis |
order.costs.klarnaInvoiceCost |
netPerItem der Position zahlung, plus vatPerItem nur bei Bruttobasis |
order.account.* |
paymentInfo, Schlüssel payerId, bankIban, bankBic, bankName, bankHolder |
invoiceAddress.groupKey |
customerGroup, nur wenn nicht leer |
invoiceAddress.costCenterKey |
Costcenter, nur wenn nicht leer |
paymentStatus ist Offen bei Vorkasse, Nachnahme und Rechnung. Jeder andere Zahlungsname, auch der Fallback Offen wenn keine Zahlungsposition existiert, wird Komplett bezahlt.
Lieferadresse ist type = lief. Sind Firma, Vorname, Nachname, Straße, Hausnummer, Ort, PLZ und countryIso gleich der Rechnungsadresse, wird keine Lieferadresse gesetzt.
Adressfelder:
Die Firma steht in Cosmoshop in addressAddition. company ist dort leer. companyName ist deshalb addressAddition, und nur wenn das leer ist, company.
| reybex | Cosmoshop |
|---|---|
name, addressLine1 |
companyName, sonst firstName + lastName |
company |
companyName |
addressLine2 |
bei Firma der Personenname, wenn er von der Firma abweicht, sonst leer; ohne Firma die Postnummer der Packstation |
salutation |
m → Herr, w → Frau, f → Firma, sonst leer |
email |
email |
invoiceEmail |
extraInvoicemail |
phone, fax |
gleichnamige Felder |
street |
Packstation, sonst street + streetNumber |
city |
city |
province |
immer leer |
zipCode |
zip, sonst - |
customerUstId |
vatNo |
country.code |
countryIso |
Der Vergleich, ob Rechnungs- und Lieferadresse gleich sind, berücksichtigt zusätzlich addressAddition.
5.2 Positionen
| reybex | Cosmoshop |
|---|---|
id |
baseArticleNumber |
sku |
optionId, wenn gesetzt und nicht 0, sonst articleNumber, sonst baseArticleNumber |
alternativeSku |
articleNumber, sonst baseArticleNumber |
quantity |
amount |
openQuantity |
0, wenn stockPosted gleich 1 ist, sonst amount |
price.value |
netPerItem, plus vatPerItem nur bei Bruttobasis |
price.currency |
order.currency |
isGrossPrice |
Ergebnis von priceDisplayMethod, kann null sein |
name |
name |
shippingPrice.value |
immer 0 |
variant |
immer leer |
customFields, nur wenn der SOAP-Knoten Text enthält:
reybex customFields |
SOAP-Kind |
|---|---|
returnDate |
returnDate |
downloadUrl |
downloadUrl |
rentaleFrom |
rentalsFrom |
rentalsTo |
rentalsTo |
rentalsMode |
rentalsMode |
Der Schlüssel rentaleFrom ist so im Client geschrieben.
5.3 Preisbasis
priceDisplayMethod am Auftrag steuert Netto oder Brutto:
| SOAP-Wert | isPriceTypeGross |
Übernommener Betrag |
|---|---|---|
brutto |
true |
netPerItem bzw. netTotal plus vatPerItem |
netto |
false |
nur netPerItem bzw. netTotal |
| fehlt oder anderer Text | null |
wie Brutto, weil nur explizites false die Steuer weglässt |
Dasselbe gilt für Versand (baseArticleNumber = versand, Basis netTotal) und Zahlungsgebühr (baseArticleNumber = zahlung, Basis netPerItem).
applyPriceRoundingForRecalculate steht im Client, der Aufruf in listOrders ist auskommentiert. Der Import rundet Positions- und Versandpreise an dieser Stelle nicht auf zwei Nachkommastellen. Die SOAP-Zahlen werden als Double übernommen.
6. Versandstatus (updateOrders)
Je Bestellung ein SOAP setOrder:
| Cosmoshop Feld | reybex |
|---|---|
orderNumber |
order.id |
trackingNumber |
order.licensePlate |
status |
marktplaceStatusShipped, sonst 2 |
updateOrdersToProcess sendet keinen Status. Die Methode gibt eine leere Map zurück. uploadOrderInvoices und listReturns sind nicht implementiert.
7. Weitere SOAP-Aufrufe
| Aktion | SOAP-Methode |
|---|---|
| Verbindungstest und Session | login |
| Artikel schreiben | setArticles |
| Artikel lesen | getArticles |
| Artikelnummern | getArticleNumbers |
| Existenzprüfung einer SKU | getArticles |
| Bilder löschen | deleteArticleMedia |
| Bilder schreiben | setArticleMedia |
| Bilder lesen | getArticleMedia |
| Kategorien | getCategories (numericId, name.item.value, parentNumericId; 0 wird zu keiner Parent-ID) |
| MwSt.-Sätze | getVatRates |
| Bestellungen | getOrders |
| Versandstatus | setOrder |
| Artikelanzahl | getArticleNumbers mit rowCount = 1, offset = 1, Ergebnis pagination.total |
getApiVersion liefert No Version. getOrderCount liefert 0 und ruft Cosmoshop nicht auf. getInventoryReport, getReport, uploadDataToMarketplace und listMarketplaceSpecificData liefern leere Ergebnisse.
8. Zusammenfassung: Export-Mappings
| Cosmoshop Feld | reybex Feld | Gruppe | Hinweis |
|---|---|---|---|
articleNumber |
material.sku |
immer | |
ean |
material.gtin |
Artikeldaten | |
asin |
material.asin |
Artikeldaten | |
vatId |
Treffer aus getVatRates |
Artikeldaten | |
manufacturer |
material.brand.name |
Artikeldaten | |
stocking |
material.stock.value |
Artikeldaten | |
categories.item[].categoryId |
material.categories[].id |
Kategorie | |
recommendedRetailPrice |
material.price.rrp |
Preis | |
prices.item.price |
material.price.value |
Preis | displayMethod = brutto |
stock.actual |
material.stock.value oder variant.stock |
Bestand | Varianten nur in setStocks |
stock.ignore |
material.isStocked ? 0 : 1 |
Bestand | |
stock.minStock |
material.reorderStockLevel |
Bestand | |
languageContent |
material.translations |
Beschreibung | Name und Kurztext vom Artikel |
seo.* |
deutsche Übersetzung | SEO | nur de |
distributionInfo.articleNumber |
material.manufacturer.number |
Artikeldaten | |
distributionInfo.price |
material.purPrice |
Artikeldaten | |
media |
material.images |
Bild | nur bei refreshPictures |
notActive |
0 oder 1 aus isMarketplaceActive |
Artikeldaten | false setzt 1 |
notActive |
1 |
Deaktivieren | nur disableMaterials |
Version: 1.2
Stand: 2026-10-23
Quelle: reybex/src/main/groovy/wsendpoint/client/CosmoshopClient.groovy