Zu Content springen
Deutsch
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

Wie nutze ich die REST-API? API-Empfänger und API-Keys anlegen

Mit der REST-API verbindest du Inventory ONE mit deinen eigenen Systemen, zum Beispiel einem ERP, einem Personal- oder einem Fuhrparksystem. Dein System liest und pflegt Inventar, Lager, Standorte und Empfänger dann direkt über die Schnittstelle, statt dass du die Daten von Hand nachträgst. Der Zugriff läuft über API-Keys. Jeder API-Key gehört zu einem API-Empfänger, der dein angebundenes System in Inventory ONE darstellt.

Voraussetzungen

  • Die REST-API ist für dein Konto freigeschaltet. Sie ist in den Paketen Basis 500 und Pro 4.000 zubuchbar und im Paket Big 10.000 enthalten (siehe Pakete und Preise). Ohne Freischaltung fehlt der Reiter API-Empfänger in der Benutzerverwaltung. Kontaktiere in diesem Fall unseren Support, wir schalten die Schnittstelle für dein Konto frei.
  • Du hast die technische Dokumentation der Schnittstelle (OpenAPI-Spezifikation). Du bekommst sie vom Support; sie beschreibt alle Endpunkte, Felder und Fehlermeldungen für deine Entwickler.
  • Deine Rolle darf API-Empfänger und API-Keys verwalten. Administratoren dürfen das standardmäßig. Bei eigenen Rollen brauchst du im Bereich Empfänger die Rechte Sehen, Anlegen, Bearbeiten und Löschen für den Empfängertyp API-Empfänger sowie im Bereich API-Schlüssel die Rechte API-Schlüssel sehen, API-Schlüssel anlegen und API-Schlüssel löschen (siehe Wie lege ich eigene Benutzerrollen an?).

Was ist ein API-Empfänger?

Ein API-Empfänger ist ein technischer Empfänger ohne Login. Er steht für ein angebundenes System, zum Beispiel „ERP“ oder „Personalsystem“. An ihm hängen die API-Keys, mit denen sich dein System an der Schnittstelle anmeldet. Lege für jedes angebundene System einen eigenen API-Empfänger an. So siehst du später, welches System welche Keys hat, und kannst ein System abklemmen, ohne die anderen zu stören. Inventar lässt sich einem API-Empfänger nicht zuweisen; er dient nur der Anbindung. Sind für dein Konto Geschäftseinheiten aktiv, ordnest du den API-Empfänger beim Anlegen einer Geschäftseinheit zu.

API-Empfänger anlegen

  1. Öffne Einstellungen → Benutzer und wechsle auf den Reiter API-Empfänger.
  2. Klicke auf Neuen API-Empfänger anlegen.
  3. Gib einen Namen ein, zum Beispiel den Namen des Systems, das du anbinden möchtest. Sind Geschäftseinheiten aktiv, wählst du zusätzlich die Geschäftseinheit.
  4. Klicke auf Speichern.

Die Übersicht zeigt alle API-Empfänger mit Name und Geschäftseinheit. Ein Klick auf eine Zeile öffnet die Detailansicht. Dort kannst du den API-Empfänger über Bearbeiten umbenennen und seine API-Keys verwalten. Brauchst du ein angebundenes System nicht mehr, deaktivierst du seine API-Keys (siehe unten); der API-Empfänger selbst lässt sich in der Anwendung nicht löschen.

API-Key anlegen

  1. Öffne die Detailansicht des API-Empfängers. Im Abschnitt API-Keys siehst du alle bisher angelegten Keys.
  2. Klicke auf Neuen API-Key anlegen.
  3. Gib dem Key einen Namen, zum Beispiel „Produktivsystem“ oder „Test“. Der Name erscheint später in der Tabelle.
  4. Setze den Haken bei Schreibrechte, wenn dein System Daten anlegen, ändern oder löschen soll. Ohne Haken darf der Key nur lesen (siehe unten).
  5. Wähle optional ein Ablaufdatum. Nach diesem Tag akzeptiert die Schnittstelle den Key nicht mehr.
  6. Klicke auf Speichern.

Inventory ONE zeigt dir den neuen Key im Dialog API-Key erstellt genau einmal an. Kopiere ihn jetzt über Kopieren und hinterlege ihn sicher in deinem System. Aus Sicherheitsgründen kannst du den vollständigen Key später nicht erneut abrufen; die Tabelle zeigt nur noch seinen Anfang. Hast du den Key verloren, legst du einfach einen neuen an und deaktivierst den alten.

Die Tabelle der API-Keys zeigt zu jedem Key den Namen, den Anfang des Keys, ob er Schreibrechte hat, das Ablaufdatum und den Status Aktiv oder Gelöscht.

Lese- oder Schreibrechte

API-Keys sind an keinen Benutzer gebunden, sondern erhalten ihre Rechte über eine eigene Rolle (siehe Welche Rollen gibt es?):

  • Ohne Schreibrechte arbeitet der Key mit der vordefinierten Rolle API-Zugriff (nur lesend). Er darf alle Daten lesen, aber nichts anlegen, ändern, löschen oder buchen. Schreibende Aufrufe beantwortet die Schnittstelle mit „Keine Berechtigung“.
  • Mit Schreibrechten arbeitet der Key wie ein Administrator und darf Daten anlegen, ändern und löschen.

