# Support

> Wie Sie Hilfe zu einer Integration bekommen, was in eine Anfrage gehört und wo der Stand der Funktionen dokumentiert ist.

## Wen Sie ansprechen

| Frage                                                                                           | Ansprechpartner                                                                       |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| API-Schlüssel, Scopes, Einstellungen der Organisation wie die Regel für die Neuveröffentlichung | Ein Inhaber Ihrer Organisation, im Portal                                             |
| Daten in einem Pass, Prüfung, Veröffentlichung                                                  | Die für die Daten verantwortlichen Mitglieder Ihrer Organisation                      |
| Unerklärliche Fehler, Ausfälle, vermutete Sicherheitsprobleme                                   | Ihr Ansprechpartner für BatteryPass oder der Betreiber Ihrer BatteryPass-Installation |

Supportwege und Reaktionszeiten vereinbaren Sie mit dem Betreiber Ihrer Installation; diese Dokumentation legt
sie nicht fest.

## Vorher prüfen

- `code`, `detail` und `errors[]` des Problems nennen meist die Ursache; [Fehler](https://passport.kabin.sh/docs/de/errors) erklärt jeden
  Code, und [Fehler behandeln](https://passport.kabin.sh/docs/de/guides/handle-errors) zeigt, wie Sie darauf reagieren.
- `429 rate_limited`: Warten Sie die Sekunden aus `Retry-After` ab ([Ratenlimits](https://passport.kabin.sh/docs/de/rate-limits)).
- `403 forbidden` mit einem Schlüssel: Dem Schlüssel fehlt der Scope der Operation, oder die Operation verlangt
  mehr als die Rechte eines Betrachters ([Authentifizierung](https://passport.kabin.sh/docs/de/authentication)).

## Die Request-Id angeben

Jede Antwort, ob erfolgreich oder nicht, trägt den Header `X-Request-Id`. Fehlerantworten wiederholen ihn als
`request_id` im Problem. Mit dieser Id findet der Betreiber Ihre Anfrage in den Logs. Eine `X-Request-Id`, die Sie
selbst senden, ignoriert BatteryPass und vergibt immer eine eigene; protokollieren Sie also die aus der Antwort.

```bash title="cURL"
curl -s -D - -o /dev/null "$BATTERYPASS_URL/api/v1/battery-models?limit=1" \
  -H "Authorization: Bearer $BATTERYPASS_API_KEY" | grep -i '^x-request-id'
```

```ts title="TypeScript"
const base = process.env.BATTERYPASS_URL;
const key = process.env.BATTERYPASS_API_KEY;

const res = await fetch(`${base}/api/v1/battery-models?limit=1`, {
  headers: { Authorization: `Bearer ${key}` },
});
const requestId = res.headers.get('X-Request-Id');
if (res.ok) {
  console.log(`ok request_id=${requestId}`);
} else {
  const problem = await res.json();
  console.error(`${res.status} ${problem.code} request_id=${problem.request_id ?? requestId}`);
}
```

```python title="Python"
import os

import requests

base = os.environ["BATTERYPASS_URL"]
key = os.environ["BATTERYPASS_API_KEY"]

res = requests.get(
    f"{base}/api/v1/battery-models",
    params={"limit": 1},
    headers={"Authorization": f"Bearer {key}"},
    timeout=30,
)
request_id = res.headers.get("X-Request-Id")
if res.ok:
    print(f"ok request_id={request_id}")
else:
    problem = res.json()
    print(f"{res.status_code} {problem.get('code')} request_id={problem.get('request_id', request_id)}")
```

```go title="Go"
package main

import (
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, os.Getenv("BATTERYPASS_URL")+"/api/v1/battery-models?limit=1", nil)
	if err != nil {
		log.Fatal(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("BATTERYPASS_API_KEY"))
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer res.Body.Close()

	requestID := res.Header.Get("X-Request-Id")
	if res.StatusCode >= 400 {
		var problem struct {
			Code string `json:"code"`
		}
		_ = json.NewDecoder(res.Body).Decode(&problem)
		log.Printf("%d %s request_id=%s", res.StatusCode, problem.Code, requestID)
		return
	}
	fmt.Println("ok request_id=" + requestID)
}
```

## Was in die Anfrage gehört

1. **Den Aufruf benennen**

   Die `request_id`, die Uhrzeit in UTC, die Operation (etwa `updateCondition`, oder Methode und Pfad) und den
   HTTP-Status mit `code`, `detail` und `errors[]` des Problems.

2. **Schlüssel und Daten benennen**

   Das Präfix des Schlüssels (seine ersten 12 Zeichen, wie das Portal sie zeigt) und die beteiligten Ids:
   Batterie-Id, UUID des Passes, Versionsnummer.

3. **Den Fall beschreiben**

   Was Sie erwartet haben, was passiert ist und ob es jedes Mal oder nur manchmal auftritt.

> [!WARNING]
> Senden Sie nie den vollständigen API-Schlüssel, und lassen Sie personenbezogene Daten sowie Exporte mit
> eingeschränkten Stufen weg (BatteryPass JSON und PDF einer Passversion). Request-Id und Ids genügen, um die Anfrage
> zu finden.

## Stand der Funktionen

- Das [Changelog](https://passport.kabin.sh/docs/de/changelog) nennt, was sich an der API und an dieser Dokumentation geändert hat, auch
  als [RSS-Feed](https://passport.kabin.sh/docs/de/changelog/rss.xml).
- Der veröffentlichte Vertrag nennt seine Version in `info.version`; Sie laden ihn als [JSON](https://passport.kabin.sh/docs/openapi.json)
  oder [YAML](https://passport.kabin.sh/docs/openapi.yaml) herunter.
- [`getRegistryInfo`](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-info) und
  [`getRegistryStatus`](https://passport.kabin.sh/docs/de/api-reference/registry/get-registry-status) melden das verwendete Feldregister und
  wie viele Pässe nach einer Registeränderung aktualisiert werden müssen.
- [`getRegistrySubmissionStatus`](https://passport.kabin.sh/docs/de/api-reference/passports/get-registry-submission-status) meldet den
  Stand eines Passes im EU-Register; er ist `not_available`, solange das EU-Register Wirtschaftsakteuren keine
  Schnittstelle bietet.