Posted by Markus Wals

Sicher schreiben: PUT, version, Read-after-write und Idempotenz in der weclapp API

API dryRun Idempotenz Integration Optimistic Locking PUT Read-after-write weclapp

Titelgrafik: Sicher schreiben. weclapp API, Das Handbuch, Teil 04: PUT, Versionen und Read-after-write.

Kurz gesagt: Sicher in die weclapp API schreibst du, wenn du PUT als Vollersatz behandelst, Item-Listen per Merge zurücksendest, nach einem Timeout den Zielzustand nachliest statt blind zu wiederholen und jeden Seiteneffekt mit einem eigenen Idempotenz-Schlüssel absicherst.

Lesen verzeiht viel. Ein falscher Filter kostet Zeit, ein zu großer Abruf kostet Last. Schreiben verzeiht wenig: Ein PUT mit dem falschen Array löscht Positionen, ein erneuter Klick nach einem Timeout bucht doppelt, und der Fehler fällt oft erst auf, wenn eine Rechnung oder ein Carrier-Konto betroffen ist.

Christian Lanig (weclapp) nannte am Community Day 2026 für die Schreibseite ein klares Prinzip: nur Änderungen übertragen, unnötige Updates vermeiden. Wie das konkret geht, ohne dabei etwas zu verlieren, lassen die Folien offen. Dieser Artikel füllt die Lücke mit dem, was in der Doku steht, und dem, was wir aus Integrationen im Dauerbetrieb kennen: Fulfillment 4 weclapp, 4Fulfillment und unsere weclapp-Anbindungen in n8n.

Der rote Faden: Gehe bei jedem Schreibzugriff davon aus, dass er zweimal ankommen oder halb ankommen kann, und baue so, dass das egal ist. In allen Beispielen gilt: Basis-URL https://<dein-mandant>.weclapp.com/webapp/api/v2/, Header AuthenticationToken: <dein-token>. Schreibzugriffe probierst du gegen ein Testsystem aus.

Das Wichtigste in Kürze

  • PUT ersetzt die ganze Entität. Für Teil-Updates setzt du ignoreMissingProperties=true und sendest die version mit.
  • Item-Listen sind Zielzustand. Jede bestehende Position geht als Stub mit id und version zurück, sonst ist sie weg.
  • Ein Timeout heißt nicht gescheitert. Du liest den Zielzustand mit wachsender Wartezeit nach, statt den Write blind zu wiederholen.
  • Idempotenz baust du selbst. weclapp kennt keine Idempotency-Keys, also sichern Checkpoint, Signatur und Nonce deine Seiteneffekte ab.
  • Verknüpfte Belege entstehen über Aktionen. createSalesInvoice und Co. ersetzen jeden Nachbau, und dryRun gilt nur für generische Writes.

PUT ist ein Vollersatz: ignoreMissingProperties=true

Ein PUT auf eine weclapp-Entität ersetzt sie. Die Doku sagt es direkt: Alle Properties, die du nicht angibst, werden als null interpretiert. Für ein Teil-Update gibt es den Parameter ignoreMissingProperties=true; die Doku empfiehlt, dabei immer die version mitzusenden.

PUT https://<dein-mandant>.weclapp.com/webapp/api/v2/salesOrder/id/<auftrags-id>?ignoreMissingProperties=true
AuthenticationToken: <dein-token>
Content-Type: application/json

{ "version": "5", "recordFreeText": "Bitte vor Lieferung telefonisch avisieren" }

Zwei Hinweise dazu. Erstens steht ignoreMissingProperties in der Prosa der Doku, ist aber nicht als Parameter in der OpenAPI-Spec deklariert. Clients, die aus der Spec generiert werden, bieten ihn deshalb nicht von allein an. Zweitens bist du damit nicht vollständig geschützt, denn der Parameter gilt nur für Properties auf oberster Ebene. Dazu der nächste Abschnitt.

