Beispiele

Sechs wiederkehrende Integrationsmuster. Jedes benennt die verwendete Methode, die Aufrufe der Reihe nach und den häufigsten Fehler.

1. Ein Versandmodul

Kontext. Ein Versanddienstleister mit einer API. Die Integration braucht seine Etiketten, seine Grenzen und seinen Tagesabschluss, wobei Stockly keinen dienstleisterspezifischen Code enthält.

Integrationsmethode. Erweiterungspunkte, im Prozess.

Umsetzungsschritte.

Implementieren Sie CarrierProfileInterface und taggen Sie den Service. Der Dienstleister erscheint dann in der Dienstleisterauswahl jeder Verpackungsregel, mit eigenen Grenzen und eigenen Prüfungen.
Hören Sie auf p2lab.stockly.parcels.commit, oder lassen Sie die Regel des Händlers eine Buchung auslösen, und rufen Sie Ihren Anbieter einmal je Paket auf.
Melden Sie jede Sendungsnummer mit p2lab.stockly.parcel.tracking zurück. Stockly schreibt sie in die Lieferung der Bestellung, und dort liest die Versandbestätigungs-Mail sie aus.
Hat Ihr Anbieter einen Tagesabschluss, implementieren Sie CarrierManifestGatewayInterface und geben Sie maxParcelsPerCall() an. Stockly zerteilt die Übergabe für Sie auf diese Zahl.

Typischer Fehler. Zweimal buchen. Ein Paket, das bereits eine Sendungsnummer trägt, darf nie erneut angefordert werden: Die Sendung besteht, und der Händler hat sie bezahlt. Stockly sichert das mit isRequestable() ab, das vor dem Hinausrufen zu lesen ist; eine Wiederholungsschleife, die es übergeht, erzeugt zwei Etiketten für eine Sendung.

Ein zweiter typischer Fehler. Grenzen anzugeben, die Ihr Vertrag nicht hat. Grenzen sind so oft vertraglich wie technisch: Derselbe Dienstleister sind 31,5 kg für den einen Händler und 20 kg für einen anderen, dessen Belegschaft nicht mehr heben darf. Liefern Sie die Voreinstellungen des Dienstleisters und lassen Sie die Regel des Händlers sie überschreiben.

2. Ein Desktop-Etikettenwerkzeug

Kontext. Der Händler betreibt bereits ein kleines Programm, das mit dem Dienstleister spricht und den Etikettendrucker bedient. Das Programm behält seine Rolle, und Stockly wird über das Ergebnis unterrichtet.

Integrationsmethode. HTTP, abfragend.

Umsetzungsschritte.

Fragen Sie /api/search/p2lab-stockly-parcel nach Paketen ohne Sendungsnummer ab:

{ "filter": [
    { "type": "equals", "field": "trackingCode", "value": null },
    { "type": "equalsAny", "field": "status", "value": ["planned", "packed"] }
  ],
  "associations": { "order": {}, "lines": {} } }

Buchen Sie das Etikett im externen Programm.
Melden Sie es: POST shipping/parcels/{parcelId}/tracking.
Lesen Sie am Ende des Tages GET shipping/batches/eligible und POST shipping/batches/close. Der Abschluss liefert eine jobId zurück, kein Ergebnis: Er läuft im Hintergrund, und das PDF, das der Fahrer unterschreibt, liegt unter shipping/batches/{batchId}/list.

Typischer Fehler. batches/close als synchron zu behandeln. Die Übergabe eines Tages sind Tausende Schreibvorgänge und eine Dienstleister-API, die dreißig Sendungen auf einmal nimmt; der Endpunkt gibt sofort eine Job-Id zurück, und das Werkzeug muss das Ergebnis abfragen.

Betriebshinweis. Filtern Sie auch nach Platz, wenn der Händler mehr als einen Packplatz betreibt; sonst unterschreibt der Tagesabschluss des Werkzeugs für Pakete, die noch an einem anderen Platz stehen. Das Feld ist floorElementId am Paket, und shipping/batches/close nimmt es als Geltungsbereich entgegen.

3. Ein ERP, dem die Gewichte gehören

Kontext. Die Artikelstammdaten leben im ERP und sind besser als das, was in Shopware steht.

Integrationsmethode. DAL, nach Zeitplan.

Umsetzungsschritte.

Schieben Sie Gewichte und Maße in das Shopware-Produkt selbst: weight, length, width, height. Stockly liest die nativen Felder; es hält keine zweite Kopie.
Schieben Sie den Verpackungsaufschlag in p2lab_stockly_product_packaging, mit productId als Schlüssel.
Arbeitet das ERP in Packklassen statt je Artikel, legen Sie je Klasse ein p2lab_stockly_packaging_profile an und lassen Sie den Eigenschaftsabgleich die Arbeit tun: dreihundert Artikel von einer Zeile abgedeckt, die nie wieder synchronisiert werden muss.
Lesen Sie nach einer Synchronisierung GET packaging/coverage und protokollieren Sie summary.missingDimensions. Es ist der denkbar billigste Regressionstest für Ihren eigenen Export.

Typischer Fehler. Nullen schreiben. Ein ERP, das für ein unbekanntes Verpackungsgewicht „0.000” exportiert, besagt gegenüber Stockly, dass der Artikel unverpackt versandt wird, und keine Regel darunter berichtigt das. Lassen Sie das Feld weg oder senden Sie null.

