Lebenszyklus-Ereignisse erfassen

Ein Lebenszyklus-Ereignis hält fest, dass mit einer Batterie etwas geschehen ist: Sie wurde in Betrieb genommen, geprüft, repariert, ein Bauteil wurde getauscht. Ereignisse sind Aufzeichnungen und ändern keine Daten der Einheit. Messwerte melden Sie mit updateCondition. Hintergrund: Zustand und Lebenszyklus.

EreignisartenLink zum Abschnitt kopieren

ReportedEventType im Vertrag nennt zusätzlich condition_update, doch createLifecycleEvent lehnt diesen Typ mit 400 validation_error auf type ab: Solche Ereignisse schreibt updateCondition. Die Arten des zweiten Lebens (repurposed, reused, remanufactured) erscheinen im Lebenszyklus, wenn ein Mitglied im Portal eine Einheit für das zweite Leben anlegt; über die API lassen sie sich nicht erfassen.

Ein Ereignis erfassenLink zum Abschnitt kopieren

curl -sS -X POST "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/lifecycle-events" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "inspection",
    "occurred_on": "2026-10-22",
    "description": "Jahresinspektion: Gehäuse, Steckverbinder und BMS-Protokoll geprüft, ohne Befund.",
    "evidence_ids": ["0192f7aa-1c2d-7e3f-8a4b-5c6d7e8f9a0b"]
  }'

{
  "id": "0192f8c2-4d5e-7f60-8a71-b2c3d4e5f6a7",
  "battery_id": "0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f",
  "type": "inspection",
  "occurred_on": "2026-10-22",
  "description": "Jahresinspektion: Gehäuse, Steckverbinder und BMS-Protokoll geprüft, ohne Befund.",
  "source": "api",
  "api_key": { "id": "0192e4c7-8b9a-7c6d-8e5f-4a3b2c1d0e9f", "name": "Servicesystem Nord" },
  "field_keys": [],
  "evidence": [
    {
      "id": "0192f7aa-1c2d-7e3f-8a4b-5c6d7e8f9a0b",
      "kind": "diagnostic_report",
      "title": "Prüfprotokoll 2026",
      "filename": "pruefprotokoll-2026-10-22.pdf",
      "access_tier": "internal",
      "revision": 1,
      "superseded": false
    }
  ],
  "created_at": "2026-10-24T08:15:02Z"
}

Keine automatische DuplikaterkennungLink zum Abschnitt kopieren

BatteryPass erkennt nicht, wenn dasselbe Ereignis zweimal ankommt: Jede erfolgreiche Anfrage legt ein Ereignis an, und createLifecycleEvent kennt keinen Idempotenzschlüssel. Das ist wichtig, wenn eine Anfrage in ein Timeout läuft und Sie nicht wissen, ob sie angekommen ist:

• Wiederholen Sie einen POST nach einem Netzwerkfehler, einem Timeout oder einem 5xx nicht automatisch.
• Bevor Sie es erneut senden, suchen Sie Ihr Ereignis (gleicher type, gleiches occurred_on und gleiche description, source: api) in listLifecycleEvents. Die Liste ist nach occurred_on sortiert, das neueste zuerst; ein rückdatiertes Ereignis steht also nicht unbedingt auf der ersten Seite. Lesen Sie mit next_cursor weiter, bis die Seite Ereignisse enthält, die vor Ihrem lagen (das Beispiel für Wiederholungen macht genau das).
• Speichern Sie die zurückgegebene id in Ihrem System, damit Sie wissen, welche Ereignisse bereits erfasst sind.

Ein 429 rate_limited dürfen Sie nach Retry-After gefahrlos wiederholen: Die Anfrage wurde abgelehnt, bevor etwas gespeichert wurde. Mehr dazu unter Wiederholungen und Idempotenz.

Den Lebenszyklus lesenLink zum Abschnitt kopieren

curl -sS "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/lifecycle-events?limit=50" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY"

Die Antwort ist eine Seite {items, next_cursor}, das jüngste occurred_on zuerst; ältere Ereignisse folgen über next_cursor (Paginierung). Die Liste enthält jedes Ereignis der Einheit, gleich wer es gemeldet hat: Mitglieder, Servicepartner über ihre Links, Zustandsupdates (type: condition_update mit den aktualisierten field_keys), Schlüssel und das System. Beim zweiten Leben nennen related_battery_id und related_serial_number die jeweils andere Einheit.

FehlerLink zum Abschnitt kopieren