Eine Faustregel für Entitäten mit empfindlichen Abhängigkeiten, etwa Verträge: Sende einen minimalen Payload. Bei einem Vertrag kippte ein vermeintlich harmloses Update mehrerer Kopffelder den Schalter für die abweichende Korrespondenzadresse, obwohl er nicht im Payload stand. Ein Payload aus nur version und dem geänderten Status war dagegen feldweise identisch zum Vorzustand. Lies den zurückgegebenen Datensatz deshalb feldweise gegen den Vorzustand.

Fazit: Sende nur, was sich ändert, mit Flag und version, und prüfe das Ergebnis feldweise.

Item-Arrays sind Vollersatzlisten

Positionen, Pakete, Preiszeilen: Alle Listen mit eigenen Einträgen sind Zielzustand, auch mit ignoreMissingProperties=true. Die Doku formuliert es so: Wer die id eines bestehenden Listeneintrags weglässt, entfernt oder leert ihn. Betroffen sind unter anderem orderItems, shipmentItems, incomingGoodsItems, parcels und articlePrices.

Die Fehlerbilder sind unterschiedlich. Bei Belegpositionen bekommst du häufig recordItem cannot be deleted, bei anderen Listen verschwinden Einträge einfach, etwa fehlende bestehende Preiszeilen am Artikel. Ein zweites Fehlerbild ist property orderItems[n].manualUnitPrice cannot be updated: Du hast versucht, einen geschützten Schalter an einer bestehenden Position zu ändern.

Grafik: Item-Merge, jede ID bleibt erhalten. Erst den Bestand per GET lesen, dann im PUT Position P1 geändert, Position P2 als Stub mit id und version und eine neue Position ohne id zurücksenden.

Das robuste Muster ist der Merge. Es hat vier Schritte:

  1. Die Entität frisch per GET holen, mit Beleg-id, version und der kompletten Item-Liste.
  2. Jede bestehende Position zurücksenden: unverändert als Stub mit id und version, geändert mit den neuen Werten.
  3. Neue Positionen ohne id anhängen.
  4. Vor dem Senden prüfen, dass keine bestehende Item-ID im Payload fehlt.
PUT https://<dein-mandant>.weclapp.com/webapp/api/v2/salesOrder/id/<auftrags-id>?ignoreMissingProperties=true
AuthenticationToken: <dein-token>
Content-Type: application/json

{
  "version": "5",
  "orderItems": [
    { "id": "<position-1>", "version": "3", "quantity": "2" },
    { "id": "<position-2>", "version": "1" }
  ]
}

Position 2 ändert sich nicht, steht aber als Stub im Array. Dasselbe als Funktion:

function mergeItems(existing, updates) {
  const byId = new Map(updates.filter((u) => u.id).map((u) => [String(u.id), u]));
  const merged = existing.map((e) => {
    const u = byId.get(String(e.id));
    return u ? { ...u, id: e.id, version: e.version } : { id: e.id, version: e.version };
  });
  const added = updates.filter((u) => !u.id);
  return [...merged, ...added];
}

// Letzte Sicherung vor jedem Item-PUT, auch für Payloads aus anderen Quellen
function assertNoItemLost(existing, payloadItems) {
  const sent = new Set(payloadItems.map((i) => String(i.id)));
  const lost = existing.filter((e) => !sent.has(String(e.id)));
  if (lost.length) {
    throw new Error(`Item-IDs fehlen im Payload: ${lost.map((e) => e.id).join(", ")}`);
  }
}

const orderItems = mergeItems(current.orderItems, updates);
assertNoItemLost(current.orderItems, orderItems);

Zwei Zusätze aus der Praxis. Ändere keine geschützten Schalter an bestehenden Positionen: Hat eine Position manualUnitPrice=false, lass sie so und sende keine abweichende Preisänderung. Und löschst du wirklich eine Position, mache es bewusst und nicht als Nebeneffekt: Bei uns braucht das ein ausdrückliches allow_item_removal.