Beide Rollen findest du in der Rollenverwaltung unter Einstellungen → Rollen, sofern sie für dein Konto freigeschaltet ist. Du kannst ihre Rechte dort anpassen, zum Beispiel die Empfänger-Rechte auf bestimmte Empfängertypen einschränken; die Rolle API-Zugriff (nur lesend) lässt sich allerdings keinem Benutzer zuweisen und nicht als Vorlage für eigene Rollen verwenden. Änderungen an diesen Rollen wirken sofort auf alle API-Keys, die mit ihnen arbeiten.

Gib einem Key nur so viele Rechte, wie dein System wirklich braucht. Ein System, das nur Bestände auswertet, kommt mit einem Key ohne Schreibrechte aus. Lege für jedes System und jeden Zweck einen eigenen Key an und setze ein Ablaufdatum. Dann kannst du einzelne Zugänge gezielt beenden, ohne alle anderen zu stören.

API-Key deaktivieren

Brauchst du einen Key nicht mehr oder ist er in falsche Hände geraten, deaktivierst du ihn:

  1. Öffne die Detailansicht des API-Empfängers und wähle in der Tabelle API-Keys die Zeile des Keys aus.
  2. Klicke auf Deaktivieren und bestätige die Sicherheitsabfrage.

Mit diesem Key ist danach kein Zugriff mehr über die Schnittstelle möglich. Die Deaktivierung lässt sich nicht rückgängig machen; der Key bleibt mit dem Status Gelöscht in der Tabelle sichtbar. Braucht dein System weiter Zugriff, lege einen neuen Key an und tausche ihn dort aus.

So greift dein System auf die Schnittstelle zu

Die Schnittstelle ist unter der Adresse https://app.inventory-one.com/api/v2 erreichbar (für mein_werkzeugkoffer: https://app.meinwerkzeugkoffer.de/api/v2). Dein System sendet den API-Key bei jedem Aufruf im HTTP-Header X-ONE-API-KEY. Daten werden als JSON gesendet und empfangen. Ein Beispiel, das alle Mitarbeiter abruft:

curl -H "X-ONE-API-KEY: DEIN-API-KEY" "https://app.inventory-one.com/api/v2/receivers?type=employee"

Fehlt der Key, ist er abgelaufen oder deaktiviert, antwortet die Schnittstelle mit dem Status 401. Fehlt dem Key das Recht für die Aktion, antwortet sie mit 403. Verstößt eine Anfrage gegen eine Regel der Anwendung, zum Beispiel ein doppelter Name, antwortet sie mit 422 und nennt die Validierungsmeldungen, die du auch aus der Anwendung kennst. Welche Felder jeder Endpunkt erwartet und zurückgibt, steht in der OpenAPI-Spezifikation.

Was kann dein System über die Schnittstelle tun?

Die Schnittstelle deckt die wichtigsten Daten von Inventory ONE ab. Es gelten dieselben Regeln wie in der Anwendung, zum Beispiel Pflichtfelder, eindeutige Namen und vergebene QR-Codes.

  • Inventare: auflisten, einzeln abrufen, anlegen, bearbeiten und löschen; Reservierungen anlegen, ändern und löschen; Dokumente und Bilder hochladen; Prüfergebnisse abrufen.
  • Mengeninventar und Verbrauchsmaterial: auflisten, abrufen, anlegen, bearbeiten und löschen.
  • Sets: auflisten, abrufen, anlegen, bearbeiten und löschen.
  • Lager und Standorte: auflisten, abrufen, anlegen, bearbeiten und löschen.
  • Empfänger: auflisten (nach Typ filterbar), abrufen, anlegen, bearbeiten, archivieren, wiederherstellen und löschen. Das gilt für Mitarbeiter, externe Personen, Subunternehmer, Räume, Projekte, Baustellen, Schüler, Schulklassen, Fahrzeuge und API-Empfänger. Name, Standort, QR-Codes und Archiv-Status sind änderbar; der Typ eines Empfängers lässt sich nicht ändern. Benutzer bleiben an ihr Login gebunden: Sie werden weiterhin in der Anwendung angelegt und gelöscht, über die Schnittstelle lassen sie sich nur auflisten, archivieren und wiederherstellen.

Ein typischer Einsatz ist der Abgleich von Empfängern: Dein Personalsystem legt neue Mitarbeiter als Empfänger an, benennt sie bei Änderungen um und archiviert sie beim Austritt. Dein Fuhrparksystem hält die Fahrzeuge aktuell. Dabei gelten dieselben Schutzregeln wie in der Anwendung: Doppelte Namen innerhalb eines Empfängertyps und bereits vergebene QR-Codes werden abgelehnt, und Empfänger mit zugewiesenem Inventar lassen sich weder archivieren noch löschen. Hast du in der Rollenverwaltung die Empfänger-Rechte der Rolle Administrator oder API-Zugriff (nur lesend) auf bestimmte Empfängertypen eingeschränkt, sieht und ändert ein Key mit dieser Rolle nur diese Typen; Anfragen zu anderen Typen beantwortet die Schnittstelle mit „Keine Berechtigung“.

Sicherheitshinweise
  • Behandle API-Keys wie Passwörter. Gib sie nicht per E-Mail oder Chat weiter und speichere sie nur in deinem angebundenen System.
  • Nutze Keys ohne Schreibrechte, wo immer Lesen ausreicht.
  • Setze ein Ablaufdatum und erneuere Keys regelmäßig.
  • Deaktiviere einen Key sofort, wenn du den Verdacht hast, dass er in falsche Hände geraten ist, und lege einen neuen an.