API

Inventory360 bietet für nahezu alle Bereiche eine vollständig dokumentierte HTTP REST API. Hierüber können externe Systeme mit Inventory360 automatisiert kommunizieren um z.B. Daten abzurufen oder Assets anzulegen.

API Versionen

Seit Release 3.5.1 steht eine neue API Version 2.0 zur Verfügung, welche auch den Schreibzugriff auf das System ermöglicht. Die ältere API 1.0 sollte daher nicht mehr verwendet werden.

Dokumentation

Die Entwickler Dokumentation der zur Verfügung stehenden API Endpunkte finden sich im nachfolgenden Dokumentationsbereich:

API Dokumentation

Zugang anlegen

Um einen neuen API Zugang im System anzulegen klicken Sie im Adminbereich zunächst auf den Eintrag API. Mit einem Klick auf den grünen Hinzufügen Button wird der Dialog zur Erstellung eines neuen API Zugangs erstellt.

Anlegen eines API Benutzers

Einstellung	Beschreibung
(1) Name	Technischer / interner Name des API Zugangs
(2) Beschreibung	Interne Beschreibung des Zugangs (Welches System / welche Rechte?)
(3) Rechte	Auswahl der Lese- oder Schreibrechte

Bei der Anlage des Benutzers wird automatisch ein neuer Zugangs-Token generiert. Dieser wird für die Authentifizierung der Abfragen verwendet.

Sicherheitshinweis

Beim API Token handelt es sich um einen vertraulichen Schlüssel. Dieser sollte nicht an unbefugte Dritte weitergegeben werden.

API Token eines Benutzers

Implementierung von Schnittstellen

Über unsere REST API bieten wir eine offen dokumentierte Zugangsmöglichkeit für Dritte oder auch den Endanwender selbst.

Bitte beachten Sie, dass für ein reibungsloses und sinnvolles Zusammenspiel zweier Systeme (z.B. Inventory360 und ERP-System) in 99% der Fälle zusätzlich entsprechende Business-Logik erforderlich ist. Nur so können Geschäftsprozesse vernünftig abgebildet werden.

Consulting & Customizing

Für Rückfragen zur API oder möglichen Anbindungsmöglichkeiten stehen wir Ihnen gerne im Rahmen eines Consulting-Projektes zur Verfügung.

Ist die Umsetzung von Business-Logik auf Inventory360 Seite notwendig, ist dies in der Regel über ein Customizing möglich.

API Pagination bei sehr großen Datenbeständen

Seit Release 3.13 kann bei bestimmten API Aufrufen vom Laden gesamter Listen auf einen Pagination-Ansatz gewechselt werden:

Pagniation über die API aussteuern

Bei großen Hardware-Beständen kann ein optionaler Pagination Parameter per_page aktiviert werden, der die Ergebniszahl beschränkt. Die aktuelle Seite kann per page Parameter gewählt oder über next und prev Attribute im _query Parameter aufgerufen werden.

Beispiel für API Pagination bei den Hardware-Listen

Beispiele sind:

• Aufruf mit deaktivieren Disovery-Daten: /api/2.0/assets/hardware?per_page=100&page=1&discovery=0&search=S4711-123456789

• Aufruf mit aktiven Disovery-Daten und Ansteuerung einer bestimmten Seite: /api/2.0/assets/hardware?per_page=100&page=5&discovery=1&search=S4711-123456789

Komplexe Daten im API Handling

Die API erlaubt die Angabe von sehr einfachen Daten in den Anfragen, wodurch Assets, Stammdaten etc. erstellt oder bearbeitet werden können.

Üblicherweise werden komplexere Daten in gewachsenen Ökosystemen, aber auch Situationen notwendig, wodurch auch das Setzen von Zuordnungen oder das Zurücksetzen von bestehenden Zuordnungen notwendig wird.

Kostenstellen

Seit Release 4.7 können auch Kostenstellen und deren Zuordnung zu den Assets bei POST und PUT-Anfragen übergeben werden. Damit die Kostenstellen übernommen werden können, muss der API Knoten costcenters angegeben werden:

• Anlage einer Gesellschaft (POST-Anfrage auf /base/organizations):

  {
    "name": "EntekSystems GmbH",
      "shortcode": "ESG",
      "enabled": 1,
      "costcenters": [
          {"name": "70100 - IT", "percentage": 99, "rate": 99.22, "date_start": "2024-01-01", "date_end": "2024-12-31"},
          {"name": "70200 - Vertrieb", "percentage": 100, "rate": 19.99, "date_start": "2025-01-01", "date_end": "2025-03-31"}
      ]
  }
  