Dasselbe Prinzip gilt für Buchungszeilen im Wareneingang: POST /incomingGoods/id/{id}/updateIncomingBookings nimmt immer den vollständigen Ersatzsatz.

Fazit: Jede bestehende Position gehört in den Payload, sonst löschst du sie mit.

version und Optimistic Locking: wann mitsenden, wann nicht

weclapp sichert Updates über das Feld version. Ist sie im Body und stimmt nicht mit dem aktuellen Stand überein, antwortet die API mit dem Fehler optimistic_lock und Status 409. Lässt du version weg, ist die Sperre aus und der letzte Schreiber gewinnt; die Doku warnt, dass dabei Änderungen anderer überschrieben werden können.

Für die meisten Updates ist die Regel eindeutig: version mitsenden. Kommt ein 409, holst du die Entität neu, wendest deine Änderung erneut an und versuchst es mit einer festen Obergrenze an Wiederholungen noch einmal. So steht es auch in der Doku.

Zwei Dinge machen das in der Praxis kniffliger:

  • Listen liefern manchmal eine veraltete version. Direkt nach einem Write kann eine Listenabfrage noch den alten Stand zeigen und beim nächsten PUT einen 409 auslösen. Hole die version deshalb vor jedem PUT frisch per GET auf die einzelne Entität.
  • Der Lock hat zwei Gesichter. In unserem Betrieb kam der Fehler je nach Pfad als 409 oder als 400. Klassifiziere ihn nicht über den Statuscode allein, sondern über das Suffix optimistic_lock im Fehlertyp oder den Text „optimistic lock error“.
GET https://<dein-mandant>.weclapp.com/webapp/api/v2/salesOrder/id/<auftrags-id>?properties=id,version,status
AuthenticationToken: <dein-token>
PUT https://<dein-mandant>.weclapp.com/webapp/api/v2/salesOrder/id/<auftrags-id>?ignoreMissingProperties=true
AuthenticationToken: <dein-token>
Content-Type: application/json

{ "version": "<version-aus-dem-GET>", "recordFreeText": "Bitte vor Lieferung telefonisch avisieren" }

Bei einem Pfad machen wir eine bewusste Ausnahme, die der Doku-Empfehlung widerspricht: beim Versand-Flow in Fulfillment 4 weclapp. Dort entfernen wir die version des Aufrufers vor dem PUT. Der Grund war ein reproduzierter Fall: Ein älterer Snapshot im Speicher trug version=62, ein frischer Lesezugriff im selben Ablauf sah schon 63, der PUT mit der alten Version scheiterte mit 409. Bei Wiederholungen nach einem Timeout ist die alte version die Fehlerquelle. Dort schützen wir uns stattdessen durch Checkpoint und Nachlesen, wie es die nächsten Abschnitte zeigen.

Fazit: Frische Updates ohne Nebenwirkung laufen mit version und begrenztem Retry, wiederholungsanfällige Writes mit Nebenwirkungen ohne Aufrufer-version, dafür mit Checkpoint und Read-after-write.

Timeout heißt nicht gescheitert: Read-after-write statt Blind-Retry

Das ist der Abschnitt, den wir jeder Integration ans Herz legen. weclapp stellt Requests bei hoher Last in eine Queue und lässt sie bis zu 30 Sekunden warten, danach antwortet die API mit 429. Gleichzeitig empfiehlt die Doku Client-Timeouts von mindestens einer Minute. Wer kürzer wartet, bricht Requests ab, die weclapp trotzdem noch verarbeitet. Mehr dazu in Teil 1 zum Lastmanagement.

Für Schreibzugriffe heißt das: Ein Timeout sagt dir nicht, ob der Write angekommen ist. Nach Auskunft von weclapp gilt sonst: Liefert die API eine Fehlermeldung, sollen keine Änderungen gespeichert und keine Mails versendet sein. Die Ausnahme sind Einzelfälle, in denen ein Request kurz nach dem angeforderten Timeout noch erfolgreich abschließt (die Doku schreibt, dass Requests gelegentlich etwas länger dauern können). Dann kommt auch die Erfolgsmeldung.

