Allgemeine Erläuterungen
Mit der Version 2023.2 steht die erste Version der NEVARIS Finance API zur Verfügung. In der verlinkten Dokumentation können die entsprechenden Endpunkte in der jeweils aktuellen Version eingesehen werden. Zum Test werden wir eine Postman-Collection bereitstellen. Eine detaillierte Beschreibung dazu folgt unten im entsprechenden Kapitel.
Für die ersten Stammdaten wie Debitoren, Kreditoren, Kostenstellen, Adressen oder den Personalstamm stehen Endpunkte bereit. Im Bereich der Bewegungsdaten besteht die Möglichkeit, per API in die Belegschnittstelle zu schreiben.
Filterung eines Endpunktes
Ohne weitere Einschränkungen werden bei der Abfrage eines Endpunktes sämtliche Daten eines Mandanten ausgegeben. Um die Abfragen zu beschleunigen und gezielt Daten auszugeben, stehen verschiedene Filterungsmöglichkeiten zur Verfügung. Die URL des Endpunktes wird dann am Ende mit ?$filter=, dem Feldnamen und dem gewünschten Filteroperator erweitert.
| Operator | Beschreibung | Beispiel (für Artikel) | Ergebnis des Beispiels |
|---|---|---|---|
| eq | Ist gleich | baseUnitofMeasure eq 'STK' | Gibt alle Artikel mit Basiseinheit STK aus. |
| ne | Ist nicht gleich | baseUnitofMeasure ne 'STK' | Gibt alle Artikel ohne die Basiseinheit STK aus. |
| gt | Größer als | unitPrice gt 50 | Gibt alle Artikel aus, bei denen der VK-Preis größer als 50 ist. |
| ge | Größer als oder gleich | unitPrice ge 60 | Gibt alle Artikel aus, bei denen der VK-Preis größer als oder gleich 60 ist. |
| lt | Kleiner als | unitPrice lt 100 | Gibt alle Artikel aus, bei denen der VK-Preis kleiner als 100 ist. |
| le | Kleiner als oder gleich | unitPrice le 150 | Gibt alle Artikel aus, bei denen der VK-Preis kleiner als oder gleich 150 ist. |
| and | Und-Verknüpfung von Filtern | unitPrice le 200 and unitPrice gt 75 | Gibt alle Artikel aus, bei denen der VK-Preis kleiner als oder gleich 200 und der VK-Preis größer als 75 ist. |
| or | Oder-Verknüpfung von Filtern | baseUnitofMeasure eq 'STK' or baseUnitofMeasure eq 'STCK' | Gibt alle Artikel mit Basiseinheit STK oder mit Basiseinheit STCK aus. |
| not | Logische Verneinung | not unitPrice le 15 | Gibt alle Artikel aus, bei denen der VK-Preis nicht kleiner als oder gleich 15 ist. |
| ( ) | Gruppierung von Filtern innerhalb der Abfrage. Ist erforderlich, wenn mehrere Felder gefiltert werden sollen und es zu einem Feld mehrere Werte zum Prüfen gibt. | (baseUnitofMeasure eq 'STK' or baseUnitofMeasure eq 'STCK') and unitPrice gt 100 | Gibt alle Artikel mit Basiseinheit STK oder STCK aus und bei denen der VK-Preis größer als 100 ist. |
Selektieren von einzelnen Feldern eines Endpunktes
Mit der Abfrage eines Endpunktes werden alle zur Verfügung stehenden Felder ausgegeben. Die Felder können allerdings selektiert werden, um nur gezielt Felder auszugeben. Dazu wird der Endpunkt ergänzt um ?$select= und die Felder bzw. mit &$select und den Feldern erweitert, wenn zuvor bereits ein Filter angegeben wurde.
Beispiel 1: ...itemsExtended?$filter=baseUnitOfMeasure eq 'STK'&$select=no,baseUnitOfMeasure,unitPrice
In dem Beispiel werden für alle Artikel, mit der Basiseinheit STK, die Felder no (Artikelnr.), baseUnitOfMeasure (Basiseinheit) und unitPrice (VK-Preis) ausgegeben.
Beispiel 2: ...itemsExtended?$select=no,description,description2,baseUnitOfMeasure,unitPrice
In dem Beispiel werden für alle Artikel die Felder no (Artikelnr.), description (Beschreibung), description2 (Beschreibung2), baseUnitOfMeasure (Basiseinheit) und unitPrice (VK-Preis) ausgegeben.
Technische Einrichtung
Authentifizierung
Zur Authentifizierung wird der Windows-Benutzername benötigt und anstelle des Passwortes ein Webdienst-Zugriffsschlüssel. Dieser ist in der Benutzerkarte zu finden und kann dort nur vom Benutzer selber eingesehen werden. Selbst ein Administrator kann den Webdienst-Zugriffsschlüssel nicht sehen. Sollte noch keiner vergeben worden sein, kann dies über den AssistEdit erfolgen. Zur Auswahl stehen dort die Optionen "Schlüssel läuft niemals ab" oder "Schlüsselablaufdatum". Aus Sicherheitsgründen ist ein Schlüsselablaufdatum empfohlen, d. h. dass nach dem Ablauf ein neuer Schlüssel generiert werden muss und dieser in den angebundenen Systemen aktualisiert werden muss.
Postman-Collection
Postman ist ein Tool, mit dem APIs abgefragt werden können, um die entsprechenden Antworten einsehen zu können. Mit Hilfe von Postman können sogenannte Collections bereit gestellt werden. Diese kann jeder für sich importieren und somit die verfügbaren Endpunkte, nach der Einrichtung der unten beschriebenen Environment, abfragen.
Für die Collection wird eine eingerichtete Umgebung (Environment) benötigt. In der Environment werden vier Felder als Parameter in die API-Endpunkte eingesetzt. Das sind:
| Variable | Type | Initial value | Current value |
|---|---|---|---|
| base_url | default | https://Webserver:OData-Port/Mittelschicht/api/nevaris/finance/v2.0 | https://Webserver:OData-Port/Mittelschicht/api/nevaris/finance/v2.0 |
| company | default | ID des jeweiligen Mandanten. Kann entweder über die Seitenüberprüfung in der Mandantenübersicht ermittelt werden oder über den Endpunkt verfügbare Mandanten innerhalb der Postman-Collection. | ID des jeweiligen Mandanten. Kann entweder über die Seitenüberprüfung in der Mandantenübersicht ermittelt werden oder über den Endpunkt verfügbare Mandanten innerhalb der Postman-Collection. |
| username | default | Windows-Benutzername | Windows-Benutzername |
| pw | secret | Webdienst-Zugriffsschlüssel | Webdienst-Zugriffsschlüssel |
In jeder Environment gibt es die Möglichkeit mit "Current value" einen neuen Wert festzulegen. Das könnte zum Beispiel beim Wechsel eines Mandanten interessant sein. Im Collections-Tab in Postman kann oben rechts über den Dropdown eine Environment ausgewählt werden. Standardmäßig steht dort zunächst "No Environment".