Posted by Markus Wals

Lagerplätze per weclapp-API anlegen und migrieren: Ablauf, Requests, Fallstricke

Lagerverwaltung Leitfaden Migration weclapp weclapp API

KI-generierte Illustration: Ein Lagerregal mit nummerierbaren Fächern und Barcodes, ein Stapel Listenkarten mit roter Banderole wird als Paket eingeschoben, ein Fach trägt einen roten Prüfhaken. Überschrift: Lagerplätze per weclapp-API

Kurz gesagt: Lagerplätze legst du in weclapp per API nicht über /storagePlace an, denn dieser Endpunkt kann nur lesen. Plätze entstehen über den Lagerort (PUT /storageLocation/id/{id}) oder das Regal (/shelf). Die Platzliste im Body ersetzt dabei nach unseren Tests den kompletten Bestand des Lagerorts, deshalb baust du jeden Batch aus einem frischen GET, prüfst ihn mit dryRun=true und liest danach jeden Platz zurück.

Dieser Artikel ist für alle, die bei einem Wechsel nach weclapp hunderte oder tausende Lagerplätze aus einem Altsystem übernehmen müssen: Entwickler:innen, Projektleitungen und Lagerverantwortliche. Er zeigt den Ablauf von der Bestandsaufnahme bis zur Kontrolle und alle Requests dazu.

Typischer Anlass ist der Wechsel von einem gewachsenen Warenwirtschaftssystem auf weclapp, bei dem mehrere tausend bestehende Lagerplätze übernommen werden sollen. Worauf es dabei an der API ankommt, steht hier. Wie du einen Fulfiller anbindest, zeigt unser Leitfaden zur Fulfiller-Anbindung an weclapp, wie du Artikel mit ihren Lieferanten und Einkaufspreisen übernimmst, der Leitfaden Artikel und Bezugsquellen per weclapp-API importieren.

Das Wichtigste in Kürze

  • Erst die Plätze zählen, dann importieren. Eine Bestandsaufnahme der Lagerplätze und die Bereinigung im Altsystem entscheiden mehr über das Ergebnis als jedes Skript.
  • /storagePlace kann nur lesen. Blocklagerplätze entstehen am Lagerort, Regalplätze am Regal, und dort ist jede Kombination aus Feld, Ebene und Fach ein eigener Eintrag, den du selbst baust.
  • Die Platzliste ersetzt alles, und auf die version ist kein Verlass. Fehlt ein bestehender Platz im Body, löscht weclapp ihn. Jeder Batch entsteht deshalb aus einem frischen GET, Änderungen erkennst du an den Platz-IDs.
  • Der Barcode ist das, was das Lager scannt. weclapp dokumentiert keine Eindeutigkeitsregel, das übernimmt dein Import, und Etikett und Scanner testest du vorab.
  • Erst dryRun, dann in Stufen schreiben. Probe ohne Schreiben, dann ein Platz, fünf Plätze, der Rest, und nach jeder Stufe eine Kontrolle.

Lager, Lagerort, Regal, Blocklagerplatz: die Begriffe

weclapp gliedert ein Lager in vier Ebenen. Wer die Begriffe sauber trennt, spart sich später die Hälfte der Diskussionen mit dem Lagerteam.

Ebene Bedeutung API
Lager Standort mit Adresse, etwa Hauptlager und Außenlager /warehouse
Lagerort abgegrenzter Bereich eines Lagers, etwa eine Regalzeile, eine Halle oder ein Schrank /storageLocation
Regal liegt in einem Lagerort, hat Ebenen (horizontal) und Felder (vertikal), weclapp erzeugt die Plätze /shelf, Liste storagePlaces
Blocklagerplatz liegt direkt im Lagerort, einzeln angelegt mit Name, Typ und optional Größe /storageLocation, Liste blockStoragePlaces

Jeder Platz hat außerdem einen Lagerplatztyp. Für eine Migration reicht fast immer UNIVERSAL: Darauf sind Wareneingang und kommissionierbarer Bestand möglich. Den Typ kannst du laut weclapp-Doku zu Lagerplatztypen nachträglich ändern, solange kein Bestand auf dem Platz liegt.

Fazit: Lager und Lagerorte bilden die Struktur, Regale und Blocklagerplätze die eigentlichen Plätze.

Vor dem Import: die Lagerplätze zählen

Der häufigste Fehler bei einer Lagerplatz-Migration ist, die Platzliste des Altsystems ungeprüft zu übernehmen. Dort stehen über die Jahre Schreibvarianten (08 D12 und 8 D12), Tippfehler, persönliche Ablagen wie „Chef“ und Artikel ganz ohne Platz. Ein Skript legt all das brav an, und das Lagerteam räumt danach in weclapp auf.

