Veröffentlicht von Markus Wals

Artikel und Bezugsquellen per weclapp-API importieren: der Leitfaden für Migrationen

API Artikelstamm Einkauf Migration weclapp

KI-generierte Illustration: Artikelkarten und drei Lieferantenkisten mit Preisschildern und Staffelstufen wandern durch ein rotes Rohr mit Schnittstelle in einen Aktenschrank. Überschrift: Bezugsquellen per API importieren

Kurz gesagt: In weclapp ist eine Bezugsquelle ein eigener Datensatz (articleSupplySource) mit Lieferant, Einkaufspreisen, Rabatten, Zuschlägen, Staffeln und Mindestmenge. Am Artikel hängt sie erst, wenn du sie dort über supplySources und primarySupplySourceId verknüpfst. Wer migriert, legt Lieferanten, Artikel und Bezugsquellen in dieser Reihenfolge an, prüft jeden Schreibzugriff vorher per dryRun und gleicht beim zweiten Lauf über Artikelnummer und Lieferant ab, statt neu anzulegen.

Wir migrieren Altsysteme nach weclapp, betreiben Artikelimporter für Händler mit vielen Lieferanten und schulen Partner auf die weclapp-API. Zuletzt kam die Frage aus einem laufenden Migrationsprojekt: Die Artikel waren übernommen, die Bezugsquellen nicht, also je Artikel ein bis fünf Lieferanten mit Einkaufspreis. Dieser Artikel ist der Leitfaden für genau diesen Schritt: das Datenmodell, die Reihenfolge, alle Requests als cURL, die Stolperstellen aus unserem Testlauf und der Aufbau eines Importers, der beim zweiten Lauf nichts doppelt anlegt. Wie du Lagerplätze übernimmst, zeigt der Leitfaden Lagerplätze per weclapp-API anlegen und migrieren, die Anbindung eines Fulfillers der Leitfaden zur Fulfiller-Anbindung an weclapp.

Das Wichtigste in Kürze

  • Drei Datensätze, eine Reihenfolge: Lieferant (party), Artikel (article), Bezugsquelle (articleSupplySource). Die Verknüpfung entsteht am Artikel, nicht an der Bezugsquelle.
  • Einkaufspreise leben an der Bezugsquelle: Listenpreis, Rabatte und Zuschläge (reductionAdditions), Staffeln (priceScaleValue), Mindest- und feste Bestellmenge, Lieferzeit.
  • Listen werden ersetzt: Schickst du supplySources am Artikel mit, gilt genau diese Liste. Was fehlt, ist danach weg.
  • Nur API v2: v2 lehnt unbekannte Felder mit Fehler ab. v1 nimmt sie an, und dabei entstehen Bezugsquellen, die an keinem Artikel hängen.
  • Idempotent statt einmalig: Schlüssel sind Artikelnummer und Lieferant. Geschrieben wird nur, was sich geändert hat.

Das Datenmodell: Artikel, Lieferant, Bezugsquelle

In vielen Altsystemen ist der Lieferant eine Spalte am Artikel, oft mit „Lieferant 1“ bis „Lieferant 5“ und je einem Einkaufspreis daneben. weclapp trennt das sauber. Der Lieferant ist ein Geschäftspartner mit dem Merkmal „Lieferant“. Die Bezugsquelle ist ein eigener Datensatz, der den Lieferanten referenziert und alles trägt, was den Einkauf bei genau diesem Lieferanten beschreibt: dessen Artikelnummer und Bezeichnung, Einkaufspreise mit Staffeln, Rabatten und Zuschlägen, Mindestbestellmenge, feste Bestellmenge, Lieferzeit in Tagen, Herstellernummer und EAN.

Der Artikel kennt seine Bezugsquellen über zwei Felder: die Liste supplySources (welche Quellen in welcher Reihenfolge) und primarySupplySourceId (welche davon die primäre ist). Die Bezugsquelle selbst hat in v2 kein Feld für den Artikel. Das ist die wichtigste Erkenntnis für jede Migration, denn genau hier gehen die meisten Importe schief.