Ein 409 kann trotzdem auftauchen, als Echo: Wiederholst du einen Write nach einem Timeout und der erste Versuch hat inzwischen gespeichert, ist die version erhöht und der zweite Versuch scheitert mit 409. Der Zielzustand ist dann oft schon erreicht, und nur Nachlesen klärt das. Im Versandalltag führt genau das zum klassischen Folgefehler: Die Oberfläche meldet nach einem Timeout „Fehler“, jemand klickt erneut auf Versenden und erhält entweder „Lieferung bereits versandt“ oder löst eine zweite, kostenpflichtige Carrier-Buchung aus.

Die Antwort darauf ist Nachlesen statt Wiederholen:

  1. Den Fehler als unsicher einstufen: Timeout, Verbindungsabbruch und ein Optimistic Lock oder 409, der auf einen Wiederholungsversuch nach einem Timeout folgt.
  2. Kein automatischer Retry des Writes.
  3. Die Entität mit wachsender Wartezeit neu lesen und prüfen, ob der Zielzustand schon da ist (Status, Trackingnummer, die geschriebenen Felder).
  4. Ist er da, zähle den Write als Erfolg, mit einer Warnung im Log. Ist er nach den Wartezeiten nicht da, eskaliere.

Unsere Wartezeiten sind 0, 2, 5, 10, 20 und 30 Sekunden. Warum nicht sofort lesen? Weil die Leseseite dem Schreiben hinterherhinken kann: Direkt nach einem Write haben wir 404er auf Folgeaktionen gesehen, und ein Clear-PUT nach dem Anlegen einer Lieferung war kurz noch nicht sichtbar. Dokumentiert ist dieses Zeitfenster nicht, es ist eine Beobachtung aus unserem Betrieb.

const BACKOFF_MS = [0, 2000, 5000, 10000, 20000, 30000];

function isUncertain(err) {
  const text = String(err.message).toLowerCase();
  return (
    err.code === "ECONNABORTED" ||
    err.status === 409 ||
    text.includes("timeout") ||
    text.includes("optimistic lock")
  );
}

async function writeThenVerify(put, readBack, matchesTarget) {
  try {
    return await put();
  } catch (err) {
    if (!isUncertain(err)) throw err; // z. B. 400 validation: korrigieren, nicht wiederholen
    for (const wait of BACKOFF_MS) {
      await new Promise((r) => setTimeout(r, wait));
      const current = await readBack();
      if (matchesTarget(current)) {
        return { recovered: true, current }; // Erfolg mit Warnung
      }
    }
    err.state = "ambiguous"; // nicht als "fehlgeschlagen" melden
    throw err;
  }
}
GET https://<dein-mandant>.weclapp.com/webapp/api/v2/shipment/id/<lieferung-id>?properties=id,status,packageTrackingNumber
AuthenticationToken: <dein-token>

Unser Code behandelt vorsichtshalber jeden 409 als unsicher, nicht nur den nach einem Timeout. Bei einem echten Konflikt kostet das Nachlesen nur einen zusätzlichen Lesezugriff.

Grafik: Die Read-after-write-Schleife. Ein Blind-Retry nach dem Timeout bucht doppelt oder scheitert mit 409. Read-after-write liest nach 0, 2, 5, 10, 20 und 30 Sekunden nach und bestätigt eine Buchung mit Warnung.

Ein Vorbehalt gehört dazu: Ein unveränderter Readback nach einem Timeout beweist nicht, dass der Write nie ankommt. Er kann spät committen. Stufe den Zustand deshalb als ambiguous ein und lasse ihn nicht als „fehlgeschlagen“ durchlaufen, bis er geklärt ist.