Ein zweiter typischer Fehler. Varianten. Eine Variante, die ihr Gewicht vom Hauptartikel erbt, speichert NULL, und ein Importer, der das berichtigt, indem er den Wert des Hauptartikels auf jede Variante kopiert, macht aus einer Zeile Stammdaten tausend Zeilen, die niemand pflegen wird.

4. Ein Logistikdienstleister mit eigener Kartonisierung

Kontext. Das Lager gehört einem Logistikdienstleister, der über die Pakete entscheidet und sie im Nachhinein meldet.

Integrationsmethode. HTTP, schiebend.

Umsetzungsschritte.

Rufen Sie parcels/plan nicht auf; dieser Weg meldet ein Ergebnis, statt eines zu erfragen.

POST shipping/parcels/commit mit den Paketen, wie sie wirklich waren:

{ "orderId": "0191…",
  "source": "acme-3pl",
  "parcels": [
    { "sequence": 1,
      "weightKg": 6.42,
      "packagingMaterialId": "0191f2…",
      "volumetricWeightKg": 4.10,
      "note": "outer carton dented, retaped",
      "lines": [{ "lineItemId": "0191…", "quantity": 2 }] }
  ] }

Melden Sie Sendungsnummern wie in Fall 2.

Typischer Fehler. Einen Plan erneut zu senden, nachdem Etiketten bestehen. commit ersetzt die Aufteilung, aber Pakete, die bereits eine Sendungsnummer tragen, sind eingefroren und bleiben genau, wie sie sind, ein erneutes Senden beschädigt gebuchte Sendungen also nicht, aktualisiert sie aber auch nicht. Hat der Dienstleister ein gebuchtes Paket umgepackt, stornieren Sie es und senden Sie ein neues.

Empfohlene Vorgehensweise. Senden Sie packagingMaterialId, auch wenn Sie den Katalog nur dafür gebaut haben. Das ist es, was den Händler später fragen lässt, ob der Dienstleister sinnvolle Kartongrößen verwendet, eine Frage mit unmittelbarer Wirkung auf die Versandkosten.

5. Überwachung und BI

Kontext. Jemand will wissen, ob die Verpackungsdaten verfallen, ohne die Administration zu öffnen.

Integrationsmethode. HTTP, nur lesend.

Was zu lesen ist und was es bedeutet.

Aufruf	Melden, wenn
`GET packaging/coverage`	`summary.hasGlobalProfile` falsch ist — die ganze Funktion ist untätig
`GET packaging/coverage`	`ready / total` von Woche zu Woche fällt — neue Artikel kommen unvermessen herein
`GET packaging/collisions`	die Liste nicht leer ist — zwei Regeln stehen gleich, und niemand hat gewählt
`GET packaging/variance`	`avgVarianceKg` über einer Schwelle liegt — die Daten eines Artikels sind falsch

Typischer Fehler. Auf die Größe von gaps zu melden. Sie führt alles Unvermessene auf und bleibt in einem Shop mit langem Rest dauerhaft lang. Die Zahl, auf die es ankommt, ist ihr Anfang: die Artikel mit hohem shipments und hasDimensions: false.

6. Ein Kiosk am Arbeitsplatz

Kontext. Ein Bildschirm am Platz, den ein Packer mit einem Scanner bedient, in einem eigenen Frontend des Integrators.

Integrationsmethode. HTTP.

Umsetzungsschritte.

Lösen Sie den gescannten Code auf: GET /api/_action/p2lab-stockly/packing/scan/resolve?code=…. Es versucht das Präfix des Bestell-Barcodes, dann Bestellnummern, dann Belegnummern, und rät nie: Ein mehrdeutiger Code kommt als ambiguous samt den Kandidaten zurück.
Fordern Sie eine Aufteilung an: POST shipping/parcels/plan.
Zeigen Sie sie, lassen Sie den Packer sie ändern, dann POST shipping/parcels/commit mit floorElementId auf den Platz gesetzt. Dieser Stempel ist der einzige Moment, in dem irgendjemand weiß, welcher von drei Plätzen die Bestellung bearbeitet hat.
POST shipping/parcels/packed, wenn der Durchgang endet, damit der Buchungsauslöser des Händlers greift.

Typischer Fehler. Den Platz verlieren. floorElementId wird einmal gestempelt und nie mit null überschrieben, gerade damit ein späteres Speichern von einem Bildschirm, der den Platz nicht kennt, ihn nicht tilgen kann; wenn der Kiosk ihn aber von vornherein nie sendet, bleiben die Platzberichte leer, und das Versäumnis zeigt sich erst beim Lesen dieser Berichte.

Betriebshinweis. Gesperrte Bestellungen kommen vom Scan-Auflöser mit einem Grund zurück (storniert, unbezahlt), nicht als „nicht gefunden”. Zeigen Sie den Grund, damit niemand für eine Antwort, die sich nicht ändern wird, zum Scanner zurückgeschickt wird.

Eine Checkliste für jede Integration

Lesen Sie die vier Wege hinein, bevor Sie einen wählen; die meisten Integrationen, die Ärger machten, haben zuerst den falschen gewählt.
Schreiben Sie nie 0 anstelle von „unbekannt”.
Zeigen Sie *Source: "none" den eigenen Nutzern der Integration. So werden schlechte Daten gefunden.
Behandeln Sie batches/close als Auftrag, nicht als Aufruf.
Hat der Shop mehr als einen Packplatz, tragen Sie floorElementId überall mit, wo es möglich ist.