Deshalb kommt vor dem Import eine Bestandsaufnahme der Plätze. Gemeint ist keine Inventur der Mengen, sondern eine Liste, was es physisch gibt und wie groß es ist:

  • Muster erkennen: Aus der Altsystem-Liste lassen sich Gruppen ableiten, zum Beispiel „zwei Ziffern, Buchstabe, Zahl“ für Regalplätze, „Kürzel plus Nummer“ für Bereiche und ein Rest an Sonderfällen.
  • Regale vor Ort zählen: Felder und Ebenen inklusive der leeren, und auf welcher Seite die Zählung beginnt. Das ist wichtig bei Regalen, die Rücken an Rücken stehen. Die im Altsystem belegte Spanne ist die Untergrenze: Wer weniger zählt, hat sich verzählt.
  • An der Quelle korrigieren: Schreibvarianten vereinheitlichen, Sonderfälle einem echten Ort zuordnen, Artikeln ohne Platz einen geben. Danach einen frischen Export ziehen.

Je mehr im Altsystem bereinigt ist, desto weniger Sonderlagerplätze landen in weclapp. Erst wenn die Liste steht, entscheidest du, wie du sie abbildest.

Fazit: Erst zählen und an der Quelle bereinigen, dann über die Abbildung in weclapp entscheiden.

Regal mit Ebenen und Feldern oder Blocklagerplatz mit sprechendem Namen?

Für die Plätze gibt es zwei Wege. Beide nutzen dieselben Lager und Lagerorte, sie unterscheiden sich nur darin, wie der einzelne Platz entsteht.

Blocklagerplätze, Position im Namen Regale mit Ebenen und Feldern
Anlage einzeln, Name frei, z. B. 16B07 Regal mit Ebenen × Feldern, weclapp erzeugt die Plätze
Neuer Platz im Betrieb „+ Neu“, Namen eintippen am Regal Feld, Ebene oder Platz ergänzen
Etiketten bleiben gültig ja, wenn eine feste Namensform gilt nur, wenn der Pfad aus Regalkürzel, Ebene und Feld zu den Etiketten passt
Leere Fächer nur, wenn du sie bewusst anlegst automatisch
Sortierung und Laufweg über den Namen, braucht feste Stellenzahl über die Struktur
Lohnt sich, wenn … der Platz vor allem gefunden werden soll du Regal, Ebene oder Feld wirklich auswertest oder steuerst, etwa über Kommissionierwege oder Platzgrößen für Kommissionier- und Vorratsplätze

Unsere Empfehlung für Migrationen: Blocklagerplätze mit sprechendem Namen, solange in der Bestandsaufnahme kein konkreter Nutzen der Regalstruktur auftaucht. Die Bedienung bleibt einfach, die vorhandenen Etiketten bleiben gültig, und den größten Strukturgewinn bringt ohnehin die Gliederung in Lagerorte. Zähle die Regalgrößen trotzdem: Mit ihnen legst du auch leere Plätze an und kannst später auf Regale umsteigen.

Zwei Punkte musst du vor einer Regal-Variante auf dem Testsystem prüfen. Die weclapp-Doku zur Lagereinrichtung beschreibt nicht, in welche Richtung die Ebenen gezählt werden und nach welchem Schema die Plätze heißen, und sie beschreibt das Ergänzen von Feldern, Ebenen und Plätzen, aber kein Umbenennen.

Fazit: Nimm Regale nur, wenn du die Struktur wirklich nutzt, sonst Blocklagerplätze mit fester Namensform.

Die Mechanik: warum ein falscher PUT Plätze löscht

Drei Eigenheiten der API bestimmen den ganzen Ablauf.

1. /storagePlace ist nur zum Lesen da

Die OpenAPI-Beschreibung von weclapp kennt für /storagePlace nur GET: die Liste, die Anzahl und den einzelnen Platz. Es gibt kein POST und kein PUT. Blocklagerplätze schreibst du als Liste blockStoragePlaces am Lagerort, Regalplätze als Liste storagePlaces am Regal. Zum Lesen und Prüfen ist /storagePlace trotzdem wertvoll, weil es alle Plätze eines Lagers mit Lagerort und Regal liefert.

2. Die Platzliste hat Replace-Semantik

Ein PUT auf den Lagerort ersetzt die komplette Liste blockStoragePlaces. Ein Platz, der im Body fehlt, wird gelöscht. Daran ändert auch ignoreMissingProperties=true nichts, denn der Parameter schützt nur Felder, die du gar nicht mitschickst, nicht die Einträge einer Liste, die du mitschickst. Neue Plätze hängst du deshalb immer hinter alle bestehenden, unverändert aus dem letzten GET übernommen.

3. Die version verrät dir keine Platzänderung

Normalerweise schützt die version vor parallelen Änderungen. Bei den Plätzen eines Lagerorts zählt sie nicht verlässlich hoch. Ob jemand zwischendurch einen Platz angelegt oder gelöscht hat, erkennst du nur am Vergleich der Platz-IDs. Darum liest unser Skript den Lagerort direkt vor jedem PUT noch einmal und bricht ab, sobald sich Platz-IDs oder Version ändern. Die Version allein reicht als Prüfung nicht.

Fazit: Schreibe Plätze nur über Lagerort oder Regal, schicke immer die vollständige Liste und vergleiche IDs statt der Version.

