Rücksendungen und Reparaturen als Lebenszyklus-Ereignisse
Abgeschlossene Service-, Reparatur- und Retourenaufträge im ERP werden Lebenszyklus-Ereignisse der Einheit, ohne Kundendaten und ohne Duplikate.
Kommt eine Batterie zur Prüfung, Reparatur oder für einen Komponententausch zurück, schließt das ERP oder sein
Servicemodul einen Auftrag ab. In diesem Ablauf macht die Middleware aus dem abgeschlossenen Auftrag ein
Lebenszyklus-Ereignis der Einheit, mit
createLifecycleEvent. Ereignisse sind Aufzeichnungen:
Sie erscheinen in der Historie der Einheit und ändern keine Passdaten. Wie Ereignisse funktionieren, beschreibt
Lebenszyklus-Ereignisse erfassen.
sequenceDiagram participant ERP participant MW as Middleware participant BP as BatteryPass-API participant M as Mitglied im Portal ERP->>ERP: Auftrag abschließen, Outbox-Zeile schreiben MW->>ERP: Outbox-Zeile lesen (Seriennummer, Art der Arbeit, Datum) MW->>MW: Auftrag schon gemeldet? Dann aufhören MW->>BP: listBatteries mit serial_prefix (Scope read) MW->>BP: createLifecycleEvent (Scope condition) BP-->>MW: 201 Ereignis MW->>MW: Auftrag und Ereignis-ID merken M->>BP: Historie prüfen, bei Bedarf ein zweites Leben anlegen
Auslöser: Ein Service-, Reparatur- oder Retourenauftrag wird im ERP abgeschlossen.
Scopes des Schlüssels: readcondition
| # | Wer | Was | Operation |
|---|---|---|---|
| 1 | ERP | Schließt den Auftrag mit Seriennummer und Art der Arbeit ab und hält die Änderung in der Outbox fest. | |
| 2 | Middleware | Findet die Einheit über ihre Seriennummer. | listBatteries read |
| 3 | Middleware | Legt das Ereignis an (zum Beispiel repair, inspection oder component_replaced) mit Datum und kurzer Beschreibung. | createLifecycleEvent condition |
| 4 | Mitglied im Portal | Prüft die Historie im Portal; ein zweites Leben (Umwidmung, Wiederaufbereitung) legt ein Mitglied als neue Einheit an. |
Sicherheit
- Ereignisse sind Aufzeichnungen und ändern keine Passdaten; der Schlüssel braucht nur condition und read.
- Die Middleware merkt sich die Auftragsnummer, für die sie ein Ereignis angelegt hat, und legt es kein zweites Mal an.
Datenminimierung
- Keine Kundennamen, Adressen, Auftragsnummern oder Fehlerbeschreibungen mit Personenbezug in der Beschreibung; die Seriennummer verbindet Ereignis und Auftrag.
Auftrag einem Ereignistyp zuordnen
| ERP-Auftrag | type |
|---|---|
| Prüfung oder Diagnose ohne Arbeit | inspection |
| Reparatur | repair |
| Ein Modul, eine Zelle oder ein Teil getauscht | component_replaced |
| Batterie zur Entsorgung zurückgenommen | waste |
| Batterie recycelt | recycled |
| Alles andere, das festgehalten werden soll | custom |
Im Service gemessene Zustandswerte gehören nicht ins Ereignis: Melden Sie sie mit
updateCondition, das sein eigenes Ereignis
condition_update anlegt. Eine umgewidmete oder wiederaufbereitete Batterie bekommt eine neue Einheit mit eigenem
Pass, die ein Mitglied im Portal anlegt (zweites Leben).
Ereignis anlegen
occurred_on ist der Tag der Arbeit, zwischen Herstelldatum und heute. description nimmt höchstens 2 000 Zeichen;
evidence_ids kann bis zu 20 Dokumente Ihrer Nachweisbibliothek nennen, etwa ein Reparaturprotokoll.
curl -sS -X POST "$BATTERYPASS_URL/api/v1/batteries/0192a3f0-5b7c-7d21-8e4f-6a2b9c1d3e5f/lifecycle-events" \
-H "Authorization: Bearer $BATTERYPASS_SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{"type": "component_replaced", "occurred_on": "2026-10-21", "description": "Modul 3 getauscht (Servicecode R-12)"}'Das Ereignis hat die Quelle api und nennt den Schlüssel in api_key; das Audit-Log nennt den Schlüssel als
Handelnden.
Keine Duplikate
createLifecycleEvent ist nicht idempotent: Jeder erfolgreiche Aufruf legt ein neues Ereignis an. Führen Sie eine
Tabelle der gemeldeten Aufträge (Auftragsnummer, Ereignis-ID in BatteryPass). Sehen Sie nach einer
Zeitüberschreitung in listLifecycleEvents der Einheit
nach (dafür braucht es read), bevor Sie erneut senden: Ein Ereignis desselben Typs und Tages mit Ihrem Servicecode
heißt, dass der erste Aufruf durchging.
Was nie fließt
Keine Namen, Adressen oder Kontaktdaten von Kundinnen und Kunden, keine Auftrags- oder Rechnungsnummern, keine
Namen von Technikern und keine Fehlerbeschreibungen, die Personen erkennen lassen. Die Seriennummer verbindet das
Ereignis mit dem Auftrag in Ihrem ERP. Bauen Sie die description wie oben aus festen Codes, nicht aus dem
Freitext des Auftrags.
Fehlerbehandlung
| Antwort | Bedeutung | Was tun |
|---|---|---|
400 validation_error | Unbekannter type (auch condition_update, das nur updateCondition anlegt), occurred_on vor der Herstellung oder in der Zukunft, ein Dokument, das nicht Ihnen gehört | Zuordnung korrigieren; nicht unverändert wiederholen. |
401 unauthenticated | Schlüssel fehlt, ist unbekannt oder widerrufen | Geheimnis prüfen; Alarm auslösen. |
403 forbidden | Dem Schlüssel fehlt der Scope condition | Den Service-Schlüssel verwenden. |
404 not_found | Die Einheit gehört nicht zu Ihrer Organisation | Seriennummer prüfen. |
409 conflict | Das Modell der Einheit ist archiviert | Ereignis im Portal erfassen oder gar nicht. |
429 rate_limited | Zu viele Anfragen | Retry-After Sekunden warten. |
5xx, Zeitüberschreitung | Ergebnis unbekannt | Erst listLifecycleEvents prüfen, dann wiederholen. |
Zustandsdaten aus BMS und Service
Ein Batteriemanagementsystem oder ein Servicewerkzeug meldet Messwerte je Einheit mit updateCondition; neuere Messungen werden angenommen, ältere übersprungen, und der Pass wird nach Ihrer Richtlinie neu veröffentlicht.
Produktänderung
Eine Änderung am Produktstamm im ERP benachrichtigt die verantwortliche Person, die in BatteryPass eine neue Modellversion anlegt; deklarierte Daten werden nie automatisch geschrieben.