Im Altsystem In weclapp (API v2) Hinweis
Artikelnummer article.articleNumber Eindeutig, dein Schlüssel für den Abgleich
Lieferant 1 bis 5 party mit supplier: true, referenziert über articleSupplySource.supplierId Vorher anlegen oder per Suche zuordnen
Bestellnummer beim Lieferanten articleSupplySource.articleNumber Steht auf der Bestellung
Bezeichnung beim Lieferanten articleSupplySource.name Pflichtfeld
Einkaufspreis articlePrices[].price mit currencyId Eine Zeile je Staffel
Staffelpreis ab Menge priceScaleType: SCALE_FROM, priceScaleValue Erste Staffel ab 0
Rabatt, Zuschlag articlePrices[].reductionAdditions[] Prozentual oder absolut, mehrere je Preis
Mindestbestellmenge minimumPurchaseQuantity
Verpackungseinheit beim Lieferanten fixedPurchaseQuantity Feste Bestellmenge
Lieferzeit in Tagen procurementLeadDays
Hauptlieferant article.primarySupplySourceId Muss in supplySources stehen
Reihenfolge der Lieferanten article.supplySources[].positionNumber

Fazit: Plane die Migration in drei Datensätzen und einem Verknüpfungsschritt, nicht als Spalten am Artikel.

Fünf Grundregeln, bevor du den ersten Request schickst

1. Nur API v2

Alle Requests in diesem Artikel laufen gegen /webapp/api/v2. Laut weclapp-Changelog wurden an der Bezugsquelle in v2 die Felder unitName, supplierNumber und articlePrices[n].currencyName entfernt. Wichtiger ist das Verhalten: v2 lehnt unbekannte Felder mit 400 ab. v1 nimmt sie stillschweigend an, und das kostet dich im Zweifel Tage.

2. Projektion bei jedem GET

Jeder Lesezugriff bekommt properties mit genau den Feldern, die du brauchst, auch verschachtelt wie articlePrices.price. Den Lieferanten zur Bezugsquelle lädst du im selben Request per includeReferencedEntities=supplierId mit, nie einzeln nach. Listen paginierst du mit pageSize; die Doku nennt 100 als Standard und 1000 als übliche Obergrenze.

3. dryRun vor jedem Schreibzugriff

POST, PUT und DELETE akzeptieren dryRun=true. weclapp prüft dann alles wie bei einem echten Aufruf und antwortet mit 200 und der fertigen Entität, nur ohne ID, Version und Zeitstempel. Validierungsfehler wie Dubletten oder unbekannte Felder siehst du so, bevor ein Datensatz entsteht.

4. PUT nur mit ignoreMissingProperties=true und version

Ohne den Parameter ist ein PUT ein vollständiges Update: Was du nicht mitschickst, wird geleert. Die version schickst du immer mit. Hat sich der Datensatz seit deinem Lesen geändert, antwortet weclapp mit 409 optimistic lock error, statt fremde Änderungen zu überschreiben.

5. Listen im Body sind vollständig

Für Listen wie supplySources oder articlePrices gilt laut Doku: Fehlt ein bestehender Eintrag im Body, wird er entfernt. Bestehende Einträge erkennt weclapp an ihrer id. Wer einen Lieferanten ergänzen will, schickt also die vorhandenen Einträge mit und hängt den neuen an.

Fazit: v2, Projektion, dryRun, Teilupdate mit Version und vollständige Listen verhindern fast alle Fehler, die wir in Migrationen sehen.

Der Ablauf in sieben Schritten

Die Beispiele zeigen ein Rillenkugellager mit zwei Lieferanten. Lieferant Nord liefert mit Warengruppenrabatt, Teuerungszuschlag und Staffelpreis ab 50 Stück, Lieferant Süd nur in 25er-Gebinden mit Projektrabatt. Die IDs stammen aus unserem Testlauf und lauten bei dir anders. Den Token ersetzt du durch deinen API-Token.

Ablauf des Imports von Artikeln und Bezugsquellen nach weclapp: Altsystem und Lieferantendateien, Importer mit Abgleich und dryRun, weclapp API v2 mit Lieferant, Artikel, Bezugsquelle und Verknüpfung am Artikel

Schritt 1: Referenzdaten einmal lesen

