# API

{% embed url="<https://www.boxhero.io/en/blog/boxhero-open-api-integrate-inventory-data>" %}

***

## **API-Referenz**

Für eine detaillierte Dokumentation der Endpunkte besuchen Sie bitte: <https://rest.boxhero.io/docs/api>

***

## Endpunkt

Alle API-Anfragen sollten an die folgende Basis-URL gerichtet werden:\ <mark style="color:blau;"><https://rest.boxhero-app.com></mark>

## **Authentifizierung**

Alle API-Anfragen müssen einen <mark style="color:blau;">**Authorization**</mark> Header mit einem <mark style="color:blau;">**Bearer-Token**</mark>:

```
Authorization: Bearer {API_TOKEN}
```

Um einen API-Token zu erhalten:

1. Melden Sie sich in Ihrem BoxHero-Konto auf dem Desktop (Web) an.
2. Navigieren Sie zu <mark style="color:blau;">**`Einstellungen`**</mark> > <mark style="color:blau;">**`Integrationen`**</mark>.
3. Erstellen Sie einen neuen API-Token.

## **Anfragen senden**

Hier ist ein Beispiel für eine API-Anfrage zum Abrufen von Produkten.

```bash
curl -X 'GET' \
  'https://rest.boxhero-app.com/v1/items?location_ids=12345&location_ids=34567&limit=100' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer test-api-token-123'
```

## Ratenlimits

Um die Systemstabilität zu gewährleisten, setzen wir die folgenden Ratenlimits durch:

* 5 Abfragen pro Sekunde für jeden Endpunkt.

Sobald das Ratenlimit erreicht ist, wird eine Fehlermeldung mit folgendem Inhalt angezeigt:

* `X-Ratelimit-Limit` - Maximale Abfragen pro Minute
* `X-Ratelimit-Remaining` - Verbleibende Abfragen
* `X-Ratelimit-Reset` - Verbleibende Zeit (in Sekunden) bis zum Zurücksetzen der Abfrageanzahl

***

## Antworten

### Erfolg

Antworten mit HTTP-Statuscodes im Bereich 200 zeigen eine erfolgreiche API-Verarbeitung an.

### Fehler

Statuscodes im Bereich 400 oder 500 weisen auf fehlgeschlagene API-Anfragen hin:

* 400-Bereich: Fehler auf der Client-Seite aufgrund der mit der Anfrage bereitgestellten Informationen (z. B. fehlende erforderliche Parameter).
* 500-Bereich: Fehler auf der Server-Seite.

**Beispiel für eine Fehlerantwort:**

```json
{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Der Authentifizierungstoken ist ungültig. Bitte stellen Sie einen gültigen Token bereit.",
  "correlation_id": "rq_z4g7dh55ykol7v2cx6homkpd",
  "given": "invalid-token-123"
}
```

* **id :** Eine eindeutige ID zur Identifizierung des Fehlers.
* **type :** Ein Code in Form einer URL, der den Fehlertyp identifiziert.
* **title :** Gibt den Inhalt des Fehlers in menschenlesbarer Form an.
* **correlation\_id :** Verweist auf die ID der Anfrage, die mit dem Fehler verknüpft ist.
* **andere :** Zusätzliche Felder können enthalten sein, um weitere Informationen bereitzustellen, wie z. B. "*given*" im Beispiel.

### Häufige Fehlertypen

<table><thead><tr><th width="252">Typ</th><th>Beschreibung</th></tr></thead><tbody><tr><td>/errors/not-found</td><td>Angeforderte Ressource nicht gefunden (z. B. existiert ein Element mit einer bestimmten ID nicht).</td></tr><tr><td>/errors/invalid-request</td><td>Ungültige Parameter in der Anfrage.</td></tr><tr><td>/errors/invalid-team-mode</td><td>Die angeforderte Abfrage kann im aktuellen Teammodus nicht verarbeitet werden (z. B. Verwendung der <em>location</em> Lookup-API im <em>Basis-Modus</em>).</td></tr><tr><td>/errors/tokens/required</td><td>API-Token fehlt.</td></tr><tr><td>/errors/tokens/invalid</td><td>Ungültiger API-Token (z. B. API-Token ist abgelaufen).</td></tr><tr><td>/errors/too-many-requests</td><td>Ratenlimit überschritten.</td></tr><tr><td>/errors/unhandled</td><td>Ungelöster serverseitiger Fehler.</td></tr><tr><td>/errors/core/usage-limit-exceeded</td><td>Nutzungsgrenze erreicht. Plan-Upgrade erforderlich.</td></tr></tbody></table>

## Paginierung

Für Endpunkte, die große Datenmengen zurückgeben (z. B. Artikellisten, Transaktionslisten), begrenzt die Listenansichts-API die Anzahl der in einer einzelnen Anfrage zurückgegebenen Elemente durch Paginierung. Wir verwenden cursor-basierte Paginierung:

{% hint style="info" %}
Um festzustellen, ob Paginierung erforderlich ist, prüfen Sie, ob in der API-Dokumentation im Request-Body des Endpunkts pagierungsbezogene Parameter vorhanden sind.
{% endhint %}

#### **Paginierungsparameter**

* `has_more` : Ein boolescher Wert, der angibt, ob über die aktuelle Seite hinaus weitere Daten vorhanden sind.
* `cursor` : Liefert den Cursor-Wert zum Abrufen der nächsten Seite.

#### **Abrufen der nächsten Seite**

* Prüfen Sie, ob `has_more` ist `wahr`. Das bedeutet, dass eine weitere Seite verfügbar ist.
* Wenn `wahr`, senden Sie eine weitere Anfrage unter Einbeziehung von `cursor={erhaltener Cursor-Wert}` in den Parametern. Dadurch werden die nachfolgenden Daten zurückgegeben.
* Wiederholen Sie dies, bis `has_more` ist `falsch` ist, um die vollständige Liste abzurufen.

***

## Support und Feedback

Wenn Sie auf Probleme stoßen oder zusätzliche API-Funktionen benötigen, wenden Sie sich bitte an unser [Support-Team](https://docs-en.boxhero.io/etc/contact). Wir freuen uns über Ihr Feedback zu API-Verbesserungen und Anfragen für neue Funktionen.