API

Die API von BoxHero ermöglicht es Entwicklern, unsere Bestandsverwaltungsfunktionen in externe Anwendungen zu integrieren, um Daten effizient abzurufen und mit ihnen zu interagieren.

BoxHero’s API: A Simple Way to Integrate Your Inventory DataBoxHero Blog

---

API-Referenz

Detaillierte Endpoint-Dokumentationen finden Sie hier: https://rest.boxhero-app.com/docs/api

---

Endpoint

Alle API-Anfragen sollten an die folgende Basis-URL gerichtet werden: https://rest.boxhero-app.com

Authentifizierung

Alle API-Anfragen müssen einen Authorization Header mit einem Bearer-Token:

Authorization: Bearer {API_TOKEN}

Um ein API-Token zu erhalten:

1. Melden Sie sich in Ihrem BoxHero-Konto auf dem Desktop (Web) an.

2. Navigieren Sie zu Einstellungen > Integrationen.

3. Erstellen Sie ein neues API-Token.

Anfragen senden

Hier ist eine Beispiel-API-Anfrage zum Abrufen von Produkten.

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'

Ratenbegrenzungen

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

• 5 Anfragen pro Sekunde für jeden Endpoint.

Sobald Sie eine Ratenbegrenzung erreichen, wird eine Fehlermeldung mit dem folgenden Inhalt angezeigt:

• X-Ratelimit-Limit - Maximale Anfragen pro Minute

• X-Ratelimit-Remaining - Verbleibende Anfragen

• X-Ratelimit-Reset - Verbleibende Zeit (in Sekunden) bis zum Zurücksetzen der Anfrageanzahl

---

Antworten

Erfolg

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

Fehler

Statuscodes im Bereich 400 oder 500 weisen auf Fehlfunktionen der API-Anfrage hin:

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

• 500er-Bereich: Fehler auf Server-Seite.

Beispiel für eine Fehlerantwort:

{
  "id": "ex_ku3gij67k9xzc8ef6r5esyu5",
  "type": "/errors/tokens/invalid",
  "title": "Authentifizierungstoken ist ungültig. Bitte stellen Sie ein gültiges 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 : Geben Sie den Inhalt des Fehlers in menschenlesbarer Form an.

• correlation_id : Verweist auf die ID der mit dem Fehler verknüpften Anfrage.

• others : Zusätzliche Felder können enthalten sein, um weitere Informationen bereitzustellen, wie etwa "given" im Beispiel.

Häufige Fehlertypen

Typ	Beschreibung
/errors/not-found	Angeforderte Ressource nicht gefunden (z. B. existiert ein Element mit einer bestimmten ID nicht).
/errors/invalid-request	Ungültige Parameter in der Anfrage.
/errors/invalid-team-mode	Die angeforderte Abfrage kann im aktuellen Teammodus nicht verarbeitet werden (z. B. die Verwendung der Standort Lookup-API im Basic Mode).
/errors/tokens/required	API-Token fehlt.
/errors/tokens/invalid	Ungültiges API-Token (z. B. ist das API-Token abgelaufen).
/errors/too-many-requests	Ratenbegrenzung überschritten.
/errors/unhandled	Ungelöster Fehler auf Server-Seite.
/errors/core/usage-limit-exceeded	Nutzungsgrenze erreicht. Ein Plan-Upgrade ist erforderlich.

Paginierung

Für Endpunkte, die große Datensätze zurückgeben (z. B. Artikellisten, Transaktionslisten), begrenzt die Listenansicht-API durch Paginierung die Anzahl der Elemente, die in einer einzelnen Anfrage zurückgegeben werden. Wir verwenden cursor-basierte Paginierung:

Um festzustellen, ob Paginierung erforderlich ist, prüfen Sie, ob im Request-Body des Endpunkts in der API-Dokumentation Paginierungsparameter vorhanden sind.

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 true. Das bedeutet, dass eine weitere Seite verfügbar ist.

• Wenn trueist, 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 false ist, um die vollständige Liste abzurufen.

---

Support und Feedback

Wenn Sie auf Probleme stoßen oder zusätzliche API-Funktionen benötigen, kontaktieren Sie bitte unser Support-Team. Wir freuen uns über Ihr Feedback zu API-Verbesserungen und neuen Funktionswünschen.