Einheit und Währung brauchst du als ID in jedem Artikel und jedem Preis. Lies sie einmal zu Beginn und halte sie im Speicher.

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/unit?name-eq=Stk.&properties=id,name' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'
curl --location 'https://testhandel.weclapp.com/webapp/api/v2/currency?name-eq=EUR&properties=id,name' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'

Schritt 2: Lieferanten suchen oder anlegen

Jeder Lieferant aus dem Altsystem wird einmal zugeordnet. Suche zuerst, lege nur an, wenn die Suche leer bleibt. Die Zuordnung Altsystem-Lieferant zu weclapp-ID speicherst du in deinem Mapping, damit der nächste Lauf nicht wieder sucht.

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/party?supplier-eq=true&company-eq=Musterlieferant%20Nord%20GmbH&properties=id,company,supplierNumber' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'
curl --location 'https://testhandel.weclapp.com/webapp/api/v2/party' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AuthenticationToken: ****' \
--data '{
  "partyType": "ORGANIZATION",
  "company": "Musterlieferant Nord GmbH",
  "supplier": true
}'

weclapp vergibt die Lieferantennummer selbst und antwortet mit 201 und der neuen ID. Steht im Altsystem eine eigene Lieferantennummer, die du behalten willst, ist das eine Entscheidung vor dem ersten Lauf, nicht danach.

Schritt 3: Artikel anlegen, erst als dryRun

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/article?dryRun=true' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AuthenticationToken: ****' \
--data '{
  "articleNumber": "BZQ-1001",
  "name": "Rillenkugellager 6204-2RS, 20 × 47 × 14 mm",
  "articleType": "STORABLE",
  "unitId": "3560",
  "taxRateType": "STANDARD",
  "active": true
}'

Kommt 200 zurück, schickst du denselben Body ohne dryRun und bekommst 201 mit der Artikel-ID. Existiert die Artikelnummer schon, scheitert bereits der dryRun:

{
  "status": 400,
  "title": "validation failed",
  "validationErrors": [{
    "detail": "entity is a duplicate",
    "location": "articleNumber"
  }]
}

Das ist deine Sicherung gegen Dubletten. Verlass dich aber nicht nur darauf: Wer vorher per articleNumber-eq sucht, weiß, ob er anlegen oder abgleichen muss. Achtung bei fehlenden Feldern: Im Testlauf hat weclapp ohne unitId nicht abgelehnt, sondern die Standardeinheit des Mandanten gesetzt. Schick die Einheit deshalb immer ausdrücklich mit.

Schritt 4: Bezugsquelle mit Einkaufspreis, Rabatt, Zuschlag und Staffel

Die erste Bezugsquelle für Lieferant Nord: Listenpreis 48,00 Euro, ab 50 Stück 44,50 Euro, auf beide Staffeln 35 Prozent Warengruppenrabatt und 4 Prozent Teuerungszuschlag, Mindestbestellmenge 10, Lieferzeit 5 Tage.

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/articleSupplySource' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AuthenticationToken: ****' \
--data '{
  "supplierId": "554184",
  "articleNumber": "N-77812",
  "name": "Kugellager 6204 2RS",
  "unitId": "3560",
  "taxRateType": "STANDARD",
  "dropshippingPossible": false,
  "ignoreInDropshippingAutomation": false,
  "minimumPurchaseQuantity": "10",
  "procurementLeadDays": 5,
  "articlePrices": [
    {
      "currencyId": "256",
      "price": "48.00",
      "priceScaleType": "SCALE_FROM",
      "priceScaleValue": "0",
      "reductionAdditions": [
        { "name": "Rabatt Warengruppe", "type": "REDUCTION_PERCENT", "value": "35" },
        { "name": "Teuerungszuschlag", "type": "ADDITION_PERCENT", "value": "4" }
      ]
    },
    {
      "currencyId": "256",
      "price": "44.50",
      "priceScaleType": "SCALE_FROM",
      "priceScaleValue": "50",
      "reductionAdditions": [
        { "name": "Rabatt Warengruppe", "type": "REDUCTION_PERCENT", "value": "35" },
        { "name": "Teuerungszuschlag", "type": "ADDITION_PERCENT", "value": "4" }
      ]
    }
  ]
}'

