# BatteryPass Entwicklerdokumentation

> Integrations-API von BatteryPass für digitale EU-Batteriepässe: mit einem API-Schlüssel der Organisation Modelle, Einheiten, Werte, Pässe und Exporte lesen, Änderungen verfolgen, Tabellenimporte bereitstellen, Zustandsdaten und Lebenszyklus-Ereignisse melden und öffentliche Pässe prüfen.

Jeder Link führt zur Markdown-Fassung einer Seite. Diese Übersicht ist auf Deutsch; die englische steht unter https://passport.kabin.sh/docs/en/llms.txt.

## Erste Schritte

- [Einführung](https://passport.kabin.sh/docs/de.md): Was die Integrations-API von BatteryPass leistet, was im Portal bleibt und wo Sie anfangen.
- [Schnellstart](https://passport.kabin.sh/docs/de/quickstart.md): In wenigen Minuten einen API-Schlüssel erstellen, den ersten Aufruf senden und einen Pass lesen.
- [Authentifizierung](https://passport.kabin.sh/docs/de/authentication.md): API-Schlüssel der Organisation, ihre Scopes, was ein Schlüssel darf und wie Sie ihn rotieren.
- [Fehler](https://passport.kabin.sh/docs/de/errors.md): Wie die API Fehler als RFC 9457 Problem Details mit stabilen Codes und einer Request-ID meldet.
- [Paginierung](https://passport.kabin.sh/docs/de/pagination.md): Lange Listen seitenweise mit `limit` und einem undurchsichtigen `cursor` lesen.
- [Ratenlimits](https://passport.kabin.sh/docs/de/rate-limits.md): Wie viele Anfragen BatteryPass annimmt und wie Sie nach einem 429 zurückhaltend wiederholen.
- [Wiederholungen und Idempotenz](https://passport.kabin.sh/docs/de/idempotency.md): Welche Anfragen Sie nach einem Timeout gefahrlos wiederholen können und wie Sie doppelte Ereignisse vermeiden.
- [Stabilität und Versionierung](https://passport.kabin.sh/docs/de/versioning.md): Worauf sich Integrationen verlassen können, wie sich die API ändert und wo Sie den Vertrag laden.
- [Umgebungen und Basis-URL](https://passport.kabin.sh/docs/de/environments.md): Wo die API Ihrer Organisation liegt, welche Adressen sie bedient und wie Sie gefahrlos testen.

## Erste Schritte: Konzepte

- [Batteriemodelle, Versionen und Einheiten](https://passport.kabin.sh/docs/de/concepts/battery-models.md): Wie BatteryPass Produkt, technische Stände und einzelne Batterien trennt und wo welcher Wert gespeichert ist.
- [Pässe und Versionen](https://passport.kabin.sh/docs/de/concepts/passports.md): Der Pass einer Einheit, seine Status, seine signierten und unveränderlichen Versionen, die Unterschiede zwischen ihnen und die Exporte.
- [Zugriffsstufen](https://passport.kabin.sh/docs/de/concepts/access-tiers.md): Welche Passdaten öffentlich sind, welche eingeschränkt, und wie BatteryPass eingeschränkte Daten aus öffentlichen Antworten heraushält.
- [Herkunft und Freigabe](https://passport.kabin.sh/docs/de/concepts/provenance-and-review.md): Jeder Wert behält Quelle, Urheber, Zeitpunkt und Nachweise und wird abgelöst statt überschrieben; deklarierte Daten werden geprüft, bevor sie in einen Pass gelangen, von einer zweiten Person, wenn die Organisation das Vier-Augen-Prinzip nutzt.
- [Zustandsdaten und Lebenszyklus-Ereignisse](https://passport.kabin.sh/docs/de/concepts/condition-and-lifecycle.md): Wie gemessene Zustandsdaten ohne Prüfschritt in einen Pass gelangen, wie die Neuveröffentlichung geregelt ist und was Lebenszyklus-Ereignisse festhalten.
- [GS1 Digital Link und Resolver](https://passport.kabin.sh/docs/de/concepts/digital-link.md): Der Link in jedem QR-Code und wie der Resolver Browser zur öffentlichen Seite und Maschinen zum öffentlichen JSON leitet.
- [Signaturen](https://passport.kabin.sh/docs/de/concepts/signatures.md): Was BatteryPass in jeder Passversion signiert, wie Hash und Ed25519-Signatur entstehen und wie Sie sie mit den veröffentlichten Schlüsseln prüfen.

## Erste Schritte: Allgemeines

- [Sicherheit und Datenschutz](https://passport.kabin.sh/docs/de/general/security.md): Wie BatteryPass den API-Zugang und die Passdaten schützt und was Ihre Integration tun und vermeiden sollte.
- [Support](https://passport.kabin.sh/docs/de/general/support.md): Wie Sie Hilfe zu einer Integration bekommen, was in eine Anfrage gehört und wo der Stand der Funktionen dokumentiert ist.
- [Glossar](https://passport.kabin.sh/docs/de/general/glossary.md): Die Fach- und API-Begriffe dieser Dokumentation, auf Deutsch und Englisch.

## Anleitungen

- [Anleitungen](https://passport.kabin.sh/docs/de/guides.md): Schritt-für-Schritt-Anleitungen für die häufigsten Aufgaben einer Integration, mit Anfragen, Antworten und den wichtigen Fehlerfällen.
- [Passsignatur offline prüfen](https://passport.kabin.sh/docs/de/guides/verify-signature.md): Prüfen Sie allein mit dem öffentlichen JSON und den veröffentlichten Schlüsseln, dass die öffentlichen Daten eines Passes genau so signiert wurden.
- [Zustandsdaten aus einem Batteriemanagementsystem senden](https://passport.kabin.sh/docs/de/guides/push-condition-data.md): Melden Sie Messwerte wie Ladezustand oder Vollzyklen mit updateCondition und lesen Sie, was übernommen, übersprungen und neu veröffentlicht wurde.
- [Lebenszyklus-Ereignisse erfassen](https://passport.kabin.sh/docs/de/guides/record-lifecycle-events.md): Melden Sie Inspektionen, Reparaturen und andere Ereignisse im Leben einer Einheit mit createLifecycleEvent und lesen Sie den Lebenszyklus mit listLifecycleEvents.
- [Pässe exportieren](https://passport.kabin.sh/docs/de/guides/export-passports.md): Laden Sie BatteryPass-JSON, PDF und QR-Code einer Passversion sowie die Einheiten Ihrer Organisation als Tabelle herunter.
- [Einheiten in Ihr System übernehmen](https://passport.kabin.sh/docs/de/guides/sync-units.md): Übernehmen Sie die Einheiten Ihrer Organisation mit Cursor-Paginierung in ERP, MES oder Datenbank, setzen Sie nach einer Unterbrechung fort und erkennen Sie Änderungen.
- [Fehler behandeln und Anfragen wiederholen](https://passport.kabin.sh/docs/de/guides/handle-errors.md): Entscheiden Sie, welche Antworten Sie wiederholen und welche Sie beheben, warten Sie mit Backoff und Jitter, beachten Sie Retry-After und protokollieren Sie die request_id.
- [QR-Code oder GS1 Digital Link auflösen](https://passport.kabin.sh/docs/de/guides/resolve-digital-link.md): Vom gescannten GS1 Digital Link zum öffentlichen Pass-JSON, über den Resolver oder über GTIN und Seriennummer.
- [API-Schlüssel sicher verwalten](https://passport.kabin.sh/docs/de/guides/secure-key-handling.md): Wo Schlüssel hingehören, welcher Scope für welches System, wie Sie ohne Ausfall wechseln und was zu tun ist, wenn ein Schlüssel bekannt wird.
- [KI-Werkzeuge über MCP anbinden](https://passport.kabin.sh/docs/de/guides/mcp.md): Nutzen Sie die Integrations-API von BatteryPass aus Claude Code, Cursor, VS Code und anderen MCP-Clients mit einem API-Schlüssel Ihrer Organisation.

## Rezepte

- [Rezepte](https://passport.kabin.sh/docs/de/recipes.md): Kurze, lauffähige Programme für häufige Integrationsaufgaben, jeweils in cURL, TypeScript, Python und Go.
- [Nächtlicher Zustandsdaten-Push](https://passport.kabin.sh/docs/de/recipes/nightly-condition-push.md): Ein geplanter Job, der die Messwerte der letzten Nacht aus Ihrer eigenen Quelle liest und je Einheit ein updateCondition sendet, mit Backoff bei 429.
- [QR-Etiketten für eine Produktionscharge](https://passport.kabin.sh/docs/de/recipes/qr-labels-for-a-batch.md): Listen Sie die veröffentlichten Einheiten einer Charge über das Seriennummernpräfix und speichern Sie den QR-Code jeder Einheit als SVG-Datei für den Etikettendruck.
- [Data-Warehouse-Abgleich](https://passport.kabin.sh/docs/de/recipes/data-warehouse-sync.md): Gehen Sie alle Einheiten und ihre aktuellen Werte seitenweise durch und schreiben Sie je Einheit eine JSON-Zeile, bereit zum Laden in ein Data Warehouse.
- [Signaturen mehrerer Pässe prüfen](https://passport.kabin.sh/docs/de/recipes/verify-signatures.md): Prüfen Sie die Ed25519-Signaturen einer Liste öffentlicher Pässe offline, laden Sie das Schlüsselset nur einmal und geben Sie je Pass ein Ergebnis aus.
- [Veröffentlichte Pässe eines Modells](https://passport.kabin.sh/docs/de/recipes/published-passports-of-a-model.md): Listen Sie jede Einheit eines Batteriemodells mit veröffentlichtem Pass auf und geben Sie Pass-ID, aktuelle Version und öffentlichen Link als CSV aus.

## Integrationen

- [Ihr ERP sicher anbinden](https://passport.kabin.sh/docs/de/integrations.md): Wie ein ERP, seine Middleware und BatteryPass zusammenarbeiten, wer was tut und was Ihre Systeme nie verlässt.
- [Das Sicherheitsmodell einer ERP-Integration](https://passport.kabin.sh/docs/de/integrations/security.md): Schlüssel und Scopes, Geheimnisse und Rotation, Transport, sichere Wiederholungen, Outbox, dünne Ereignisse, veraltete Schreibvorgänge, Datenminimierung, Audit-Trail und die OWASP API Top 10.
- [iPaaS und Middleware](https://passport.kabin.sh/docs/de/integrations/ipaas.md): Die BatteryPass-API aus n8n, Make, Power Automate, MuleSoft, Boomi, Workato, Zapier und SAP Integration Suite mit einem Schlüssel aus dem Geheimnisspeicher der Plattform aufrufen und den Änderungsfeed abfragen.
- [Wie BatteryPass zu Standards für den Batteriepass steht](https://passport.kabin.sh/docs/de/integrations/standards.md): DIN DKE SPEC 99100, die IDTA-Teilmodelle des digitalen Batteriepasses, Catena-X CX-0160 und das BatteryPass-Datenmodell, und was BatteryPass heute abbildet und was nicht.

## Integrationen: Abläufe

- [Einheiten aus der Fertigung](https://passport.kabin.sh/docs/de/integrations/workflows/units-from-production.md): Seriennummern fertiger Batterien mit einem Schlüssel mit Scope import als Import bereitstellen; Mitglieder prüfen, übernehmen, geben frei und veröffentlichen im Portal.
- [Pass-Links zurück ins ERP](https://passport.kabin.sh/docs/de/integrations/workflows/passport-links-to-erp.md): Mit einem Schlüssel mit Scope read dem Änderungsfeed folgen und GS1 Digital Link, Passstatus und QR-Code jeder Einheit an ihrem Seriennummernsatz im ERP speichern.
- [Zustandsdaten aus BMS und Service](https://passport.kabin.sh/docs/de/integrations/workflows/condition-from-bms.md): 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.
- [Rücksendungen und Reparaturen als Lebenszyklus-Ereignisse](https://passport.kabin.sh/docs/de/integrations/workflows/returns-and-repairs.md): Abgeschlossene Service-, Reparatur- und Retourenaufträge im ERP werden Lebenszyklus-Ereignisse der Einheit, ohne Kundendaten und ohne Duplikate.
- [Produktänderung führt zu neuer Modellversion](https://passport.kabin.sh/docs/de/integrations/workflows/product-change.md): Eine Änderung am Produktstamm im ERP benachrichtigt die verantwortliche Person, die in BatteryPass eine neue Modellversion anlegt; deklarierte Daten werden nie automatisch geschrieben.

## Integrationen: ERP-Systeme

- [abas ERP](https://passport.kabin.sh/docs/de/integrations/erp/abas-erp.md): Was über die Anbindung von abas ERP an BatteryPass bekannt ist und was noch zu klären ist.
- [Microsoft Dynamics 365 Business Central](https://passport.kabin.sh/docs/de/integrations/erp/dynamics-365-business-central.md): Wie Business Central über seine API und eine eigene API-Seite Seriennummern an BatteryPass übergibt.
- [Microsoft Dynamics 365 Finance und Supply Chain Management](https://passport.kabin.sh/docs/de/integrations/erp/dynamics-365-finance-operations.md): Wie Dynamics 365 Finance und Supply Chain Management über Datenentitäten und Business Events mit BatteryPass zusammenarbeitet.
- [Microsoft Dynamics NAV 2018](https://passport.kabin.sh/docs/de/integrations/erp/dynamics-nav-2018.md): Wie Dynamics NAV 2018 bis zum Umstieg Seriennummern liefern kann und warum neue Integrationen auf Business Central zielen.
- [Epicor Kinetic](https://passport.kabin.sh/docs/de/integrations/erp/epicor-kinetic.md): Wie Epicor Kinetic über die REST-API v2 Seriennummern an BatteryPass liefern könnte.
- [IFS Cloud](https://passport.kabin.sh/docs/de/integrations/erp/ifs-cloud.md): Wie IFS Cloud über seine OData-Projektionen Seriennummern an BatteryPass liefern könnte.
- [Infor CloudSuite (M3, LN)](https://passport.kabin.sh/docs/de/integrations/erp/infor-cloudsuite.md): Wie Infor M3 und Infor LN über das ION API Gateway BatteryPass erreichen.
- [Odoo](https://passport.kabin.sh/docs/de/integrations/erp/odoo.md): Wie Odoo 19 über die JSON-2-API Los- und Seriennummern an BatteryPass übergibt.
- [Oracle Fusion Cloud Supply Chain Management](https://passport.kabin.sh/docs/de/integrations/erp/oracle-fusion-scm.md): Wie Oracle Fusion Cloud SCM Seriennummern von Arbeitsaufträgen über seine REST-API und Oracle Integration an BatteryPass gibt.
- [Oracle NetSuite](https://passport.kabin.sh/docs/de/integrations/erp/oracle-netsuite.md): Wie Oracle NetSuite über SuiteTalk REST und SuiteQL Inventarnummern an BatteryPass übergibt.
- [proALPHA ERP](https://passport.kabin.sh/docs/de/integrations/erp/proalpha.md): proALPHA mit einem Dateiexport an BatteryPass anbinden, bis eine Schnittstelle bestätigt ist.
- [Sage X3](https://passport.kabin.sh/docs/de/integrations/erp/sage-x3.md): Was über die Anbindung von Sage X3 an BatteryPass bekannt ist und was noch zu klären ist.
- [SAP Business One](https://passport.kabin.sh/docs/de/integrations/erp/sap-business-one.md): Wie SAP Business One über den Service Layer Seriennummern an BatteryPass liefert.
- [SAP S/4HANA Cloud Public Edition](https://passport.kabin.sh/docs/de/integrations/erp/sap-s4hana-cloud.md): Wie SAP S/4HANA Cloud Public Edition Seriennummern an BatteryPass übergibt und Pass-Links zurückbekommt.
- [SAP S/4HANA (On-Premise und Private Edition)](https://passport.kabin.sh/docs/de/integrations/erp/sap-s4hana-on-premise.md): Wie ein SAP S/4HANA im eigenen Rechenzentrum oder als Private Edition Seriennummern an BatteryPass übergibt.
- [weclapp](https://passport.kabin.sh/docs/de/integrations/erp/weclapp.md): Wie weclapp über seine REST-API Artikel und Seriennummern an BatteryPass übergibt.
- [Xentral](https://passport.kabin.sh/docs/de/integrations/erp/xentral.md): Wie Xentral über seine REST-API und Webhooks Produkte und Lieferungen an BatteryPass übergibt.

## API-Referenz

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

## API-Referenz: Katalog

- [The units as a spreadsheet with the import's columns](https://passport.kabin.sh/docs/de/api-reference/catalog/export-units.md): Any member. The units matching the filters (at most 10 000) with the columns of an import: model, version, the unit's fields and every unit-level field with a value, so the file can be edited and imported again (`docs/architecture.md` §7). XLSX by default.
- [A battery model](https://passport.kabin.sh/docs/de/api-reference/catalog/get-battery-model.md): Any member.
- [A unit](https://passport.kabin.sh/docs/de/api-reference/catalog/get-battery.md): Any member.
- [A model version](https://passport.kabin.sh/docs/de/api-reference/catalog/get-model-version.md): Any member.
- [Units (individual batteries) of the active organisation](https://passport.kabin.sh/docs/de/api-reference/catalog/list-batteries.md): Any member. Ordered by serial number, then id; filter by model, version, passport status, serial number prefix or the import that created the units.
- [List the battery models of the active organisation](https://passport.kabin.sh/docs/de/api-reference/catalog/list-battery-models.md): Any member. Ordered by name, then id. Archived models only with `include_archived=true`.
- [Versions of a battery model, newest effective date first](https://passport.kabin.sh/docs/de/api-reference/catalog/list-model-versions.md): Any member. At most 200.

## API-Referenz: Werte

- [Registry evaluation of the unit-level fields](https://passport.kabin.sh/docs/de/api-reference/values/get-battery-completeness.md): Any member. Evaluated against the category, the unit's putting-into-service date (else its manufacturing date, else the version's effective date) and the organisation's facts; includes the summary of its model version.
- [Registry evaluation of the model-level fields](https://passport.kabin.sh/docs/de/api-reference/values/get-model-version-completeness.md): Any member. Evaluated against the category, the version's effective date and the organisation's facts.
- [All revisions of one unit-level value, newest first](https://passport.kabin.sh/docs/de/api-reference/values/list-battery-value-history.md): Any member.
- [Current unit-level values of a unit](https://passport.kabin.sh/docs/de/api-reference/values/list-battery-values.md): Any member. One entry per field that has (or had) a value; `value` is null when it was cleared.
- [All revisions of one model-level value, newest first](https://passport.kabin.sh/docs/de/api-reference/values/list-model-version-value-history.md): Any member.
- [Current model-level values of a version](https://passport.kabin.sh/docs/de/api-reference/values/list-model-version-values.md): Any member. One entry per field that has (or had) a value; `value` is null when it was cleared.

## API-Referenz: Nachweise

- [Download the file](https://passport.kabin.sh/docs/de/api-reference/evidence/download-evidence.md): Documents of the tiers `public` and `legitimate_interest` can be downloaded by any member; `authority` and `internal` documents by editors and above. Always sent as an attachment.
- [One document with its revisions and where it is used](https://passport.kabin.sh/docs/de/api-reference/evidence/get-evidence.md): Any member.
- [The evidence library, newest first](https://passport.kabin.sh/docs/de/api-reference/evidence/list-evidence.md): Any member. Superseded revisions are left out unless `include_superseded=true`.

## API-Referenz: Pässe

- [The BatteryPass v2.0 export of a version (all tiers)](https://passport.kabin.sh/docs/de/api-reference/passports/export-passport-json.md): Any member. The stored export, including restricted data; sent as an attachment. Its schema report is in `getPassportVersion` (advisory, ADR-012).
- [A PDF of a version with every tier, restricted rows tagged, the signature and the QR code](https://passport.kabin.sh/docs/de/api-reference/passports/export-passport-pdf.md): Any member.
- [The QR code of the unit's GS1 Digital Link](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-qr.md): Any member. Rendered on demand from `gs1_digital_link` (error correction M, quiet zone of four modules). Only once the identifiers are locked (`409 conflict` before).
- [What changed from an earlier version to this one](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-version-diff.md): Any member. Compares the signed snapshots field by field; `against` defaults to the previous version.
- [One published version with its signed snapshot and validation report](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport-version.md): Any member.
- [The passport of a unit](https://passport.kabin.sh/docs/de/api-reference/passports/get-passport.md): Any member. A unit whose identifiers are not locked and that was never published has a passport in status `draft` without `passport_id`.
- [The passport's registration with the EU registry](https://passport.kabin.sh/docs/de/api-reference/passports/get-registry-submission-status.md): Any member. The EU digital product passport registry has no interface for economic operators yet (`docs/regulatory-reference.md`), so the registration is `not_available` and nothing is submitted. A passport is never shown as registered without the registry's confirmation.
- [The published versions of a unit's passport, newest first](https://passport.kabin.sh/docs/de/api-reference/passports/list-passport-versions.md): Any member. With `at`, only versions published at or before that instant: the first item is the version that was valid then (history by date for the portal, with every tier).

## API-Referenz: Lebenszyklus

- [Record an event in the life of a unit](https://passport.kabin.sh/docs/de/api-reference/lifecycle/create-lifecycle-event.md): Editor and above, or an API key with the `condition` scope (source `api`, ADR-017). `occurred_on` lies between the manufacturing date and today. `evidence_ids` name documents of the evidence library (a diagnostic report, a repair protocol). Events are records: they do not change the unit's data; condition values are reported with `updateCondition`, second life with `createSecondLifeBattery`.
- [The condition data of a unit (the registry's dynamic fields)](https://passport.kabin.sh/docs/de/api-reference/lifecycle/get-condition.md): Any member. The dynamic fields visible for the unit and their current values with `measured_at`.
- [The lifecycle of a unit, newest first](https://passport.kabin.sh/docs/de/api-reference/lifecycle/list-lifecycle-events.md): Any member. Events recorded by members, service-partner reports, condition updates and second life.
- [Report measured condition data (merge)](https://passport.kabin.sh/docs/de/api-reference/lifecycle/update-condition.md): Editor and above, or an API key with the `condition` scope (source `api`, ADR-016, ADR-017). Merge semantics: only the named fields change, `null` clears a field. Each value has a `measured_at` (its own or the request's), which must not lie in the future or before the manufacturing date. Fields that are not dynamic fields of the unit are refused (`unknown_field`); so is the whole update when a value is invalid or the merged condition data fails a cross-field check. A value older than the stored one, or equal to it, is skipped and listed. Accepted values are stored as approved measurements and recorded as a `condition_update` lifecycle event; a published passport is re-published as the organisation's `condition_republish` setting says (immediately in this request, or by the daily job).

## API-Referenz: Feldregister

- [Version, content hash and status of the field registry in use](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-info.md): Any signed-in user.
- [The editor schema of a battery category](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-schema.md): Any signed-in user. Sections and fields with bilingual labels, help, tier, the requirement rule for the category (before dates, conditions and values are applied; per-target status comes from the completeness operations), validation schema and export paths.
- [The registry in use and how many of the organisation's passports need an update](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-status.md): Any member. After a new registry version is deployed, a job re-evaluates the organisation's published passports; passports with a newly missing required value become `update_needed` (they stay online) and their versions get an `update_passports` task.

## API-Referenz: Standorte

- [Manufacturing facilities of the active organisation](https://passport.kabin.sh/docs/de/api-reference/facilities/list-facilities.md): Any member. Ordered by name, then id.

## API-Referenz: Öffentlich

- [A public document of a public passport](https://passport.kabin.sh/docs/de/api-reference/public/download-public-passport-document.md): No authentication. Only documents of the `public` tier that a public field of a published version names (for example the EU declaration of conformity); everything else is `404`.
- [The public passport of a unit, looked up by GTIN and serial number](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport-by-product-id.md): No authentication. Same response as `getPublicPassport`.
- [The public passport as it was at a point in time](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport-version.md): No authentication. The version with `published_at ≤ at < valid_until`; `404` before the first publication. Versions are immutable, so the response is cached for a day.
- [The public passport (current version)](https://passport.kabin.sh/docs/de/api-reference/public/get-public-passport.md): No authentication. Only the `public` tier, as stored when the version was published (ADR-013). Passports that are not public (`qr_locked`, `withdrawn`, `suspended`, `deleted_recycled`) answer with their status and no content. Cached for 5 minutes; rate-limited per client address.
- [Check the signatures of a version on the server](https://passport.kabin.sh/docs/de/api-reference/public/verify-passport.md): No authentication. A convenience: the same check works offline with the public JSON and `/.well-known/batterypass/keys.json` (ADR-004, ADR-013). Without `version_no`, the current version.

## API-Referenz: Änderungen

- [The organisation's changes, oldest first, for polling](https://passport.kabin.sh/docs/de/api-reference/changes/list-changes.md): Any member, or an API key with the `read` scope (ADR-026). The organisation's changes in the order they became visible, oldest first, as `{id, occurred_at, entity_type, entity_id, action}`: no values, no actors, no personal data; read the entity for its current state. Keep `next_cursor` of the last page and ask again later: a change appears only once every transaction that started before it has finished, so a cursor never skips a change that commits late. `next_cursor` is set whenever the page has items, also on the last page; an empty page keeps the cursor you sent (`next_cursor` null). Without `cursor` the feed starts at the beginning of the organisation's history.

## API-Referenz: Importe

- [Upload a spreadsheet of units](https://passport.kabin.sh/docs/de/api-reference/imports/create-import.md): Editor and above, or an API key with the `import` scope (ADR-026). A CSV (UTF-8, UTF-16 or Windows-1252; `;`, `,`, tab or `|` separated) or XLSX file of at most 10 MB, 10 000 rows and 200 columns; the first non-empty row holds the headers. The answer is the import with a mapping proposed from the headers (registry CSV headers, aliases, labels; units such as `(kWh)` are converted), or taken from the import preset named in `preset` (the ERP registry): a preset maps the columns it knows by their headers and leaves the others unmapped. A key stages the import only: members of the organisation commit it and approve its values in the portal, so declared data still enters through a member's decision.
- [One import with its mapping and summary](https://passport.kabin.sh/docs/de/api-reference/imports/get-import.md): Any member, or an API key with the `import` scope (ADR-026). Poll it after `validateImport`: the status becomes `validated` (or `failed`) and `summary` counts valid, warning, error and duplicate rows.
- [Imports of the active organisation, newest first](https://passport.kabin.sh/docs/de/api-reference/imports/list-imports.md): Any member, or an API key with the `import` scope (ADR-026). An import staged with a key names the key in `created_by_api_key` instead of `created_by`.
- [Map the columns of an import](https://passport.kabin.sh/docs/de/api-reference/imports/update-import-mapping.md): Editor and above, or an API key with the `import` scope (ADR-026), while the import is not being processed or committed. Each target at most once; `unit` is the unit a column's numbers are written in when it differs from the field's. With `preset` (an import preset of the ERP registry) the mapping is taken from the preset by the file's headers and `mapping` must be empty. A validated import must be validated again.
- [Start validating every row of an import](https://passport.kabin.sh/docs/de/api-reference/imports/validate-import.md): Editor and above, or an API key with the `import` scope (ADR-026). A job reads every row with the mapping, validates it with the editor's validators and finds duplicate serial numbers in the file and in the database (after removing surrounding spaces and invisible characters). Requires a serial number column and a model column or `options.battery_model_id`. Follow the import with `getImport` until its status is `validated` or `failed`.

## Optional

- [Änderungen](https://passport.kabin.sh/docs/de/changelog.md): Was sich an der Integrations-API und an dieser Dokumentation geändert hat.
- [OpenAPI (JSON)](https://passport.kabin.sh/docs/openapi.json): Der veröffentlichte OpenAPI-Vertrag
- [OpenAPI (YAML)](https://passport.kabin.sh/docs/openapi.yaml): Der veröffentlichte OpenAPI-Vertrag