Ablauf eines Lagerplatz-Imports in weclapp: frischer GET auf den Lagerort, Body aus allen bestehenden plus neuen Plätzen, Probe mit dryRun, zweiter GET mit ID-Vergleich, PUT und Readback je Platz, in den Stufen 1, 5 und Rest

Schritt 1: Lager und Lagerorte lesen

Lager und Ziel-Lagerort legst du einmal von Hand an. Die API kennt dafür zwar auch POST /storageLocation, aber bei wenigen Lagerorten ist die Oberfläche schneller. Für den Import brauchst du nur ihre IDs. Alle Beispiele nutzen zwei Variablen: BASE ist die API-Adresse deines Mandanten, TOKEN dein API-Token.

BASE='https://deinmandant.weclapp.com/webapp/api/v2'
curl -s "$BASE/warehouse?properties=id,name,shortIdentifier" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"
curl -s "$BASE/storageLocation?warehouseId-eq=__WAREHOUSE_ID__&properties=id,name,shortIdentifier,warehouseId" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"

Ein Lagerort je Bereich ist meist sinnvoller als ein einziger großer: Die Liste je PUT bleibt kleiner, und ein Fehler betrifft nur einen Bereich.

Fazit: Lager und Lagerorte legst du von Hand an, das Skript arbeitet nur mit ihren IDs.

Schritt 2: den Ist-Stand doppelt lesen

Bevor du planst, liest du den Ziel-Lagerort mit seinen Blocklagerplätzen:

curl -s "$BASE/storageLocation/id/__LOCATION_ID__?properties=id,version,name,warehouseId,blockStoragePlaces" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"

Dann liest du unabhängig davon alle Plätze des Lagers über /storagePlace, seitenweise mit pageSize=1000:

curl -s "$BASE/storagePlace?warehouseId-eq=__WAREHOUSE_ID__&properties=id,name,active,barcode,storagePlaceType,storageLocationId,shelfId&sort=id&page=1&pageSize=1000" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"

Die Plätze mit passender storageLocationId und ohne shelfId müssen genau die Blocklagerplätze aus dem ersten Request sein. Weichen die beiden Stände ab, planst du nicht. Der zweite Request hat noch einen Zweck: Er zeigt Namen, die es im Lager schon anderswo gibt, etwa auf einem Regal oder in einem anderen Lagerort.

Fazit: Zwei unabhängige Lesewege, und geplant wird nur, wenn sie übereinstimmen.

Schritt 3: den Plan bauen

Der Plan ordnet jeden Zielnamen einer von drei Aktionen zu:

  • anlegen: Den Namen gibt es im Lager noch nicht.
  • schon korrekt: Der Platz existiert in diesem Lagerort, ist aktiv, hat den richtigen Typ und den richtigen Barcode.
  • Konflikt: Der Name liegt anderswo im Lager, existiert mehrfach oder weicht ab, etwa in der Schreibweise, beim Typ oder beim Barcode.

Mit einem Konflikt läuft kein Import. Namen, die sich nur in Groß- und Kleinschreibung unterscheiden, lehnen wir schon in der Zielliste ab, weil sie im Lageralltag niemand auseinanderhält.

Den Plan speichern wir als Datei mit SHA-256-Prüfsumme und einem Bestätigungssatz, der Anzahl, Lager, Lagerort und Zielsystem nennt. Ausgeführt wird nur ein unveränderter Plan, und nur mit genau diesem Satz.

Fazit: Der Plan ist der Kontrollschritt, bei dem ein Mensch prüft, was angelegt wird, bevor irgendetwas geschrieben ist.

Schritt 4: Probe mit dryRun=true

Der PUT auf den Lagerort kennt den Parameter dryRun. weclapp prüft dann den kompletten Body und schreibt nichts. Der Body enthält alle bestehenden Plätze unverändert und dahinter die neuen:

curl -s -X PUT "$BASE/storageLocation/id/__LOCATION_ID__?ignoreMissingProperties=true&dryRun=true" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "AuthenticationToken: $TOKEN" \
  --data '{
    "id": "__LOCATION_ID__",
    "version": "__VERSION__",
    "blockStoragePlaces": [
      { "id": "__BESTEHENDE_PLATZ_ID__", "name": "16B06", "barcode": "16B06",
        "storagePlaceType": "UNIVERSAL", "active": true, "blockedForResupply": false },
      { "name": "16B07", "barcode": "16B07", "storagePlaceType": "UNIVERSAL",
        "active": true, "blockedForResupply": false, "customAttributes": [] }
    ]
  }'

Im echten Body übernimmst du die bestehenden Plätze vollständig so, wie der GET sie geliefert hat, nicht nur die hier gezeigten Felder. Prüfe nach der Probe per GET, dass sich die Platz-IDs nicht verändert haben. Wir schicken die Probe zuerst mit einem einzigen neuen Platz und erst dann mit allen. Würde eine weclapp-Installation dryRun an dieser Stelle ignorieren, entstünde so höchstens ein Platz statt aller. Das prüfen wir auf jedem neuen System erneut, auch bei weclapp auf eigenem Server.