• Aktualisierung eines Assets (PUT-Anfrage auf /assets/hardware/:inventorynumber):

  {
    "status": "production",
    "location": "frankfurt",
    "owner": "mmustermann",
    "acquisition_value": "1599.00",
    "costcenters": [
      {"name": "70100 - IT", "percentage": 99, "rate": 99.22, "date_start": "2024-01-01", "date_end": "2024-12-31"},
      {"name": "70200 - Vertrieb", "percentage": 100, "rate": 19.99, "date_start": "2025-01-01", "date_end": "2025-03-31"}
   ]
  }
  

Folgende Kostenstellen-Daten sind dabei möglich:

Feld	Beschreibung	Pflichtfeld
name	Name der Kostenstelle über die auch die passende ID intern aufgelöst wird	Ja
percentage	Prozenduale Angabe der Kostenstelle von 0 bis 100	Ja
rate	Mögliche Ratenangabe je Zuordnung	Nein
date_start	Mögliches Startdatum	Nein
date_end	Mögliches Enddatum	Nein

Benutzerdefinierte Felder

Auch seit dem Release 4.7 können benutzerdefinierte Felder für die Kostenstellen-Zuordnungen verwendet werden. Hierdurch können auch in den API-Anfragen weitere Felder genutzt werden und zusätzlich auch die Pflichtfeld-Validierung für diese zusätzlichen benutzerdefinierten Felder angewendet werden.

Zurücksetzen aller Kostenstellen

Um im jeweiligen Fall die Kostenstellen zurücksetzen bzw. leeren zu können, muss nur ein leerer Knoten costcenters übergeben werden.

Software & Lizenzen - Anzeige und Zuordnungen von Benutzern oder Hardware

Seit Release 4.7 ist es möglich die Zuordnungen für Benutzer und Hardware spezifisch für Software und Lizenzen setzen zu können.

• Anzeige der Software Details (Lizenzmetrik Benutzer) (GET-Anfrage auf /assets/software/:id):

  {
      "id": 1,
      "software": "Microsoft Office 2019",
      "licensing": "User",
      "timestamp": "2020-07-22 15:03:28",
      "users": [
          5,
          11,
          16
      ]
  }
  

• Anzeige der Software Details (Lizenzmetrik Workplace) (GET-Anfrage auf /assets/software/:id):

  {
      "id": 4,
      "software": "Windows 11 VL",
      "licensing": "Workplace",
      "timestamp": "2024-04-10 14:50:28",
      "hardware": [
          201004,
          201001,
          201002,
          201003
      ]
  }
  

• Änderung von Benutzer-Zuordnungen (PUT-Anfrage auf /assets/software/:id):

   {
      "name": "Microsoft Office 2019 Standard",
      "users": [
          {"user_id": 1},
          {"user_id": 2, "comment": "Benutzer-Zuweisung"},
      ]
   }
  

Folgende Daten für die Benutzer Zuordnung sind dabei möglich:

Feld	Beschreibung	Pflichtfeld
user_id	ID des spezifischen Benutzer	Ja
comment	Möglicher Kommentar für weitere Informationen	Nein

• Änderung von Asset-Zuordnungen (PUT-Anfrage auf /assets/software/:id):

   {
      "name": "Windows 11 VL",
      "hardware": [
          {"inventorynumber": 100101},
          {"inventorynumber": 100102, "comment": "Hardware-Zuweisung"},
      ]
   }
  

Folgende Daten für die Benutzer Zuordnung sind dabei möglich:

Feld	Beschreibung	Pflichtfeld
inventorynumber	Inventarnummer des spezifischen Assets	Ja
comment	Möglicher Kommentar für weitere Informationen	Nein

Keine Probleme bei falschen Zuordnungen

Falls falsche Zuordnungsdaten wie Benutzerzuordnungen bei Software Objekten, die nur Assets/Hardware erlauben benutzt werden, werden diese ignoriert und nicht verarbeitet.

Gleiche Zuordnungslogik für Lizenzen

Die Logik für das Setzen von Benutzer- oder Asset-Zuordnungen ist für die Lizenzen identisch und kann dort ebenso angewendet werden. Somit können auch API-Aufrufe von Fremdsystemen die Aktualisierung von einzelnen Lizenzen durchführen, wenn diese Information nicht primär in Inventory360 vorliegt.