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 fieldKeys 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 fieldKeys 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

    string (24 hex chars)

    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