# Einführung

> Was die Integrations-API von BatteryPass leistet, was im Portal bleibt und wo Sie anfangen.

BatteryPass ist eine Plattform für digitale Batteriepässe nach der EU-Batterieverordnung (Verordnung (EU)
2023/1542). Hersteller pflegen Batteriemodelle, Einheiten und deren Daten im BatteryPass-Portal, lassen die
Daten prüfen und veröffentlichen signierte Pässe. Diese Dokumentation beschreibt die **Integrations-API**: den
Teil von BatteryPass, den Ihre eigenen Systeme (ERP, MES, Batteriemanagementsystem, Data Warehouse) mit einem
API-Schlüssel nutzen.

## Was die API abdeckt

| Bereich                                     | Mit Schlüssel                                                                                                                                        | Scope               |
| ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Batteriemodelle, Modellversionen, Einheiten | Lesen, Einheiten auch als Tabellenexport                                                                                                             | `read`              |
| Werte                                       | Lesen mit Herkunft (Quelle, Prüfstatus, Revisionen, belegende Dokumente) und Vollständigkeit                                                         | `read`              |
| Nachweise und Standorte                     | Metadaten von Dokumenten lesen, Dateien herunterladen, Produktionsstandorte auflisten                                                                | `read`              |
| Pässe                                       | Aktuellen Stand, veröffentlichte Versionen, Unterschiede zwischen Versionen, Exporte (BatteryPass-JSON, PDF, QR-Code) und Registrierungsstatus lesen | `read`              |
| Feldregister                                | Version, Schema und Status lesen                                                                                                                     | `read`              |
| Zustandsdaten                               | Lesen und Messwerte wie Ladezustand oder Kapazitätsverlust melden                                                                                    | `read`, `condition` |
| Lebenszyklusereignisse                      | Lesen und Ereignisse wie eine Inspektion oder Reparatur melden                                                                                       | `read`, `condition` |
| Änderungen                                  | Verfolgen, was sich in der Organisation geändert hat (Änderungsfeed zum Abfragen)                                                                    | `read`              |
| Importe                                     | Tabellenimporte von Einheiten bereitstellen: hochladen, zuordnen, prüfen; Mitglieder übernehmen und geben sie frei                                   | `import`            |
| Öffentliche Pässe                           | Öffentliche Stufe lesen, Signaturen prüfen, öffentliche Dokumente laden                                                                              | ohne Schlüssel      |

Jede Operation mit Parametern, Antworten und benötigtem Scope finden Sie in der
[API-Referenz](https://passport.kabin.sh/docs/de/api-reference).

## Was im Portal bleibt

- **Deklarierte Daten** (Modelle, Einheiten, Werte, Dokumente) erfassen Mitglieder im Portal oder importieren
  sie dort aus einer Tabelle. Die API legt keine deklarierten Daten an und ändert sie nicht.
- **Prüfung, Freigabe und Veröffentlichung** bleiben bei den Mitgliedern. Standardmäßig gilt das
  Vier-Augen-Prinzip: Wer einen Wert erfasst hat, kann ihn nicht selbst freigeben.
- **Mitglieder, API-Schlüssel und Einstellungen der Organisation** verwalten Eigentümer und Administration im
  Portal.

Eine Ausnahme vom Prüfschritt sind Zustandsdaten, die ein Schlüssel meldet: Sie werden als freigegebene
Messung mit Quelle und Messzeitpunkt gespeichert, und ein veröffentlichter Pass wird so aktualisiert, wie es
die Einstellungen Ihrer Organisation vorsehen. Mehr dazu unter
[Zustandsdaten und Lebenszyklus](https://passport.kabin.sh/docs/de/concepts/condition-and-lifecycle).

> [!NOTE]
> **EU-Register**
>
> Das EU-Register für digitale Produktpässe bietet Wirtschaftsakteuren noch keine Schnittstelle. BatteryPass
> übermittelt deshalb bisher nichts dorthin, und `getRegistrySubmissionStatus` meldet `not_available`.

## Wie die Teile zusammenspielen

```mermaid
flowchart LR
  Portal["Portal: Mitglieder erfassen, prüfen, veröffentlichen"] --> BP[("BatteryPass")]
  Import["Tabellenimport im Portal"] --> BP
  BP -- "API-Schlüssel, Scope read" --> ERP["Ihre Systeme: ERP, Data Warehouse"]
  BMS["BMS oder System eines Servicepartners"] -- "API-Schlüssel, Scope condition" --> BP
  BP --> Public["Öffentlicher Pass: QR-Code, Seite, JSON, ohne Schlüssel"]
```

## Hier anfangen

[**Schnellstart**](https://passport.kabin.sh/docs/de/quickstart): Schlüssel erstellen, ersten Aufruf senden und einen Pass lesen.

[**Authentifizierung**](https://passport.kabin.sh/docs/de/authentication): Organisationsschlüssel, Scopes und was ein Schlüssel darf.

[**Anleitungen**](https://passport.kabin.sh/docs/de/guides): Schritt für Schritt durch typische Integrationsaufgaben.

[**Rezepte**](https://passport.kabin.sh/docs/de/recipes): Kurze, vollständige Programme zum Kopieren und Anpassen.

[**API-Referenz**](https://passport.kabin.sh/docs/de/api-reference): Jede Operation des veröffentlichten Vertrags, mit Playground.