Die Fehler im Überblick, speziell für Schreibzugriffe:

Fehler Was es für den Write bedeutet Reaktion
400 validation Request wurde abgelehnt Payload korrigieren, nicht unverändert wiederholen
409 optimistic_lock Bei einer Fehlerantwort sollen laut weclapp keine Änderungen gespeichert sein. Entweder echter Konflikt, oder ein früherer Versuch hat inzwischen gespeichert und die version erhöht Nachlesen; nur bei Writes ohne Nebenwirkung neu holen und begrenzt neu versuchen
400 request_timeout Du hast X-Weclapp-Request-Timeout-Ms gesetzt und es lief ab. Bei einer Fehlermeldung sollen laut weclapp keine Änderungen gespeichert sein. Das Limit ist Best-Effort: In Einzelfällen schließt der Request kurz danach erfolgreich ab, dann kommt die Erfolgsmeldung statt des 400 Antwort auswerten; vor einem Retry den Zielzustand nachlesen (unsere Praxis)
409 persistence Sammelfehler der Persistenz Nur bei idempotenten Writes kurz warten und neu versuchen
429 Die Queue-Zeit ist abgelaufen. Der Request wurde laut weclapp noch nicht bearbeitet Backoff mit Jitter, danach GET und andere sichere Methoden erneut senden. Writes erst nachlesen und dann wiederholen, auch wenn der Request laut weclapp noch nicht bearbeitet wurde. Einen Retry-After-Header sendet weclapp aktuell nicht (eine Einführung wird überlegt); 10 Sekunden bis zum ersten erneuten Versuch können laut weclapp eine gute Empfehlung sein, je nach Timeouts und Szenario passen andere Werte
Timeout, Verbindungsabbruch Ausgang unbekannt Nachlesen, nie blind wiederholen

Automatische Wiederholungen sind für sichere Methoden vorgesehen, vor allem GET. Writes, die eine Wirkung außerhalb von weclapp haben (Druck, Zahlung, Lagerbuchung, Label), bekommen nie einen blinden Retry, auch nicht nach einem 429. Laut weclapp wurde der Request dann zwar noch nicht bearbeitet, bei Writes mit Außenwirkung liest du trotzdem erst den Zielzustand nach und wiederholst danach.

Fazit: Nach einem unsicheren Fehler liest du nach, statt zu wiederholen, und lässt den Zustand ambiguous zu, bis er geklärt ist.

Idempotenz: dein eigener Schlüssel

weclapp kennt keine Idempotency-Keys. Du kannst einen Request nicht mit einem Schlüssel versehen, der eine zweite Ausführung erkennt. Idempotenz muss deshalb in deiner Integration entstehen. Ein bewährtes Muster hat drei Teile:

  1. Checkpoint vor dem Seiteneffekt. Schreibe in einen eigenen Speicher, was du gleich tun wirst („pending“), bevor du den Request sendest, und „committed“, sobald der Zielzustand bestätigt ist.
  2. Signatur aus dem aufgelösten Ergebnis, nicht aus der Eingabe. Bilde den Schlüssel aus den Fakten, die den Seiteneffekt ausmachen, zum Beispiel Lieferung, ausgehender Carrier und Paketanzahl.
  3. Nonce für bewusste Wiederholung. Willst du etwas absichtlich noch einmal tun, erzeuge pro Bestätigung eine neue ID und nimm sie in die Signatur auf.

Warum Punkt 2 wichtig ist, zeigt ein typisches Integrationsproblem: Ruft der Schlüssel nur den Eingabenamen des Carriers ab (etwa einmal „weclapp“ und einmal „direct“), entstehen bei zwei Klicks zwei verschiedene Signaturen. Bei Carriern ohne Storno-Schnittstelle geht der zweite Auftrag dann als kostenpflichtige Zusatzbuchung durch. Die Lösung: erst den Carrier auf die tatsächlich ausgehende Variante vereinheitlichen, dann signieren.

