# Introduction

> What the BatteryPass integration API does, what stays in the portal, and where to start.

BatteryPass is a platform for digital battery passports under the EU Battery Regulation (Regulation (EU)
2023/1542). Manufacturers maintain battery models, units and their data in the BatteryPass portal, have the
data reviewed and publish signed passports. This documentation covers the **integration API**: the part of
BatteryPass that your own systems (ERP, MES, battery management system, data warehouse) use with an API key.

## What the API covers

| Area                                  | With a key                                                                                                                                     | Scope               |
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| Battery models, model versions, units | Read, units also as a spreadsheet export                                                                                                       | `read`              |
| Values                                | Read with provenance (source, review status, revisions, supporting documents) and completeness                                                 | `read`              |
| Evidence and facilities               | Read document metadata, download files, list manufacturing facilities                                                                          | `read`              |
| Passports                             | Read the current state, published versions, differences between versions, exports (BatteryPass JSON, PDF, QR code) and the registration status | `read`              |
| Field registry                        | Read version, schema and status                                                                                                                | `read`              |
| Condition data                        | Read, and report measurements such as state of charge or capacity fade                                                                         | `read`, `condition` |
| Lifecycle events                      | Read, and report events such as an inspection or a repair                                                                                      | `read`, `condition` |
| Changes                               | Follow what changed in the organisation (change feed for polling)                                                                              | `read`              |
| Imports                               | Stage spreadsheet imports of units: upload, map, validate; members commit and approve them                                                     | `import`            |
| Public passports                      | Read the public tier, check signatures, download public documents                                                                              | no key              |

Every operation, with its parameters, responses and required scope, is in the
[API reference](https://passport.kabin.sh/docs/en/api-reference).

## What stays in the portal

- **Declared data** (models, units, values, documents) is entered by members in the portal or imported from a
  spreadsheet there. The API does not create or change declared data.
- **Review, approval and publication** stay with members. By default the four-eyes principle applies: the
  person who entered a value cannot approve it.
- **Members, API keys and organisation settings** are managed in the portal by owners and administrators.

Condition data reported with a key is the exception to the review step: it is stored as an approved
measurement with its source and measurement time, and a published passport is updated as your organisation's
settings say. See [Condition data and lifecycle](https://passport.kabin.sh/docs/en/concepts/condition-and-lifecycle).

> [!NOTE]
> **EU registry**
>
> The EU registry for digital product passports does not yet offer an interface for economic operators.
> BatteryPass submits nothing to it so far, and `getRegistrySubmissionStatus` reports `not_available`.

## How the parts fit together

```mermaid
flowchart LR
  Portal["Portal: members enter, review, publish"] --> BP[("BatteryPass")]
  Import["Spreadsheet import in the portal"] --> BP
  BP -- "API key, scope read" --> ERP["Your systems: ERP, data warehouse"]
  BMS["BMS or service partner system"] -- "API key, scope condition" --> BP
  BP --> Public["Public passport: QR code, page, JSON, no key"]
```

## Start here

[**Quickstart**](https://passport.kabin.sh/docs/en/quickstart): Create a key, make your first request and read a passport.

[**Authentication**](https://passport.kabin.sh/docs/en/authentication): Organisation keys, scopes and what a key may do.

[**Guides**](https://passport.kabin.sh/docs/en/guides): Step-by-step instructions for common integration tasks.

[**Recipes**](https://passport.kabin.sh/docs/en/recipes): Complete, short programs to copy and adapt.

[**API reference**](https://passport.kabin.sh/docs/en/api-reference): Every operation of the published contract, with a playground.