Zum Inhalt

PlentyOne — Write-Operations

Empirisch validierte Pflichtfelder + Fallstricke für Write-Endpoints. Vor jedem neuen Workflow, der schreibt, hier nachlesen.

Quelle: SUB Retoure (gebaut + getestet am 12.05.2026 gegen Hauptauftrag 370944).

POST /rest/orders — Retoure (oder Auftrag) anlegen

Endpoint: POST https://p38991.my.plentysystems.com/rest/orders

Auth: Bearer-Token aus Login PlentyOne-Node → siehe Auth-Patterns.

Pflichtfelder (Body)

{
  "typeId": 3,
  "plentyId": <fromParent>,
  "locationId": <fromParent>,
  "referrerId": <fromParent>,
  "ownerId": 78,
  "statusId": 9.01,
  "orderReferences": [
    { "referenceType": "parent", "referenceOrderId": <parentId> }
  ],
  "orderItems": [
    {
      "typeId": 1,
      "itemVariationId": <fromParent>,
      "quantity": <fromMailOrParent>,
      "orderItemName": "...",
      "amounts": [ /* OHNE id/orderItemId */ ],
      "references": [
        { "referenceType": "parent", "referenceOrderItemId": <parentItemId> }
      ],
      "properties": [
        { "typeId": 35, "value": "1" }
      ]
    }
  ],
  "properties": [
    { "typeId": 7, "value": "<externalOrderId-vom-parent>" },
    { "typeId": 1, "value": "<warehouseId-vom-parent>" },
    { "typeId": 2, "value": "<shippingProfileId-vom-parent>" },
    { "typeId": 995, "value": "<treueprogramm-falls-vorhanden>" }
  ],
  "addressRelations": [
    { "typeId": 1, "addressId": <fromParent> },
    { "typeId": 2, "addressId": <fromParent> }
  ]
}

Empirisch gefundene Fallstricke

  1. addressRelations ist Pflicht — sonst Status 1 (unvollständig) statt 9.01. Kritisch.
  2. amounts[] ohne System-IDs (id, orderItemId) — sonst 422. Plenty vergibt die selbst.
  3. ownerId: 78 (n8n-User) verwenden — sonst läuft die GLS/DHL-Ereignisaktion ggf. falsch.
  4. Item-Filter sinnvoll setzen: typeId !== 6 (Versandkosten raus) und itemVariationId > 0 (Phantome raus). Bei Bundles bleibt typeId 2 (Master) und typeId 3 (Komponenten) drin.
  5. statusId: 9.01 ist direkt setzbar wenn addressRelations mit im Body sind — kein nachgelagertes PUT nötig.
  6. Plenty-Ereignisaktion 496 GLS (oder DHL-Pendant) feuert trotzdem ein Plenty-Label — bewusst akzeptiert, 01 Retouren-Erfassung filtert den Plenty-Auto-Comment per [n8n Amazon-RSA-Marker.

Retourengrund-Property

typeId: 35, Werte siehe Reference: Mokebo Plenty IDs. Default value: "1" = „kein Grund bekannt".

Bundle-Behandlung

Master + Komponenten haben dieselbe SKU (Property typeId: 98). Wenn Master matcht, kommen alle Komponenten automatisch mit. Filter im Item-Loop: typeId in [1, 2, 3] und itemVariationId > 0.

POST /rest/comments — Comment an Auftrag posten

Endpoint: POST https://p38991.my.plentysystems.com/rest/comments

⚠️ NICHT POST /rest/comments/order/{id} benutzen — der gibt zwar HTTP 200 zurück, ist aber ein HTML-Redirect (x-location: /index.php), kein API-Schreib-Endpoint.

Pflichtfelder

{
  "referenceType": "order",
  "referenceValue": <orderId-als-Integer>,
  "text": "...",
  "isVisibleForContact": false,
  "userId": 78
}

Fallstricke

  1. userId ist Pflicht wenn isVisibleForContact: false. Plenty wirft sonst 422 mit Validation-Error "user id muss ausgefüllt sein wenn is visible for contact false ist".
  2. userId: 78 verwenden (n8n-User). Andere User-IDs (67 = apoio, 2 = System) sind möglich, aber semantisch falsch.
  3. referenceValue als Integer, nicht als String.
  4. isVisibleForContact: false für interne Notizen. Plenty-API-internes Flag — bei mokebo-Setup (Marketplace via Amazon/Shopify) ist true ohnehin irrelevant, der Kunde sieht Plenty eh nicht.
  5. UI-Cache: Plenty-UI cacht stark. Nach POST den Auftrag schließen + neu öffnen, sonst alter Stand sichtbar.
  6. GET-Verifikation: GET /rest/comments/order/{id} listet alle Comments — funktioniert auch wenn das UI sie nicht zeigt.

Mokebo-spezifische Comment-Patterns

Idempotency-Marker am Hauptauftrag (durch SUB Retoure):

[n8n] Auto-Retoure für Amazon-RSA Ticket #<ticketId> angelegt: Retoure <retourenAuftragId>

Tracking-Comment am Retoure-Auftrag (durch SUB Retoure, triggert 01-Retouren-Erfassung-Priorisierung):

[n8n Amazon-RSA #<ticketId>] Retourensendung angemeldet: DHL, Sendungsnummer: <number>

Der [n8n Amazon-RSA-Prefix ist kritisch — 01 Retouren-Erfassung ignoriert den Plenty-Auto-Comment wenn der Marker vorhanden ist.