import { createHash } from "node:crypto";

function signature({ shipmentId, resolvedCarrierId, parcelCount, reshipAttemptId = "" }) {
  return createHash("sha256")
    .update(JSON.stringify([shipmentId, resolvedCarrierId, parcelCount, reshipAttemptId]))
    .digest("hex");
}

Ein Beispiel für Punkt 3: Der Dialog „Diese Lieferung wurde bereits versandt, trotzdem versenden?“ lief bei uns endlos im Kreis, weil die Bestätigung zwar die Statusprüfung umging, aber nicht den Checkpoint. Die Lösung war eine frische reshipAttemptId je Bestätigung: Dieselbe Nonce bedeutet Wiederverwendung der vorhandenen Ergebnisse (ein Wiederholungsversuch nach einem Timeout), eine neue Nonce bedeutet einen bewusst neuen Versand. Eine einfache Umgehung der Prüfung hätte die Idempotenz verloren.

Grafik: Zwei Klicks, eine Buchung. Klick 1 und Klick 2 mit unterschiedlich benanntem Carrier führen nach dem Auflösen zur selben Signatur, der Checkpoint stoppt die zweite Buchung. Eine neue reshipAttemptId erlaubt einen bewussten Neuversand.

Einfacher geht es, wenn weclapp selbst den Zustand trägt. Ein Zusatzfeld am Beleg als Statusflag („importiert“, „versendet“) ist ein bewährter Handshake, damit nichts doppelt verarbeitet wird; ein Beispiel steht im Fulfiller-Leitfaden. Achte nur darauf, dass deine eigenen Writes keine Webhooks auslösen, die dich wieder aufrufen. Wie du das verhinderst, steht in Teil 5 zu Webhooks und Delta-Sync.

Fazit: Checkpoint vor dem Seiteneffekt, Signatur aus dem aufgelösten Ergebnis und eine Nonce für bewusste Wiederholung machen jeden Write idempotent.

Native Aktionen statt Nachbau

Verknüpfte Belege entstehen in weclapp nur über die Aktion, nicht durch das Setzen von Feldern. Eine direkt per POST angelegte Rechnung lässt sich nicht mit dem Auftrag verknüpfen: salesOrderId im POST wird akzeptiert und verworfen, im PUT kommt ein 400. Mehr dazu in Teil 3 zu den stillen Fehlern. Den richtigen Weg gibt es als Aktion:

POST https://<dein-mandant>.weclapp.com/webapp/api/v2/salesOrder/id/<auftrags-id>/createSalesInvoice
AuthenticationToken: <dein-token>
Content-Type: application/json

{}

Voraussetzung ist ein Auftrag im Status ORDER_CONFIRMATION_PRINTED. Analog funktionieren POST /salesOrder/id/{id}/createShipment und POST /purchaseOrder/id/{id}/createIncomingGoods.

POST https://<dein-mandant>.weclapp.com/webapp/api/v2/purchaseOrder/id/<bestell-id>/createIncomingGoods
AuthenticationToken: <dein-token>
Content-Type: application/json

{ "additionalPurchaseOrderIds": [] }

Drei Regeln für den Umgang mit Aktionen:

  • Nicht erneut aufrufen, sondern ergänzen. createIncomingGoods liefert einen offenen Wareneingang mit je einer Position in voller Bestellmenge. Ein zweiter Aufruf legt einen weiteren an. Passe stattdessen den bestehenden an, und denke dabei an den Vollersatz der Item-Liste.
  • Reihenfolge beachten. Eine Schlussrechnung entsteht erst richtig, wenn die Anzahlung als Zahlung verbucht ist. Sonst steht dort „abzgl. Anzahlung: 0,00 €“ und der Kunde wird doppelt gefordert.
  • Statuswechsel mit Mailregeln über die Aktion. Ein roher Status-PUT akzeptiert auch Rückwärtskanten und kann Mailregeln auslösen. manuallyClose ist der saubere Weg, mehr dazu in Teil 3.

