Packing API

Alles hier liegt unter /api/_action/p2lab-stockly/packaging/ und authentifiziert sich wie jeder andere Admin-API-Aufruf. Die Beispiele nehmen ein Bearer-Token in Authorization an.

Resolve

GET packaging/resolve?productIds=<kommagetrennt> ACL: p2lab_stockly_packaging_profile:read · höchstens 100 Ids je Aufruf

Der eine Endpunkt, den die meisten Integrationen brauchen. Er beantwortet, welche Werte für einen Artikel verwendet werden und welche Ebene sie geliefert hat.

{
  "products": [
    {
      "productId": "0191f1…",
      "packagingWeightKg": 0.06,
      "packagingWeightSource": "profile",
      "ownBox": false,
      "ownBoxSource": "global",
      "dimensionsMm": [300, 200, 100],
      "dimensionsSource": "product",
      "dunnageFactor": 1.15,
      "preferredMaterialId": "0191f2…",
      "winningProfileId": "0191f3…",
      "matchedProfileIds": ["0191f3…", "0191f4…"],
      "rankCollision": false,
      "estimated": true
    }
  ]
}

Feld	Anmerkungen
*Source	product, parent, profile, global, none
dimensionsMm	[Länge, Breite, Höhe] oder null, wenn es niemand weiß
matchedProfileIds	Gewinner zuerst, dann die Regeln, die er geschlagen hat
rankCollision	zwei Regeln gleichen Rangs haben ihn beansprucht; die Antwort ist stabil, aber willkürlich
estimated	mindestens ein Wert wurde geerbt oder angenommen statt gemessen

Typischer Fehler. packagingWeightKg: null mit packagingWeightSource: "none" heißt, dass niemand eines erfasst hat. Stellen Sie das nicht als 0,00 kg dar; dieser Unterschied ist der Grund, warum es das Feld gibt.

Coverage

GET packaging/coverage?page=1&limit=50 ACL: p2lab_stockly_packaging_profile:read

{
  "summary": {
    "total": 4812,
    "missingDimensions": 3140,
    "missingWeight": 210,
    "ready": 1672,
    "materials": 8,
    "profiles": 5,
    "hasGlobalProfile": true
  },
  "gaps": [
    {
      "productId": "0191f1…",
      "productNumber": "SW10001",
      "name": "Wall paint, white, 5 l",
      "shipments": 412,
      "hasWeight": true,
      "hasDimensions": false,
      "hasOwnRow": false
    }
  ]
}

gaps ist absteigend nach shipments der letzten sechs Monate geordnet. Diese Ordnung ist der nützliche Teil: Sie macht aus der Aufgabe, fünftausend Artikel zu berichtigen, das Berichtigen der vierzig, die täglich hinausgehen.

hasGlobalProfile: false ist eine eigene Meldung wert. Ohne eine Auffangregel bekommen Artikel außerhalb jedes Profils überhaupt keine Verpackungsdaten.

Kollisionen

GET packaging/collisions?limit=50 ACL: p2lab_stockly_packaging_profile:read

{
  "collisions": [
    {
      "productId": "0191f1…",
      "productNumber": "SW10001",
      "name": "Wall paint, white, 5 l",
      "matchRank": 100,
      "profiles": [
        { "id": "0191f3…", "name": "Paints 5 l" },
        { "id": "0191f4…", "name": "Fragile goods" }
      ]
    }
  ]
}

Normalerweise leer. Eine nicht leere Liste heißt, dass zwei Regeln desselben Rangs denselben Artikel beanspruchen, der Gewinner also durch einen internen Vergleich entschieden wird und nicht vom Händler.

Variance

GET packaging/variance?limit=50&minVarianceKg=0.05 ACL: p2lab_stockly_parcel:read

{
  "variance": [
    {
      "productId": "0191f1…",
      "productNumber": "SW10001",
      "name": "Wall paint, white, 5 l",
      "parcels": 37,
      "avgVarianceKg": 0.42,
      "maxVarianceKg": 0.61,
      "avgEstimatedKg": 5.9
    }
  ]
}

Gezählt werden nur Pakete, die eine einzige Artikelart enthalten; in einem gemischten Karton lässt sich ein Fehler keinem davon zuschreiben. Positiv heißt, dass das Paket schwerer ausfiel als vorhergesagt.

Verpackungsdaten schreiben

Es gibt hier mit Absicht keinen Schreib-Endpunkt: Verpackungsdaten sind gewöhnliches DAL, die Standard-Admin-API deckt sie also bereits ab, mit weniger zu lernen und weniger kaputtzumachen.

POST /api/p2lab-stockly-packaging-material
{
  "code": "K30",
  "label": "Carton 300x200x150",
  "type": "box",
  "innerLengthMm": 300,
  "innerWidthMm": 200,
  "innerHeightMm": 150,
  "tareKg": 0.28,
  "maxPayloadKg": 20,
  "active": true
}

POST /api/p2lab-stockly-packaging-profile
{
  "name": "Paints 5 l",
  "matchType": "property",
  "matchId": "<property_group_option id>",
  "matchRank": 100,
  "packagingWeightKg": 0.06
}

POST /api/p2lab-stockly-product-packaging
{
  "productId": "0191f1…",
  "packagingWeightKg": 0.12,
  "ownBox": true
}

Fallen beim Schreiben

• Eine Zeile je Artikel in p2lab_stockly_product_packaging. Der eindeutige Schlüssel setzt das durch, und der passende Schreibvorgang ist ein Upsert über productId.
• Lassen Sie ein Feld weg, statt 0 oder false zu senden, außer dieser Wert ist beabsichtigt. Das Weglassen erbt; ein Wert entscheidet.
• matchType: null ist die globale Zeile. Halten Sie genau eine.
• Gleiche matchRank-Werte sind zulässig und werden gemeldet statt abgewiesen; siehe Kollisionen. Wählen Sie verschiedene Ränge.