TracePass
Loslegen
Pässe

Messwerte erfassen

**Nur für Batteriepässe** (Verordnung (EU) 2023/1542 Art. 77, Anhang XIII Punkt 4 — Nutzungsdaten). Der Pass muss veröffentlicht sein; ein Entwurf oder ausgesetzter Pass gibt 422 `passport_not_active` zurück. Ein Nicht-Batteriepass gibt 422 `not_a_battery` zurück. Senden Sie 1–500 Messwerte pro Aufruf, jeweils als `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` ist ein ISO-8601-Zeitstempel, der nicht in der Zukunft liegen darf; `value` darf serialisiert **maximal 16 KB** groß sein (ein größerer Wert gibt 400 `invalid_value` zurück). Die akzeptierten `fieldKey`s sind die Nutzungsdatenfelder aus Anhang XIII Punkt 4: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`.

POST/api/v1/passports/{id}/measurements
OpenAPI 3.1 herunterladen
POST/api/v1/passports/{id}/measurements

Messwerte erfassen

**Nur für Batteriepässe** (Verordnung (EU) 2023/1542 Art. 77, Anhang XIII Punkt 4 — Nutzungsdaten). Der Pass muss veröffentlicht sein; ein Entwurf oder ausgesetzter Pass gibt 422 `passport_not_active` zurück. Ein Nicht-Batteriepass gibt 422 `not_a_battery` zurück. Senden Sie 1–500 Messwerte pro Aufruf, jeweils als `{ fieldKey, value, measuredAt, externalId?, unit? }` — `measuredAt` ist ein ISO-8601-Zeitstempel, der nicht in der Zukunft liegen darf; `value` darf serialisiert **maximal 16 KB** groß sein (ein größerer Wert gibt 400 `invalid_value` zurück). Die akzeptierten `fieldKey`s sind die Nutzungsdatenfelder aus Anhang XIII Punkt 4: `stateOfHealth`, `stateOfCertifiedEnergy`, `remainingCapacity`, `remainingPowerCapability`, `remainingRoundTripEfficiency`, `evolutionOfSelfDischargeRate`, `currentInternalResistancePack`, `capacityFade`, `powerFade`, `internalResistanceIncrease`, `dynamicRatedCapacity`, `dynamicPowerCapability`, `dynamicInternalResistance`, `dynamicEnergyRoundTripEfficiency`, `dynamicExpectedLifetimeCycles`, `numberOfFullEquivalentChargingCycles`, `numberOfChargingEvents`, `currentStateOfCharge`, `negativeEvents`, `temperatureConditionsHistorical`.

Jeder Messwert wird gespeichert. Der neueste pro Feld (nach `measuredAt`) wird auch zum aktuellen Wert dieses Feldes im Pass und setzt `dynamicDataAsOf`. Ein später eintreffender älterer Messwert wird in der Historie behalten, überschreibt jedoch keinen neueren aktuellen Wert. Die Angabe einer `externalId` macht einen Messwert **idempotent**: eine Wiederholung wird in `duplicates` gezählt, nicht erneut gespeichert oder verrechnet. Der `Idempotency-Key`-Header wird ebenfalls unterstützt — gleicher Schlüssel + gleicher Body replayed die gecachte Antwort für 24 h; gleicher Schlüssel + anderer Body gibt 422 zurück. OAuth-Scope: `passports:write`.

`batteryStatus` ist **kein** Messfeld — Änderungen am Lebenszyklus-Status erfolgen über das Dashboard. Eine zur Wiederverwendung vorbereitete, umgenutzte oder wiederaufgearbeitete Batterie erhält einen neuen Batteriepass, der über `lineage` beim Erstellen des Passes mit dem Original verknüpft ist. Ein Feld, das die Verordnung für die Batteriekategorie ausschließt, gibt 422 `field_not_applicable` zurück (z. B. ist `stateOfCertifiedEnergy` für LMT-Batterien nicht zulässig; die fünf Restenergiedichte-Metriken aus Anhang VII Teil A sind für EV-Batterien nicht zulässig). Eine alternative Adressierungsform gibt es unter `POST /api/v1/passports/by-serial/{serial}/measurements` — gleicher Body, gleiche Antwort. Bei nicht eindeutiger Seriennummer fügen Sie `?gtin=<gtin>` zur Disambiguierung hinzu.

Messwerte zählen gegen das **monatliche** Messwertkontingent des Plans (`maxMeasurementsPerMonth`), nicht gegen das tägliche v1-Schreibbudget. Bezahlte Pläne nehmen Messwerte nach Überschreitung des Kontingents weiterhin kostenlos an und zählen sie; der Free-Plan stoppt bei Erreichen des Kontingents. Das Aufrufen eines Passes wird niemals verrechnet.

Pfad-Parameter

  • iderforderlich

    ObjectId

    Pass-ID.

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

    Optionaler Idempotenz-Schlüssel (UUID v4 oder beliebiger opaker String ≤ 64 Zeichen). Gleicher Schlüssel + gleicher Body replayed die gecachte Antwort für 24 h; gleicher Schlüssel + anderer Body gibt 422 zurück.

Anfrage

curl -sS -X POST \
  https://app.tracepass.eu/api/v1/passports/6650b2c3d4e5f6a7b8c9d0e1/measurements \
  -H "Authorization: Bearer tp_REDACTED_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "measurements": [
      {
        "fieldKey": "stateOfHealth",
        "value": 96.4,
        "measuredAt": "2027-03-01T06:00:00Z",
        "externalId": "bms-7781-2027-03-01"
      },
      {
        "fieldKey": "numberOfFullEquivalentChargingCycles",
        "value": 112,
        "measuredAt": "2027-03-01T06:00:00Z"
      }
    ]
  }'

Antwort

{
  "accepted": 2,
  "storedCount": 2,
  "materializedCount": 2,
  "duplicates": 0,
  "measurementIds": [
    "6750a1b2c3d4e5f6a7b8c9d0",
    "6750a1b2c3d4e5f6a7b8c9d1"
  ]
}

Verwandte Endpoints