Fazit: Die Probe deckt Fehler im Body auf, bevor ein Platz entsteht, und beweist nebenbei, dass dryRun auf diesem System wirkt.

Schritt 5: in Batches schreiben, jeder aus einem frischen GET

Geschrieben wird in Batches von höchstens 500 neuen Plätzen und in drei Stufen: erst ein Platz, dann fünf, dann der Rest. Nach jeder Stufe läuft die Kontrolle aus Schritt 6. Für jeden Batch gilt dieselbe Reihenfolge:

  1. Frischer GET auf den Lagerort. Alle Plätze aus dem Plan und aus den vorigen Batches müssen noch da sein.
  2. Body bauen: alle bestehenden Plätze unverändert, dahinter die neuen dieses Batches. Namen, die schon existieren, fallen heraus.
  3. Probe mit dryRun=true.
  4. Zweiter GET direkt vor dem Schreiben. Haben sich Platz-IDs oder Version geändert, arbeitet jemand parallel am Lagerort, und der Lauf bricht ab.
  5. PUT ohne dryRun, sonst identisch mit der Probe.
  6. Readback: Kein bestehender Platz darf fehlen oder verändert sein, und jeder neue Platz muss genau einmal mit Typ, Barcode und Status da sein.
curl -s -X PUT "$BASE/storageLocation/id/__LOCATION_ID__?ignoreMissingProperties=true" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "AuthenticationToken: $TOKEN" \
  --data @batch-001.json

batch-001.json enthält denselben Body wie die Probe in Schritt 4.

Auf ein 409 antwortest du mit Nachlesen statt blindem Wiederholen. Der erste PUT kann trotzdem gewirkt haben, deshalb filterst du vor dem zweiten Versuch die schon angelegten Namen heraus.

Bei einem Timeout ist der Zustand unbekannt: Warte, bis der Server fertig sein kann, und entscheide anhand des Readbacks. Fehlt nach einem PUT ein bestehender Platz, stoppt der Lauf sofort.

Ein abgebrochener Lauf ist so unkritisch: Derselbe Befehl legt beim nächsten Start nur an, was noch fehlt. Ein zweiter Lauf mit demselben Plan legt nichts an.

Fazit: Jeder Batch entsteht aus einem frischen GET, wird geprobt, gegen einen zweiten GET abgesichert und Platz für Platz zurückgelesen.

Schritt 6: jeden Platz kontrollieren

Die Kontrolle liest Lagerort und /storagePlace erneut und vergleicht jeden Platz mit dem Plan. Mögliche Ergebnisse sind „ok“, „fehlt“, „doppelt“, „weicht ab“, „nicht in storagePlace“ sowie für die Plätze, die vor dem Import da waren, „fehlt“ oder „verändert“. Plätze, die nicht im Plan stehen, meldet sie als „zusätzlich vorhanden“. Erfolgreich ist der Lauf erst, wenn nur „ok“ und „zusätzlich vorhanden“ übrig bleiben.

Fazit: Beweis ist der zurückgelesene Platz in weclapp, nicht der HTTP-Status des PUT.

Regallagerplätze per API: /shelf mit Ebenen, Feldern und Fächern

Entscheidest du dich für Regale, gilt dieselbe Mechanik wie am Lagerort, nur am Regal. Der große Unterschied zur Oberfläche: Dort legst du ein Regal laut weclapp-Doku zur Lagereinrichtung über ein Formular an, mit Abkürzung, Anzahl Ebenen, Anzahl Felder, Anzahl Lagerplätze je Fach und einem Intervall für die Nummerierung. Nach der Vorschau und „Übernehmen“ entsteht das Regal mit seinen Plätzen.

Die API rechnet nichts davon aus. POST /shelf erwartet die fertige Liste storagePlaces, und jede Kombination aus Feld, Ebene und Fach ist darin ein eigener Eintrag mit eigenem Namen. Ein Regal mit 4 Feldern und 3 Ebenen und einem Platz je Fach sind also 12 Einträge, die dein Skript baut.

Oberfläche (Regal-Formular) API (/shelf)
Plätze entstehen aus Anzahl Ebenen, Felder und Plätze je Fach jeder Platz als eigener Eintrag in storagePlaces
Platznamen entstehen aus dem Formular, die Abkürzung des Regals steht im Pfad; das Namensschema beschreibt die Doku nicht gibst du vor, Pflichtfeld name
Position ergibt sich aus dem Raster fieldNumber und levelNumber je Platz, beide optional
Barcode Feld „Barcode“ am Platz Feld barcode je Platz, gleich beim Anlegen
Erst prüfen Vorschau dryRun=true
Nachträglich ergänzen in der grafischen Übersicht Feld, Ebene oder Platz hinzufügen PUT mit allen bestehenden und den neuen Plätzen

Pflichtfelder laut OpenAPI. Am Regal sind das shortIdentifier (die Abkürzung), storageLocationId und storagePlaces. Je Platz verlangt die API name, storagePlaceType, active und blockedForResupply.

