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.

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

Aufbau der URL

Die URL besteht aus der Base-URL https://Webserver:OData-Port/Mittelschicht/api/nevaris/finance/v2.0/companies(ID des Mandanten) und dem jeweiligen Endpunkt aus der oben verlinkten Dokumentation. Die ID des Mandanten kann über die Seitenüberprüfung in der Mandantenübersicht oder alternativ über einen GET-Request des Endpunktes /companies (https://Webserver:OData-Port/Mittelschicht/api/nevaris/finance/v2.0/companies) ermittelt werden.

Authentifizierung

Webdienst-Zugriffsschlüssel

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.

OAuth 2.0

Alternativ zur Authentifizierung mit dem Webdienst-Zugriffsschlüssel gibt es ebenfalls die Möglichkeit sich über OAuth 2.0 zu authentifizieren. Für diese Authentifizierungsmethode werden unterschiedliche Werte benötigt, die im Folgenden beschrieben sind.

Weitere Informationen dazu finden Sie in der Hilfe von Business Central.

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:

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".