WMS‑Integration: REST, Webhooks und WebSockets für eine Live‑Lagerkarte

Wer nach „WMS‑Integration“ sucht, landet in einer Protokolldebatte. Für eine Live‑Lagerkarte ist die nützliche Frage enger: Wie gibt Ihr WMS Daten heraus, und wie aktuell muss die Karte sein? Das WMS stellt vielleicht REST‑Endpunkte bereit, feuert Webhooks, publiziert in eine Queue oder streamt über einen Socket. Spatial Map nimmt drei Arten von Eingaben an: Es fragt REST‑Endpunkte ab, importiert Dateien und empfängt Pushes als Schreibzugriffe auf die API einer Tabelle. Brauchen Sie also Webhooks oder WebSockets? Ihr WMS sendet sie womöglich; Spatial Map empfängt sie als Schreibzugriffe auf die Tabellen‑API, abgeschickt von einem Relay, das Ihnen gehört.

Unter Integrations → Add integration stehen drei Optionen: REST API, Upload file und Table. Eine Tabelle bringt dann einen vierten Weg mit — ihre eigene Schreib‑API — sowie einen optionalen serverseitigen Poller. Der Hauptunterschied: wo sie laufen.

Einen herstellerspezifischen Connector brauchen Sie nicht — Spatial Map hat keinen. Entscheidend ist, welche Art Schnittstelle Ihr WMS bietet. Prüfen Sie die Integrationsdoku Ihrer Version; die folgenden Muster gelten für die meisten Produkte.

Ein Relay ist jedes kleine Programm zwischen WMS und Spatial Map: eine Serverless‑Funktion hinter dem WMS‑Webhook, ein Consumer an der Message Queue oder ein Prozess, der den RTLS‑Socket offen hält. Seine Aufgabe ist immer dieselbe — jedes Ereignis in eine Tabellenzeile übersetzen und Zeilen gebündelt senden.

1. 1
   Tabelle anlegen

   Unter Tables je Art von Objekt eine Tabelle anlegen (Lagerplätze, Pick‑Ereignisse, Mitarbeitende) und die Art wählen — Marker / POI, Asset (mobile), Shipment, Polygon / area usw. Jedes Feld hat einen API key wie `bin_code` oder `status`: Das sind die Payload‑Schlüssel, die das Relay sendet. Siehe Tables.

2. 2
   Key erstellen

   Im Tab API & access der Tabelle erstellt ein Owner oder Admin einen Key. Er beginnt mit `sgv_tbl_` und wird nur einmal angezeigt. Ein Key schreibt in genau eine Tabelle, daher steht keine Tabellen‑ID in der URL. Geben Sie jedem System einen eigenen Key, damit Sie einen widerrufen können, ohne die anderen zu stören, und kopieren Sie die exakte Basis‑URL aus demselben Tab.

3. 3
   Jedes Ereignis auf eine Zeile abbilden

   Wählen Sie einen stabilen `entityKey` — Lagerplatzcode, Ereignis‑ID, Badge‑ID. Zeilen werden über diesen Schlüssel per Upsert geschrieben; eine doppelte Zustellung überschreibt also, statt zu duplizieren.

4. 4
   Batches statt Einzelereignisse

   Ein paar Sekunden puffern, dann ein `POST /rows/bulk` (vollständige Zeilen) oder `PATCH /rows/bulk` (nur geänderte Felder) mit bis zu 1.000 Zeilen senden. Gültige Zeilen werden übernommen, auch wenn andere scheitern; abgelehnte kommen in `errors[]` zurück.

5. 5
   Die richtigen Fehler wiederholen

   `429` heißt, der Key hat 60 Anfragen pro Minute überschritten; `401`, der Key ist falsch oder widerrufen; `400`, eine Zeile verletzt das Tabellenschema (Pflicht‑ oder Unique‑Feld). Nicht gesendete Zeilen behalten und im nächsten Takt erneut senden.

curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"entityKey":"EV-20261011-0412","payload":{"event_id":"EV-20261011-0412","event_type":"pick","item_id":"B-B86-L2-01","from_bin_code":"B-B86-L2","quantity":2,"worker_id":"W-04","ts":"2026-10-11T09:14:05Z"}}'

curl -X POST https://app.spatialmap.io/api/v1/public/tables/rows/bulk \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rows":[
        {"entityKey":"EV-20261011-0413","payload":{"event_id":"EV-20261011-0413","event_type":"pick","item_id":"A-B07-L1-02","from_bin_code":"A-B07-L1","quantity":1,"worker_id":"W-02","ts":"2026-10-11T09:14:09Z"}},
        {"entityKey":"EV-20261011-0414","payload":{"event_id":"EV-20261011-0414","event_type":"move","item_id":"B-B99-L1-03","from_bin_code":"B-B99-L1","to_bin_code":"B-B51-L1","quantity":1,"worker_id":"W-05","ts":"2026-10-11T09:14:11Z"}}
      ]}'

curl -X PATCH https://app.spatialmap.io/api/v1/public/tables/rows/A-B01-L1 \
  -H "Authorization: Bearer $SPATIALMAP_TABLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"blocked","hold_reason":"Damaged pallet"}'