Für Rabatte und Zuschläge kennt weclapp vier Typen: REDUCTION_PERCENT und REDUCTION_ABS für Rabatte, ADDITION_PERCENT und ADDITIONAL_ABS für Zuschläge. Gültigkeiten pflegst du bei Bedarf je Preiszeile über startDate und endDate.

Was du hier nicht mitschicken darfst, ist der Artikel. Wer aus einem v1-Skript articleId übernimmt, bekommt in v2:

{
  "status": 400,
  "validationErrors": [{
    "detail": "property articleId is unknown",
    "errorCode": "platform.unknown_property",
    "location": "articleId"
  }]
}

Dasselbe passiert mit currencyName in der Preiszeile. Beides ist gut so: Der Fehler zeigt dir sofort, dass die Verknüpfung woanders hingehört.

Schritt 5: Weitere Lieferanten für denselben Artikel

Jeder weitere Lieferant ist eine weitere Bezugsquelle. Lieferant Süd liefert nur in 25er-Gebinden, mit 1,50 Euro Projektrabatt je Stück und 12 Tagen Lieferzeit:

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/articleSupplySource' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AuthenticationToken: ****' \
--data '{
  "supplierId": "554189",
  "articleNumber": "S-RB45-150",
  "name": "Rillenkugellager 6204-2RS C3",
  "unitId": "3560",
  "taxRateType": "STANDARD",
  "dropshippingPossible": false,
  "ignoreInDropshippingAutomation": false,
  "minimumPurchaseQuantity": "25",
  "fixedPurchaseQuantity": "25",
  "procurementLeadDays": 12,
  "articlePrices": [
    {
      "currencyId": "256",
      "price": "33.90",
      "priceScaleType": "SCALE_FROM",
      "priceScaleValue": "0",
      "reductionAdditions": [
        { "name": "Projektrabatt", "type": "REDUCTION_ABS", "value": "1.50" }
      ]
    }
  ]
}'

Bei fünf Lieferanten je Artikel sind das fünf solcher Requests. Nach diesem Schritt existieren beide Bezugsquellen, hängen aber an keinem Artikel. In der Oberfläche siehst du sie am Artikel noch nicht.

Schritt 6: Bezugsquellen am Artikel verknüpfen und die primäre setzen

Erst jetzt kommt der Artikel ins Spiel. Lies seine aktuelle version und schicke ein Teilupdate mit der vollständigen Liste und der primären Quelle:

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/article?articleNumber-eq=BZQ-1001&properties=id,version,primarySupplySourceId,supplySources' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'
curl --location --request PUT 'https://testhandel.weclapp.com/webapp/api/v2/article/id/554194?ignoreMissingProperties=true' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AuthenticationToken: ****' \
--data '{
  "version": "0",
  "primarySupplySourceId": "554198",
  "supplySources": [
    { "articleSupplySourceId": "554198", "positionNumber": 1 },
    { "articleSupplySourceId": "554207", "positionNumber": 2 }
  ]
}'

Den Request schickst du wie alle Schreibzugriffe zuerst mit &dryRun=true. Danach steht die Version des Artikels auf 1, und jeder Listeneintrag hat eine eigene id. Ab jetzt gilt die Replace-Semantik aus Grundregel 5, und weclapp bewacht die primäre Quelle streng. Diese Antworten hat uns der dryRun im Testlauf geliefert:

Was du schickst Was passiert
supplySources nur mit Süd, die primäre Quelle Nord fehlt 400: „primarySupplySourceId … was removed from the list of supply sources, but not updated“
primarySupplySourceId auf Süd, Liste nur mit Nord 400: „primarySupplySourceId … is not linked to any article of this packaging unit structure“
supplySources nur mit Nord (primär) 200: Süd fällt aus der Liste, ohne Warnung
Nur primarySupplySourceId auf Süd, Liste nicht im Body 200: Primäre Quelle wechselt, die Liste bleibt unverändert
Veraltete version 409: „optimistic lock error“

Die dritte Zeile ist die gefährliche. Willst du einen Lieferanten ergänzen, liest du die Liste, hängst den neuen Eintrag an und schickst alle Einträge zurück. Laut Doku genügt für bestehende Einträge ihre id. Willst du nur den Hauptlieferanten wechseln, lässt du die Liste ganz weg.