Fazit: Aktionen sind gleichzeitig Seiteneffekte, für sie gilt das Muster aus dem Abschnitt über Read-after-write.

dryRun richtig einsetzen

dryRun=true führt einen Write im Probelauf aus: Die Daten werden validiert und, wo möglich, läuft die Geschäftslogik, aber nichts wird gespeichert. Die Antwort hat Status 200 statt 201 und enthält keine Metadaten wie id, version oder Datumsfelder. Das ist ein praktischer Vorabtest: Er prüft den Body und auch deine Berechtigungen.

POST https://<dein-mandant>.weclapp.com/webapp/api/v2/salesOrder?dryRun=true
AuthenticationToken: <dein-token>
Content-Type: application/json

{ "customerId": "<party-id>" }

Gut geeignet ist das für Preflight-Prüfungen in der CI oder vor dem Start eines größeren Laufs. Ein Fehler kommt als normaler 400 mit validationErrors, bei Erfolg ein 200 ohne id.

Es gilt aber nur für generische Writes: POST auf die Sammlung, PUT und DELETE auf die einzelne Entität. Aktionen wie createCreditNote kennen den Parameter nicht und laufen echt. Ein Aufruf von createCreditNote?dryRun=true antwortet beispielsweise mit 200 und leerem Body, legt aber trotzdem eine echte Gutschrift an. Warum die API unbekannte Parameter still ignoriert, erklärt Teil 3 zu den stillen Fehlern. Die Regel dazu: Vor jedem dryRun klären, ob du einen generischen Write oder eine Aktion vor dir hast. Bei Aktionen gibt es keinen Probelauf, nur das Testsystem.

Was dryRun nebenher bewirkt, zum Beispiel ob Nummernkreise verbraucht werden oder Webhooks auslösen, nennt die Doku nicht („wo möglich“). Behandle dryRun deshalb nicht als garantiert nebenwirkungsfrei.

Fazit: dryRun ist ein guter Preflight für generische Writes, bei Aktionen hilft nur das Testsystem.

Kurzhinweise: Steuern, Preise, Zusatzfelder

Drei Themen mit eigenen Schreibregeln. Die Details stehen in Teil 9 zu den Datentypen; hier nur das, was du fürs sichere Schreiben brauchst.

  • Steuern: nicht mitsenden. weclapp leitet die Positionssteuer vom Artikel oder dem Mandanten-Standard ab. Lass taxId und taxRateType aus Schreib-Payloads weg. Kommt der Fehler „no item tax found“, fehlt ein Eintrag in der Steuermatrix; dann setzt du taxId an der Position von Hand.
  • Preise: alle Zeilen mitsenden. Bestehende Preiszeilen am Artikel müssen mit id und version im PUT stehen, sonst werden sie gelöscht. Die Überlappungsprüfung arbeitet auf Sekundenraster, und das Enddatum einer vorhandenen Zeile lässt sich nicht ändern.
  • Zusatzfelder: das passende Wertfeld. Jeder Typ hat sein eigenes Wertfeld (booleanValue, numberValue, stringValue und so weiter); ein falsches wird still ignoriert. Laut Doku werden Einträge von customAttributes, die du nicht mitsendest, aus der bestehenden Entität übernommen. Wir lesen in der Praxis trotzdem erst die ganze Entität und setzen den Wert im Round-Trip.

Fazit: Steuern weglassen, Preiszeilen vollständig senden, Zusatzfelder mit dem passenden Wertfeld schreiben.