// relay.mjs (Node 18+) - receives bin-status webhooks from your WMS and
// forwards them in batches to the "Rack Inventory" table. A sketch, not a product.
import http from 'node:http';

const BASE = 'https://app.spatialmap.io/api/v1/public/tables'; // copy yours from API & access
const KEY = process.env.SPATIALMAP_TABLE_KEY;                  // sgv_tbl_... (this table's key)
const pending = new Map();                                     // bin_code -> latest changes

http.createServer((req, res) => {
  let body = '';
  req.on('data', (chunk) => (body += chunk));
  req.on('end', () => {
    try {
      // 1. Verify your WMS's webhook signature here (its docs say how).
      const e = JSON.parse(body);
      // 2. Map the WMS event onto your table's field keys.
      const prev = pending.get(e.bin_code)?.patch ?? {};
      pending.set(e.bin_code, {
        entityKey: e.bin_code,
        patch: { ...prev, status: e.status, sku: e.sku, quantity: e.quantity },
      });
      res.writeHead(202).end();
    } catch {
      res.writeHead(400).end();
    }
  });
}).listen(8080);

// 3. Flush every 5 s: one request instead of one per event (60 requests/min per key).
setInterval(async () => {
  const rows = [...pending.values()].slice(0, 1000);
  if (rows.length === 0) return;
  rows.forEach((r) => pending.delete(r.entityKey));
  try {
    const res = await fetch(BASE + '/rows/bulk', {
      method: 'PATCH', // merge changed fields onto existing bins
      headers: { Authorization: 'Bearer ' + KEY, 'Content-Type': 'application/json' },
      body: JSON.stringify({ rows }),
    });
    if (!res.ok) throw new Error('HTTP ' + res.status); // 401 key, 429 rate limit, 5xx
    const { errors } = await res.json();                 // rows the table rejected
    if (errors?.length) console.warn(errors);
  } catch (err) {
    // put the batch back without losing newer events; retry on the next tick
    rows.forEach((r) => {
      const newer = pending.get(r.entityKey);
      pending.set(r.entityKey, newer ? { ...newer, patch: { ...r.patch, ...newer.patch } } : r);
    });
    console.error(err);
  }
}, 5000);

Das Demo‑Lager Acme Warehouse hat 17 Regale mit 314 Lagerplätzen und Tabellen wie Rack Inventory (eine Zeile je Platz, Schlüssel `bin_code` wie `A-B01-L1`, Felder `status`, `sku` und `quantity`), Inventory Items, Pick Events und Warehouse Workers. Ein typischer WMS‑Feed nutzt dafür drei der vier Wege.

1. 1
   Platzstatus per Polling

   Hat das WMS einen Endpunkt für den Bestand je Lagerplatz, öffnen Sie Rack Inventory → API & access → Pull from a REST API: die URL, ein Intervall ab 30 s, Row key field in the response = `bin_code`, Where the items are (JSON path), falls die Liste in einem Envelope steckt, Header für die Authentifizierung und ein Feld‑Mapping. Start polling klicken; der erste Lauf kommt innerhalb einer Minute. Komplettes Rezept: einen REST‑Endpunkt nach Zeitplan abfragen.

2. 2
   Ereignisse per Push

   Die WMS‑Webhooks für bestätigte Picks und Platzstatus auf Ihr Relay zeigen lassen. Bestätigte Picks werden neue Zeilen in Pick Events (`POST /rows/bulk`); Statuswechsel patchen den passenden Platz in Rack Inventory (`PATCH /rows/bulk`). Schritt für Schritt: Zeilen mit der Tabellen‑Schreib‑API senden.

3. 3
   Snapshots per Upload

   Der nächtliche Inventurexport kommt über Upload file herein, und Re-import auf der Quellkarte aktualisiert ihn — ganz ohne Code.

4. 4
   Auf die Karte bringen

   Im Editor Data → Manage data links → New link öffnen. Ein Color a shape‑Link färbt jeden Platz per Style‑Regeln nach `status`; ein Live location marker‑Link setzt Mitarbeitende auf ihre Breiten‑ und Längengrade. Siehe Überblick über Data Links.

5. 5
   Prüfen, ob Daten fließen

   Der Tab Health unter Integrations listet jede Tabelle mit dem Zeitpunkt, an dem Ihre Systeme zuletzt geschrieben haben. Jeder API‑Schreibzugriff landet außerdem in der History der Zeile, die ein Historical movement‑Link auf der Karte abspielen kann.

Create new table: festlegen, was jeder Datensatz beschreibt

• Tables — Schema, Datensätze und der Tab API & access.
• Integrations — REST‑API‑Integrationen, Datei‑Uploads und Health.
• Zeilen mit der Tabellen‑Schreib‑API senden — durchgespieltes Beispiel mit Keys und curl.
• Einen REST‑Endpunkt nach Zeitplan abfragen — serverseitiges Polling von A bis Z.
• Überblick über Data Links — wie aus Zeilen Marker, Einfärbungen und Badges werden.
• Spatial Map für Lager und digitaler Lagerzwilling vs. WMS.