Optional sind fieldNumber, levelNumber, barcode, pickSequence und storagePlaceSizeId für eine Lagerplatzgröße (laut Doku nur bei den Typen Kommissionierung, Vorrat und Gesperrt).

Für ein Regal brauchst du Feld und Ebene trotzdem, denn erst sie geben dem Platz eine Position im Regal. Ein eigenes Feld für das Fach gibt es nicht: Hat eine Ebene mehrere Plätze je Feld, steckt das Fach nur in Name und Barcode.

curl -s -X POST "$BASE/shelf?dryRun=true" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "AuthenticationToken: $TOKEN" \
  --data '{
    "shortIdentifier": "B",
    "storageLocationId": "__LOCATION_ID__",
    "storagePlaces": [
      { "name": "B01101", "fieldNumber": 1, "levelNumber": 1, "barcode": "B01101",
        "storagePlaceType": "UNIVERSAL", "active": true, "blockedForResupply": false },
      { "name": "B02101", "fieldNumber": 2, "levelNumber": 1, "barcode": "B02101",
        "storagePlaceType": "UNIVERSAL", "active": true, "blockedForResupply": false },
      { "name": "B01201", "fieldNumber": 1, "levelNumber": 2, "barcode": "B01201",
        "storagePlaceType": "UNIVERSAL", "active": true, "blockedForResupply": false }
    ]
  }'

Das Beispiel ist gekürzt, im echten Body stehen alle Kombinationen, also eine Schleife über Ebenen, Felder und Fächer. Ob Ebene 1 unten oder oben liegt, legst du dabei selbst fest und prüfst es auf dem Testsystem. Die Probe mit dryRun=true prüft den ganzen Body, ohne das Regal anzulegen. Ohne den Parameter legt derselbe Request das Regal an.

Regal B mit 4 Feldern und 3 Ebenen: Jedes Fach ist ein eigener Eintrag in storagePlaces mit name, fieldNumber, levelNumber und barcode, etwa B04301 für Gang B, Feld 04, Ebene 3, Fach 01; darunter drei Namensschemata aus Projekten

Benennung: drei Schemata aus unseren Projekten

Weil die API keine Namen vergibt, legst du das Schema vorher fest. Drei Varianten stecken in unseren Importskripten aus Kundenprojekten:

Schema Beispiel Passt, wenn …
Ein Platz je Ebene, Name aus Regal und Ebene Name 15A3, Feld immer 1 die vorhandenen Etiketten nur die Ebene kennen und Unterplätze wegfallen sollen
Fachnummer als Name, Position im Barcode Name 1, Barcode B02301 (Gang, Feld zweistellig, Ebene, Fach zweistellig) das Lager nach Gang, Feld, Ebene und Fach scannt; der Name allein ist dann nicht eindeutig, der Barcode schon
Pfad als Barcode LO1/B/2/3/1 (Lagerort, Regal, Feld, Ebene, Name) du fehlende Barcodes in einem gewachsenen Bestand nachträglich setzt

Schreibvarianten fängst du vor dem Plan ab: Unser Regal-Skript behandelt 15 A1, 15A1 und 15 A 1 als denselben Platz und begrenzt die Ebenen je Regal, damit ein Tippfehler wie 15 A71 nicht 71 Ebenen erzeugt. Feste Stellenzahlen halten Sortierung und Etiketten eindeutig.

Ein bestehendes Regal ändern

Ein bestehendes Regal änderst du mit PUT /shelf/id/{id}?ignoreMissingProperties=true. Auch storagePlaces hat Replace-Semantik: Der Body muss jeden bestehenden Platz enthalten, sonst ist er weg. Deshalb liest du das Regal direkt vorher frisch:

curl -s "$BASE/shelf/id/__SHELF_ID__" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"
curl -s -X PUT "$BASE/shelf/id/__SHELF_ID__?ignoreMissingProperties=true&dryRun=true" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "AuthenticationToken: $TOKEN" \
  --data '{
    "id": "__SHELF_ID__",
    "version": "__VERSION__",
    "storagePlaces": [
      { "id": "__BESTEHENDE_PLATZ_ID__", "name": "B01101", "fieldNumber": 1, "levelNumber": 1,
        "barcode": "B01101", "storagePlaceType": "UNIVERSAL", "active": true, "blockedForResupply": false },
      { "name": "B01401", "fieldNumber": 1, "levelNumber": 4, "barcode": "B01401",
        "storagePlaceType": "UNIVERSAL", "active": true, "blockedForResupply": false }
    ]
  }'

Das Beispiel ist gekürzt: Wie beim Lagerort übernimmst du alle bestehenden Plätze vollständig aus dem GET und hängst die neuen hinten an.

Auch am Regal zählt die version bei Platzänderungen nicht zuverlässig hoch. Das Regal-Skript vergleicht deshalb vor jedem PUT einen Fingerabdruck aus ID, Version, Ebene, Feld, Name und Status jedes Platzes und bricht bei jeder Abweichung ab. Entfernt es überzählige Plätze, prüft es vorher Bestand, Standardplätze und laufende Inventur, wie im Abschnitt zu geschützten Plätzen beschrieben.