Schritt 7: Ergebnis zurücklesen

Ein Request zeigt dir den Artikel mit seiner primären Bezugsquelle samt Preisen:

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/article?articleNumber-eq=BZQ-1001&properties=id,version,primarySupplySourceId,supplySources&includeReferencedEntities=primarySupplySourceId' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'

Die Bezugsquelle steht dann unter referencedEntities.articleSupplySource. Für die Gegenprobe über alle Lieferanten liest du die Quellen mit verschachtelter Projektion und lädst den Lieferanten gleich mit:

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/articleSupplySource?id-eq=554198&properties=id,articleNumber,supplierId,minimumPurchaseQuantity,articlePrices.price,articlePrices.priceScaleValue,articlePrices.reductionAdditions&includeReferencedEntities=supplierId' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'

Für die Abnahme nach der Migration hilft der Filter auf Artikel ohne primäre Bezugsquelle. Jeder Treffer ist ein Artikel, bei dem die Verknüpfung fehlt:

curl --location 'https://testhandel.weclapp.com/webapp/api/v2/article?primarySupplySourceId-null=true&articleType-eq=STORABLE&properties=id,articleNumber&page=1&pageSize=1000' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'

Ohne pageSize liefert weclapp laut Doku nur die ersten 100 Treffer. Für die Abnahme und für das Laden des Bestands erhöhst du page so lange, bis eine Seite weniger Einträge liefert als pageSize.

Fazit: Lieferant, Artikel und Bezugsquelle entstehen unabhängig voneinander, verbunden werden sie in genau einem PUT am Artikel.

Der zweite Lauf: idempotent abgleichen statt neu anlegen

Eine Migration läuft nie nur einmal. Es gibt Probeläufe, eine Stichtagsübernahme und oft danach regelmäßige Preislisten der Lieferanten. Der Importer muss deshalb jeden Datensatz wiederfinden und nur schreiben, was sich geändert hat.

  1. Artikel über die Artikelnummer finden und die IDs seiner verknüpften Bezugsquellen aus supplySources lesen.
  2. Die Bezugsquelle über Lieferant und Bestellnummer suchen (supplierId-eq und articleNumber-eq), nicht nur unter den verknüpften IDs. Ist ein früherer Lauf zwischen Anlegen und Verknüpfen abgebrochen, existiert die Quelle schon, hängt aber an keinem Artikel. Diese Suche findet sie, und du verknüpfst sie, statt eine zweite anzulegen.
  3. Verknüpfung prüfen: Steht die gefundene ID nicht in supplySources, hängst du sie wie in Schritt 6 an. Hat der Artikel noch gar keine Quellen, entfällt der Abgleich der Liste.
  4. Preise vergleichen, nicht Zeichenketten. Du schickst "48.00", weclapp liefert "48" zurück. Vergleiche Preise, Staffeln, Rabatte und Zuschläge als Dezimalzahlen und sortiert.
  5. Nur bei Abweichung schreiben, mit dryRun, dann echt, dann zurücklesen.
curl --location 'https://testhandel.weclapp.com/webapp/api/v2/articleSupplySource?supplierId-eq=554184&articleNumber-eq=N-77812&properties=id,version,articleNumber,articlePrices' \
--header 'Accept: application/json' \
--header 'AuthenticationToken: ****'

Wer mehrere Quellen auf einmal liest, etwa alle verknüpften eines Artikels, nutzt id-in=[554198,554207] und dazu --globoff, weil cURL eckige Klammern sonst als Muster liest. Hat Lieferant Nord seinen Teuerungszuschlag auf 6 Prozent erhöht und eine dritte Staffel ab 200 Stück eingeführt, schickst du die neue Preisliste vollständig:

curl --location --request PUT 'https://testhandel.weclapp.com/webapp/api/v2/articleSupplySource/id/554198?ignoreMissingProperties=true' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--header 'AuthenticationToken: ****' \
--data '{
  "version": "1",
  "articlePrices": [
    { "currencyId": "256", "price": "48.00", "priceScaleType": "SCALE_FROM", "priceScaleValue": "0",
      "reductionAdditions": [
        { "name": "Rabatt Warengruppe", "type": "REDUCTION_PERCENT", "value": "35" },
        { "name": "Teuerungszuschlag", "type": "ADDITION_PERCENT", "value": "6" } ] },
    { "currencyId": "256", "price": "44.50", "priceScaleType": "SCALE_FROM", "priceScaleValue": "50",
      "reductionAdditions": [
        { "name": "Rabatt Warengruppe", "type": "REDUCTION_PERCENT", "value": "35" },
        { "name": "Teuerungszuschlag", "type": "ADDITION_PERCENT", "value": "6" } ] },
    { "currencyId": "256", "price": "42.00", "priceScaleType": "SCALE_FROM", "priceScaleValue": "200",
      "reductionAdditions": [
        { "name": "Rabatt Warengruppe", "type": "REDUCTION_PERCENT", "value": "35" },
        { "name": "Teuerungszuschlag", "type": "ADDITION_PERCENT", "value": "6" } ] }
  ]
}'

Weil die Preiszeilen ohne id kommen, ersetzt weclapp die alten Zeilen durch neue mit neuen IDs. Für eine Preisliste ist das gewollt. Zwei Beobachtungen aus dem Testlauf solltest du kennen: Die Version der Bezugsquelle steigt, und die Version des Artikels steigt ebenfalls, weil sich sein Listeneintrag zur Quelle mit ändert. Lies die Artikelversion deshalb nach allen Schreibzugriffen auf Bezugsquellen frisch, bevor du am Artikel etwas verknüpfst, sonst läufst du in den 409. Ein zweiter Lauf mit derselben Preisliste findet keine Abweichung und schreibt nichts.

Fazit: Ein Importer, der vergleicht statt schreibt, lässt sich beliebig oft starten, und genau das brauchst du für Probeläufe und Stichtag.

v1 gegen v2: was sich für Bezugsquellen ändert

Viele bestehende Importskripte laufen noch gegen v1. Für Bezugsquellen sind die Unterschiede klein im Schema und groß in der Wirkung:

Thema API v1 API v2
articleId an der Bezugsquelle Wird angenommen (201), die Quelle hängt aber an keinem Artikel 400: „property articleId is unknown“
currencyName in der Preiszeile Wird angenommen 400: unbekanntes Feld, nur currencyId
supplierNumber, unitName in der Antwort Enthalten Entfernt, Lieferant per includeReferencedEntities=supplierId
Bezug in Bestellpositionen supplierArticleId articleSupplySourceId

Die erste Zeile ist der Grund für diesen Abschnitt. Im Testlauf hat v1 eine Bezugsquelle mit articleId ohne Fehler angelegt, der Artikel hatte danach trotzdem keine einzige Bezugsquelle. Bei tausenden Artikeln bemerkst du das erst, wenn der Einkauf fragt, warum keine Bestellvorschläge kommen. Solche verwaisten Quellen findest du, indem du alle Quellen eines Lieferanten (supplierId-eq) gegen die verknüpften IDs aus supplySources deiner Artikel abgleichst. Löschen kannst du sie per DELETE /articleSupplySource/id/<id>, ebenfalls zuerst mit dryRun.

Fazit: Migriere das Skript vor den Daten, v2 macht aus stillen Fehlern laute.

So ist ein produktiver Importer aufgebaut

Für eine einmalige Migration reicht ein Skript. Kommen danach regelmäßig Preislisten von mehreren Lieferanten, lohnt sich der Aufbau, den wir für Händler im Betrieb haben:

  1. Konfiguration je Lieferant: Dateiformat, Feldzuordnung, Rabattlogik und Artikelnummern-Präfix stehen in einer Konfiguration, nicht im Code. Ein neuer Lieferant ist eine neue Konfiguration.
  2. Datei holen und Änderung erkennen: Ist die Preisliste seit dem letzten Lauf unverändert, endet der Lauf hier.
  3. Einlesen über Adapter: CSV, XLSX oder XML landen in einem einheitlichen Zwischenformat. Ab hier ist es egal, woher die Daten kommen.
  4. Anreichern: Einheit, Kategorie, Einkaufspreis mit Rabatten und Zuschlägen.
  5. Bestand einmal laden: alle Artikel und alle Bezugsquellen des Lieferanten, projiziert und paginiert, als Speicher mit dem Schlüssel Artikelnummer und Lieferant. Keine Einzelabfrage pro Zeile.
  6. Feldweise vergleichen und nur Änderungen schreiben, mit einem eigenen Modus „nur Preise“ für die regelmäßigen Läufe.
  7. Schreiben mit Rücksicht auf den Mandanten: weclapp hat keine festen Ratenlimits, verzögert aber bei Last und antwortet nach bis zu 30 Sekunden Wartezeit mit 429. Die Doku empfiehlt Wiederholung mit exponentiellem Backoff und Timeouts von mindestens einer Minute.
  8. Fehler je Zeile, nicht je Lauf: Scheitert ein Artikel an der Validierung, protokollierst du Zeile, Request und Fehlermeldung und machst mit dem nächsten weiter. Weil der Abgleich idempotent ist, setzt der nächste Lauf dort wieder auf.
  9. Bericht: neu, geändert, unverändert, fehlgeschlagen, je Lieferant, per Mail an Einkauf und Betreuer.

