TracePass
Loslegen
Pässe

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.

PATCH/api/v1/passports/{id}/fields/{key}
OpenAPI 3.1 herunterladen
PATCH/api/v1/passports/{id}/fields/{key}

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.

Pfad-Parameter

  • iderforderlich

    ObjectId

    Pass-ID. Adressierung per Seriennummer: PATCH /api/v1/passports/by-serial/{serial}/fields/{key}.

    e.g. 6650b2c3d4e5f6a7b8c9d0e1

  • keyerforderlich

    string

    Feldschlüssel (camelCase) wie in der Vorlage des Passes definiert — z. B. `nominalVoltage`, `batteryChemistry`, `recycledContentCobalt`. 400, wenn der Schlüssel nicht in der Vorlage existiert.

    e.g. ratedCapacity

Header

  • Authorizationerforderlich

    string

    `Bearer <token>` — entweder ein `tp_` API-Schlüssel (Developer → API Keys; am einfachsten, für Server-zu-Server) oder ein OAuth-2.0-Access-Token (Developer → OAuth Apps; für nutzerautorisierte Apps, scoped und widerrufbar). Die Authentication-Seite enthält den vollständigen OAuth-Flow und die Scope-Liste.

    e.g. Bearer tp_REDACTED_xxxxxxxxxxxx

  • Idempotency-Key

    string

    UUID v4 pro logischer Operation.

Body-Felder

  • valueerforderlich

    string | number | boolean | array | object

    Neuer Wert. Die Plattform formatiert keine Strings in Zahlen um — senden Sie den Wert im erwarteten Feldtyp.

    e.g. 5.24

  • source

    enum

    Markiert den Ursprung des Werts. Einer von: `manual`, `ai_suggested`, `reference_db`, `supplier`. Standard `manual`. `ai_suggested` landet in der Prüf-Queue; die anderen werden mit den Rechten Ihrer Zugangsdaten geschrieben. `ai_approved` und `system` setzt TracePass; hier werden sie abgelehnt.

  • sourceLocale

    string (ISO 639-1)

    Locale des Werts (eines der 24 EU-Locales). Steuert Übersetzungsrichtung + Sprachauflösung des öffentlichen Viewers. Standardmäßig der `sourceLocale` des Passes, wenn ausgelassen.

Anfrage

curl -sS -X PATCH \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/fields/ratedCapacity \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "value": 5.24 }'

Antwort

{
  "field": {
    "value": 5.24,
    "source": "manual",
    "status": "approved",
    "accessLevel": "public",
    "sourceLocale": "en",
    "lastUpdatedAt": "2026-05-09T10:30:00.000Z",
    "lastUpdatedBy": "api_key:tp_89b2482d"
  },
  "version": 4
}

Verwandte Endpoints