Ein Regal löschen

Regale hängen am Lagerort nur als Verweis. Ein PUT auf den Lagerort mit leerer Liste shelves löscht deshalb nichts, in unserer Probe mit dryRun blieben die Regale stehen. Ein Regal entfernst du in zwei Schritten: erst die Plätze per PUT /shelf/id/{id} mit "storagePlaces": [] leeren, dann das leere Regal löschen.

curl -s -X DELETE "$BASE/shelf/id/__SHELF_ID__" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"

Unser Löschskript setzt voraus, dass auf den Plätzen kein Bestand liegt und kein Artikel sie als Standardplatz führt; einen blockierten Löschversuch beantwortet weclapp mit dem Grund. Laut weclapp-Doku zum Löschen von Lagerplätzen lassen sich Plätze mit bisherigen Lagerbewegungen ohnehin nur deaktivieren. Die API kennt dafür POST /shelf/id/{id}/deactivate. Probiere das Löschen erst mit einem einzigen Regal.

Fazit: Per API baust du jedes Fach selbst, mit Name, Feld, Ebene und Barcode, und schickst beim Ändern immer alle bestehenden Plätze mit.

Lagerplatz-Barcodes: was das Lager wirklich scannt

Im Lageralltag ist der Barcode wichtiger als der Name. In der mobilen Lager-App scannt das Team laut weclapp-Doku zur mobilen Lager-App Lagerort bzw. Lagerplatz per Barcode oder QR-Code, etwa im Wareneingang. Bei der Kommissionierung scannst du zuerst den Platz und dann den Artikel, bei der Inventur ebenfalls zuerst den Platz. Die Doku empfiehlt, das Etikett direkt am Platz anzubringen.

Das Feld barcode

Jeder Platz hat neben dem Namen ein eigenes Feld barcode, an Regalplätzen genauso wie an Blocklagerplätzen. Laut OpenAPI ist es optional und nimmt bis zu 4.000 Zeichen, die Doku spricht von einem frei wählbaren alphanumerischen Code. Du setzt es über dieselben Listen wie den Platz selbst, also storagePlaces am Regal oder blockStoragePlaces am Lagerort, gleich beim Anlegen oder später. Auch beim späteren Setzen gilt die Replace-Regel: Du schickst alle Plätze aus dem frischen GET und änderst nur den Barcode des einen Platzes.

Schemata und alte Etiketten

Bei einer Migration setzen wir den Barcode standardmäßig gleich dem Namen. So scannt das Lagerteam die vorhandenen Etiketten weiter, ohne neu zu drucken. Prüfe dafür mit ein paar Scans, was die alten Etiketten wirklich codieren, denn der Klartext darunter muss nicht dasselbe sein.

Codieren sie etwas anderes als den Namen, führst du den Barcode als eigene Spalte in der Zielliste. Bei Regalen mit mehreren Fächern je Ebene trägt der Barcode die Position, etwa B02301 für Gang B, Feld 02, Ebene 3, Fach 01.

Für die Namensform gilt: Leerzeichen am Rand und doppelte Leerzeichen bereinigen wir, mehr nicht. „08 D12“ und „8 D12“ bleiben zwei Plätze, bis sie im Altsystem vereinheitlicht sind. Umlaute, ß, Schrägstrich, Punkt, kaufmännisches Und und Namen mit über 200 Zeichen liefen in unserem Testlauf vom 09.11.2026 ohne Probleme durch.

Ob dein Scanner Groß- und Kleinschreibung, führende Nullen und Sonderzeichen sauber überträgt, testest du mit einem echten Etikett auf dem Testsystem. weclapp unterstützt laut Doku zur Scanner-Konfiguration Scanner mit Tastaturemulation, keine Anbindung über Middleware.

Eindeutigkeit prüfst du selbst

Die API-Beschreibung kennt für barcode keine Eindeutigkeitsregel, und in unserem Testlauf liefen gleiche Namen und Barcodes in einem zweiten Lager ohne Fehler durch. Ob innerhalb eines Lagers ein doppelter Barcode abgelehnt wird, ist nicht dokumentiert.

Verlass dich deshalb nicht darauf. Unsere Skripte prüfen die Zielliste auf doppelte Barcodes, überspringen Barcodes, die es im Lager schon gibt, und melden nach dem Import Dubletten im Readback. Dubletten in einem bestehenden Lager findest du so:

curl -s "$BASE/storagePlace?warehouseId-eq=__WAREHOUSE_ID__&properties=id,name,barcode&page=1&pageSize=1000" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN" \
  | jq -r '.result[].barcode // empty' | sort | uniq -d

Bei mehr als 1.000 Plätzen liest du alle Seiten, bevor du zählst.

Vom Barcode-Feld bis zum Scan: Barcode am Platz setzen, Eindeutigkeit je Lager selbst prüfen, Etikett in der Etikettenkonfiguration im Tab Lagerplatz gestalten, Platz in der mobilen Lager-App bei Wareneingang, Kommissionierung und Inventur scannen

