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:

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:

Wichtige Konzepte

reybex-Artikelstruktur

Cosmoshop-Produktstruktur

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