Checkliste: Schreiben ohne Reue

  1. Teil-Update mit ignoreMissingProperties=true und version, bei empfindlichen Entitäten ein minimaler Payload.
  2. Item-Arrays als Merge: jede bestehende Position als Stub, neue ohne id, vorher prüfen, dass keine ID fehlt.
  3. version frisch per GET holen, nicht aus einer Liste. Bei 409 begrenzt neu versuchen, aber nur bei Writes ohne Nebenwirkung.
  4. Timeout und Verbindungsabbruch sind unsicher, ein 409 nach einem Wiederholungsversuch auch. Nachlesen mit wachsender Wartezeit, kein blinder Retry. Ein 429 heißt laut weclapp: noch nicht bearbeitet. GET sendest du mit Backoff erneut, Writes erst nach dem Nachlesen.
  5. Zustand ambiguous zulassen und nicht als Fehler durchreichen, bis er geklärt ist.
  6. Eigener Idempotenz-Schlüssel: Checkpoint vor dem Seiteneffekt, Signatur aus dem aufgelösten Ergebnis, Nonce für bewusste Wiederholung.
  7. Native Aktionen für verknüpfte Belege (createSalesInvoice, createShipment, createIncomingGoods), nicht nachbauen.
  8. dryRun nur bei generischen Writes, bei Aktionen nie.
  9. Read-back nach jedem neuen Schreibpfad, Felder vergleichen statt Status.
  10. Test gegen eine Sandbox, nie gegen Produktion.

Weiterlesen und Ausprobieren

Dieser Artikel gehört zur Serie „weclapp API: Das Handbuch“. Weiter geht es mit Teil 1 zum Lastmanagement, Teil 3 zu den stillen Fehlern und Teil 5 zu Webhooks und Delta-Sync. Mit der kostenlosen Postman Collection 4 weclapp spielst du die Requests aus diesem Artikel gegen dein Testsystem nach. Einen Gesamtüberblick über Authentifizierung, Filter, Projektion und die Belegkette gibt das Webinar „weclapp API Deep Dive“ auf YouTube.

Quellen und Grenzen

  • weclapp API-Dokumentation v2 (openapi_v2.yaml, abgerufen am 17.11.2026): Vollersatz bei PUT, ignoreMissingProperties, Listeneinträge ohne id, Optimistic Locking, Fehlertypen, Queue und Timeouts, dryRun.
  • Auskunft von weclapp (Oktober 2026) zu Fehlerantworten, Status 429, Timeouts und Retry-After.
  • Vortrag „Jeder Request zählt“ von Christian Lanig (weclapp), Community Day 2026.

Die Muster stammen aus unseren eigenen Integrationen im Dauerbetrieb; Fehlerbilder und Zeitfenster, die die Doku nicht nennt, sind als Beobachtung gekennzeichnet und können je Entität und Mandant abweichen. Der Artikel ersetzt keinen Test gegen dein eigenes Testsystem.

Häufige Fragen

Warum sind nach meinem PUT Felder oder Positionen leer?

Ein PUT ersetzt die ganze Entität, fehlende Properties werden als null interpretiert. Setze ignoreMissingProperties=true und sende bei Item-Listen jede bestehende Position mit id und version mit.

Muss ich die version bei jedem Update mitsenden?

Für die meisten Updates ja, denn sie aktiviert das Optimistic Locking. Hole sie vorher frisch per GET auf die einzelne Entität, nicht aus einer Liste.

Was mache ich nach einem Timeout bei einem Schreibzugriff?

Nicht blind wiederholen, sondern den Zielzustand mit wachsender Wartezeit nachlesen. Ist er erreicht, zählt der Write als Erfolg, sonst bleibt der Zustand ambiguous und wird eskaliert.

Darf ich einen Write nach einem 429 automatisch wiederholen?

Laut weclapp ist ein Request mit 429 noch nicht bearbeitet. Wir wiederholen automatisch trotzdem nur Lesezugriffe und lesen bei Writes mit Außenwirkung erst den Zielzustand nach.

Kann ich Aktionen wie createCreditNote mit dryRun testen?

Nein. dryRun gilt nur für generische Writes, Aktionen ignorieren den Parameter und laufen echt. Aktionen testest du nur in einem Testsystem.