Etiketten in weclapp gestalten

Den Inhalt der Lagerplatzetiketten legst du unter Globale Einstellungen > Formularwesen > Etikettenkonfiguration im Tab „Lagerplatz“ fest. Laut weclapp-Doku zu Etiketten stehen dort die Platzhalter ..storagePlaceName.. für den Platznamen, ..warehouseName.. für den Lagernamen und @@storagePlaceBarcode@@ für den Barcode zur Verfügung. Wo du den Druck für viele Plätze auslöst und welchen Barcode-Typ das Etikett nutzt, beschreibt die Doku-Seite nicht. Prüfe das mit einem Probeetikett, bevor du ein ganzes Lager beschriftest.

Fazit: Der Barcode ist der Schlüssel für jeden Scan im Lager, darum legst du sein Schema vor dem Import fest, prüfst die Eindeutigkeit selbst und testest Etikett und Scanner vorab.

Bevorzugte Lagerplätze am Artikel und geschützte Plätze

Am Artikel hinterlegst du die Lagerplätze, auf denen er standardmäßig liegt. In der API ist das die Liste defaultStoragePlaces mit Platz-IDs. Sie ist der Grund, warum der Platzimport zuerst kommt: Erst wenn die Plätze existieren, gibt es die IDs, die du am Artikel einträgst. Die Zuordnung ist deshalb ein eigener, zweiter Schritt, ebenso der Anfangsbestand.

curl -s "$BASE/article?properties=id,articleNumber,defaultStoragePlaces&sort=id&page=1&pageSize=1000" \
  --header 'Accept: application/json' \
  --header "AuthenticationToken: $TOKEN"
curl -s -X PUT "$BASE/article/id/__ARTICLE_ID__?ignoreMissingProperties=true&dryRun=true" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header "AuthenticationToken: $TOKEN" \
  --data '{ "id": "__ARTICLE_ID__", "version": "__VERSION__",
            "defaultStoragePlaces": [ { "id": "__PLATZ_ID__" } ] }'

Auch diese Liste schickst du immer vollständig, sonst verliert der Artikel Plätze, die schon eingetragen waren. defaultStoragePlaces ist nicht filterbar. Wer wissen will, welche Plätze irgendein Artikel als Standard nutzt, liest alle Artikel.

Das ist vor allem wichtig, sobald du Plätze nicht nur anlegst, sondern auch umbenennst oder entfernst. Ein Platz ist dann tabu, wenn mindestens eines davon zutrifft:

  • Auf ihm liegt Bestand (GET /warehouseStock?quantity-ne=0&properties=storagePlaceId).
  • Er ist Standardplatz eines Artikels (defaultStoragePlaces).
  • Er ist Standardplatz des Lagers für Wareneingang, Retoure, Produktion oder Konsolidierung.
  • Er steckt in einer laufenden Inventur (currentInventoryId am Platz).

Unser Importskript umgeht das Problem: Es legt nur an und verändert oder entfernt nie einen bestehenden Platz.

Fazit: Erst Plätze, dann Standardplätze am Artikel und Anfangsbestand, und nie einen Platz mit Bestand, Standardrolle oder laufender Inventur entfernen.

Wie schnell das ist und wie du zurückbaust

Auf unserem Testmandanten haben wir den Ablauf am 09.11.2026 mit 5.600 erfundenen Plätzen durchgespielt:

Prüfung Ergebnis
Probe mit dryRun über alle 5.600 Plätze bestanden, nichts geschrieben, 2,6 Sekunden
Anlage in Stufen: 1, 5, dann 5.594 Plätze alle zurückgelesen, der Rest in knapp 2 Minuten
Kontrolle je Platz 5.600 von 5.600 ok
Zweiter Lauf mit demselben Plan 0 angelegt, 5.600 schon korrekt
Gleiche Namen und Barcodes in einem zweiten Lager 20 von 20 ok
Rückbau durch Leeren des Lagerorts 5.600 Plätze in knapp 2,5 Minuten entfernt

Das Skript hat bewusst keinen eigenen Rückbau. Auf einem Testsystem stellt eine Sicherung den alten Stand wieder her. Für das Produktivsystem legst du den Rückweg vor der Freigabe fest. Nicht geprüft haben wir das Löschen eines Platzes, auf dem schon Bestand liegt.

Fazit: Tausende Plätze sind in Minuten angelegt, die Zeit steckt in Bestandsaufnahme, Plan und Kontrolle.

Checkliste für den Import

  1. Bestandsaufnahme der Plätze abgeschlossen, Korrekturen im Altsystem eingepflegt, frischer Export gezogen.
  2. Entscheidung Regal oder Blocklagerplatz getroffen, feste Namensform je Lagerort-Art festgelegt, bei Regalen Feld, Ebene und Fach je Platz in der Zielliste.
  3. Barcode-Schema festgelegt, alte Etiketten probegescannt, Barcodes je Lager eindeutig, Probeetikett mit dem eigenen Scanner getestet.
  4. Lager und Lagerorte in weclapp von Hand angelegt, IDs notiert.
  5. Sicherung des Zielsystems gezogen, Schreibfenster ohne Nutzer:innen vereinbart, Automatisierungen auf Lagerplätzen pausiert.
  6. Plan ohne Konflikte, von einem Menschen geprüft.
  7. Probe mit dryRun bestanden, Platz-IDs danach unverändert.
  8. Stufen 1, 5, Rest, nach jeder Stufe Kontrolle nur mit „ok“ und „zusätzlich vorhanden“.
  9. Danach als eigene Schritte: Standardplätze am Artikel, Anfangsbestand.