Fazit: Trenn Einlesen, Abgleich und Schreiben, dann wird aus dem Migrationsskript ein Importer, der jede Preisliste verträgt.

Go-Live-Checkliste

  1. Alle Requests laufen gegen /webapp/api/v2, kein Body enthält articleId oder currencyName.
  2. Einheiten und Währungen sind einmal gelesen, kein Artikel entsteht ohne ausdrückliche unitId.
  3. Jeder Lieferant aus dem Altsystem ist genau einer weclapp-ID zugeordnet, das Mapping ist gespeichert.
  4. Jeder Schreibzugriff läuft im Probelauf mit dryRun=true, die Fehlerliste ist leer.
  5. Jeder PUT trägt ignoreMissingProperties=true und die frisch gelesene version.
  6. Die primäre Bezugsquelle steht immer in derselben Liste, die du schickst.
  7. Ein zweiter Lauf mit denselben Daten schreibt nichts. Ein Lauf mit einer geänderten Preisliste ändert genau die betroffenen Quellen.
  8. Negativfälle sind geprüft: doppelte Artikelnummer liefert „entity is a duplicate“, veraltete Version liefert 409.
  9. Nach der Übernahme liefert primarySupplySourceId-null=true nur noch Artikel, die bewusst keinen Lieferanten haben.
  10. Stichproben in der Oberfläche: je Lieferant drei Artikel, Preise mit Rabatt und Staffel gegen das Altsystem geprüft.

Fazit: Die Checkliste ist abgehakt, wenn der zweite Lauf leer bleibt und die Stichproben stimmen.

Werkzeuge, die die Migration beschleunigen

Ein Testsystem

Entwickle nie am Produktivmandanten deines Kunden. weclapp bietet eigene Testsysteme an, pauschal pro System und Monat statt pro Nutzer:in. Dort fährst du Probeläufe so oft, wie du willst. Wenn du kein eigenes Testsystem willst, stellen wir dir eines samt Stammdaten bereit.

Grundschulung und Postman Collection

Wer neu auf der weclapp-API ist, startet mit unserem Webinar weclapp API Deep Dive auf YouTube: Authentifizierung, Filter, Projektion und referenzierte Entitäten. Viele Requests gibt es fertig in unserer Postman Collection 4 weclapp, mit Umgebungsvariablen für Testsystem und Mandant.

weclapp Toolbox

Die Chrome-Erweiterung weclapp Toolbox öffnet zu jedem Datensatz in der Oberfläche die API-Ansicht und kopiert IDs. So prüfst du nach dem Import schnell, was an einem Artikel wirklich verknüpft ist.

wals.pro AI 4 weclapp

Die KI-Plattform kennt Schema und API-Doku deines Mandanten und liest Daten zurück. Du kannst kostenlos starten, bis 31.12.2026 mit allen Funktionen. In einer Migration hilft sie in drei Phasen:

  • Planung: Dein Assistent findet Einheiten, Währungen und Lieferanten-IDs und zeigt dir, welche Artikel noch ohne primäre Bezugsquelle sind.
  • Entwicklung: Feldnamen, Filter, Pflichtfelder und Endpunkte beantwortet er aus Schema und Doku, statt dass du sie in der OpenAPI suchst.
  • Nacharbeit: Einzelne Bezugsquellen samt Verknüpfung am Artikel pflegt er direkt in weclapp, jeweils mit Vorschau und Freigabe.

