Einzelnes Feld in einem Pass aktualisieren

Patcht ein einzelnes Feld auf einem Pass. Der Wert wird gegen den Feldschlüssel validiert (muss in der Vorlage des Passes vorhanden sein) und mit einem Audit-Trail-Eintrag persistiert, der die Zugangsdaten nennt (via API key <prefix> oder via OAuth app <client>) und, wenn der Header X-Source gesetzt ist, den aufrufenden Client, z. B. (mcp). Bevorzugen Sie das gegenüber dem Schreiben der gesamten fields-Karte, wenn Sie nur eine Zahl aktualisieren müssen — das ist ein kleinerer Schreibvorgang und der Audit-Eintrag ist das, was Dashboard-Prüfer sehen.

Der Status richtet sich danach, wer schreibt, nicht nach dem Kanal. Ein API-Schlüssel schreibt status: "approved" (er ist ein unternehmensweites Dienstkonto). Ein OAuth-Token schreibt mit den Dashboard-Rechten seines Nutzers, eine Rolle unterhalb von Admin landet also in pending_review. Ein mit source: "ai_suggested" gesendeter Wert landet immer in pending_review und wird mit 400 abgelehnt, wenn das Feld nur vom Wirtschaftsakteur erklärt oder gemessen werden darf (z. B. stateOfHealth einer Batterie); senden Sie ihn mit einer anderen Quelle, wenn Ihre Organisation diese Angabe macht. ai_approved und system setzt TracePass; als Anfragewerte werden sie abgelehnt.

Eine alternative Adressierungsform existiert unter PATCH /api/v1/passports/by-serial/{serial}/fields/{key} — gleicher Body, gleiche Antwort, nützlich wenn Ihr ERP nur die kundenseitige Seriennummer kennt. Zählt als ein v1-Schreibvorgang. Unterstützt Idempotency-Key.

No-op (200 unchanged: true): Wenn der eingehende Wert, der berechnete Status und das Quell-Locale identisch mit dem gespeicherten Zustand sind, überspringt der Endpunkt den Schreibvorgang vollständig — kein Versionsincrement, kein Audit-Eintrag, kein Snapshot — und gibt 200 mit unchanged: true zusammen mit dem aktuellen Feld und der aktuellen Version zurück. Die Antwortstruktur ist dieselbe wie bei einem echten Schreibvorgang; prüfen Sie den Schlüssel unchanged, um beide Fälle zu unterscheiden.

Pflichtfeld-Schutz (400): Nach der Veröffentlichung eines Passes wird das Senden von null oder einem leeren String für ein Feld, das die Verordnung für die Kategorie des Passes vorschreibt, mit required_field_empty (HTTP 400) abgelehnt. Das Array fields im Antwort-Body nennt jeden betroffenen Schlüssel. Entwürfe bleiben frei bearbeitbar.

Größengrenzen (400 / 413): Ein Wert darf höchstens 1.000 Array-Elemente (verschachtelte Arrays eingeschlossen), 20.000 Zeichen in jedem einzelnen String (jede Sprache eines übersetzbaren Werts zählt für sich) und insgesamt 256 KB enthalten, bei höchstens 8 Verschachtelungsebenen. Ein größerer Wert wird mit field_value_too_large abgelehnt; die Antwort nennt das Feld, die Art der Grenze (items, characters, bytes oder depth) und den Grenzwert. Ein Request-Body, dessen angegebene Größe 1 MB übersteigt, wird mit 413 payload_too_large abgelehnt.

Schreibsperre (409): Nach der ersten Veröffentlichung eines Passes können Identitätsfelder (gtin, serialNumber, uniqueProductIdentifier, globalUniqueProductIdentifier, productIdentifier, identifierStandard, batteryUniqueIdentifier, batteryIdDmcCode, batteryPassportIdentifier) nicht mehr geändert werden, wenn sie bereits einen approved-Wert enthalten — die Antwort ist 409 identifier_locked mit den Feldnamen in keys. Ein pending_review-Wert kann korrigiert werden; ein leeres Feld kann befüllt werden. Das Zurückschreiben desselben Werts (einschließlich einer GTIN mit oder ohne führende Null auf 14 Stellen aufgefüllt oder bei übereinstimmendem Wert ohne Leerzeichen) wird angenommen, wenn der Wert dabei freigegeben bleibt, wie bei einem API-Schlüssel. Ein Schreibzugriff mit source: "ai_suggested" oder von einem OAuth-Benutzer unterhalb von admin landet als pending_review und wird abgelehnt. Ein Schreibzugriff auf einen archivierten Pass gibt 409 passport_archived zurück. Ein konkurrierender Schreibzugriff gibt 409 concurrent_update zurück — Pass neu laden und erneut versuchen. Suspendierte und abgelaufene Pässe bleiben editierbar.