Fazit: Erst Testsystem mit Sicherung, Probe und Stufen, das Produktivsystem nach Freigabe und mit festgelegtem Rückweg.

Werkzeuge, die dir dabei helfen

Ein eigenes weclapp-Testsystem ist für eine Migration Pflicht: Dort laufen Probe, Stufen und Rückbau, bevor das Produktivsystem den ersten Platz sieht. Die Chrome-Erweiterung weclapp Toolbox zeigt zu jedem Datensatz die API-Ansicht und kopiert IDs, etwa die des Lagerorts. Wer neu auf der weclapp-API ist, startet mit unserem Webinar zur weclapp-API und unserer Postman Collection für die weclapp-API.

Mit wals.pro AI 4 weclapp findet dein KI-Assistent die IDs von Lagern, Lagerorten und Plätzen und beantwortet Feldfragen aus dem Schema deines Mandanten. Jede Schreibaktion läuft dabei über Vorschau und Freigabe.

Und wenn du die Migration nicht allein stemmen willst: Wir übernehmen Bestandsaufnahme, Plan und Import mit dir zusammen.

Fazit: Testsystem, weclapp Toolbox und ein Assistent, der die IDs kennt, verkürzen jede Lagerplatz-Migration.

Quellen und Grenzen

Replace-Semantik, das Verhalten der version und die Laufzeiten stammen aus unseren Testläufen auf einem weclapp-Testmandanten (09.11.2026). Live gefahren haben wir dabei den Skriptlauf; die einzelnen Beispiel-Requests in diesem Artikel sind aus der OpenAPI-Beschreibung und dem Skript abgeleitet. Die IDs in den Beispielen sind Platzhalter. Prüfe das Verhalten auf deinem eigenen Testsystem, besonders bei weclapp auf eigenem Server.

Regal anlegen, ändern und löschen sowie die Barcode-Schemata stammen aus Importskripten unserer Kundenprojekte. Das Löschen eines Regals mit Bestand auf den Plätzen haben wir nicht geprüft. Den Etikettendruck für viele Plätze und den Barcode-Typ des Etiketts beschreibt die weclapp-Doku nicht, wir haben ihn nicht geprüft. Anfangsbestände und das Löschen von Plätzen mit Bestand deckt dieser Artikel nicht ab.

Häufige Fragen

Kann ich Lagerplätze in weclapp per API mit POST /storagePlace anlegen?

Nein. /storagePlace kann nur lesen. Blocklagerplätze legst du über PUT /storageLocation/id/{id} mit der Liste blockStoragePlaces an, Regalplätze über POST /shelf mit der Liste storagePlaces, in der jede Kombination aus Feld, Ebene und Fach ein eigener Eintrag ist.

Warum hat mein PUT auf den Lagerort Lagerplätze gelöscht?

Die Liste blockStoragePlaces ersetzt den kompletten Bestand des Lagerorts. Jeder Platz, der im Body fehlt, wird gelöscht, auch mit ignoreMissingProperties=true. Baue den Body deshalb immer aus einem frischen GET und hänge neue Plätze hinten an.

Soll ich Regale mit Ebenen und Feldern oder Blocklagerplätze anlegen?

Regale lohnen sich, wenn du Regal, Ebene oder Feld wirklich auswertest, etwa über Kommissionierwege oder Platzgrößen für Kommissionier- und Vorratsplätze. Sonst sind Blocklagerplätze mit sprechendem Namen einfacher zu bedienen und halten die vorhandenen Etiketten gültig.

Wie teste ich einen Lagerplatz-Import, ohne etwas zu schreiben?

Schicke den PUT mit dryRun=true. weclapp prüft dann den ganzen Body und schreibt nichts. Prüfe danach per GET, dass die Platz-IDs unverändert sind, und fange mit einem einzelnen neuen Platz an.

Wann trage ich die bevorzugten Lagerplätze am Artikel ein?

Nach dem Platzimport, als eigenen Schritt. Erst dann gibt es die Platz-IDs, die du in defaultStoragePlaces am Artikel einträgst, und auch diese Liste schickst du immer vollständig.

Muss der Lagerplatz-Barcode in weclapp eindeutig sein?

Die API-Beschreibung nennt keine Eindeutigkeitsregel, und in unserem Testlauf liefen gleiche Barcodes in einem zweiten Lager ohne Fehler durch. Für sauberes Scannen sollte jeder Barcode je Lager genau einmal vorkommen, deshalb prüfst du Zielliste und Bestand vor dem Import selbst auf Dubletten.