Begleitung

Und wenn du die Migration nicht allein bauen willst: Wir übernehmen Mapping, Importer und Abnahme oder schulen dein Team auf genau diesen Ablauf.

Fazit: Testsystem, Postman Collection und ein Assistent mit Schemawissen verkürzen vor allem die Planung, in der die meisten Migrationen Zeit verlieren.

Quellen und Grenzen

  • weclapp API v2, Dokumentation und OpenAPI-Spezifikation des Mandanten unter /webapp/api/v2/meta/openapi.yaml: Abschnitte zu dryRun, Projektion, includeReferencedEntities, Teilupdates, Listen, Paginierung und Lastmanagement sowie die Schemata article, articleSupplySource, purchasePrice und reductionAddition. Abgerufen am 16.11.2026.
  • weclapp API Changelog v2: entfernte Felder an articleSupplySource und Umstellung auf articleSupplySourceId in Bestellpositionen. Abgerufen am 16.11.2026.
  • Eigener End-to-End-Test aller Requests dieses Artikels gegen ein weclapp-Testsystem am 16.11.2026, inklusive der Fehlerfälle. Die zitierten Fehlermeldungen stammen aus diesem Test.

Grenzen: Der Artikel behandelt Einkaufspreise und Bezugsquellen. Verkaufspreise, Lagerplätze, Stücklisten, Verpackungseinheiten und Streckengeschäft sind nicht Teil davon. Das Verhalten ohne unitId, die Versionserhöhung am Artikel nach Preisänderungen und die Antworten von v1 haben wir beobachtet, weclapp dokumentiert sie nicht ausdrücklich. Prüfe sie in deinem Testsystem, bevor du dich darauf verlässt.

Häufige Fragen

Kann ich beim Anlegen einer Bezugsquelle direkt den Artikel mitgeben?

Nein. In API v2 hat die Bezugsquelle kein Feld für den Artikel, articleId wird mit „property articleId is unknown“ abgelehnt. Du legst die Bezugsquelle an und verknüpfst sie danach per PUT am Artikel über supplySources und primarySupplySourceId.

Wie lege ich den Hauptlieferanten eines Artikels fest?

Über primarySupplySourceId am Artikel. Die ID muss in der Liste supplySources desselben Artikels stehen, sonst lehnt weclapp den PUT ab. Willst du nur den Hauptlieferanten wechseln, schickst du die Liste nicht mit.

Wie bilde ich Rabatte und Zuschläge auf den Einkaufspreis ab?

Je Preiszeile in reductionAdditions, mit Name, Typ und Wert. Rabatte sind REDUCTION_PERCENT oder REDUCTION_ABS, Zuschläge ADDITION_PERCENT oder ADDITIONAL_ABS. Mehrere Einträge je Preiszeile sind möglich, etwa Warengruppenrabatt und Teuerungszuschlag.

Wie verhindere ich Dubletten, wenn der Import mehrmals läuft?

Suche jeden Artikel über die Artikelnummer und jede Bezugsquelle über den Lieferanten unter den Quellen dieses Artikels. Schreibe nur bei Abweichung und vergleiche Preise als Zahlen. Zusätzlich meldet weclapp bei einer doppelten Artikelnummer schon im dryRun „entity is a duplicate“.

Warum sollte ich für Bezugsquellen nicht mehr API v1 verwenden?

Weil v1 Felder annimmt, die nichts bewirken. Im Test hat v1 eine Bezugsquelle mit articleId angelegt, die an keinem Artikel hing. v2 lehnt solche Felder mit einem Fehler ab, du merkst den Fehler also beim ersten Request.

Was passiert mit bestehenden Bezugsquellen, wenn ich die Liste am Artikel schicke?

Die geschickte Liste ersetzt die bestehende. Fehlt ein verknüpfter Lieferant im Body, ist er danach nicht mehr verknüpft. Fehlt die primäre Quelle, lehnt weclapp ab. Zum Ergänzen liest du die Liste, hängst den neuen Eintrag an und schickst alle Einträge zurück.