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

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.

Access Token URL	https://login.microsoftonline.com/Tenant ID/oauth2/v2.0/token
Client ID	Wählen Sie die Client ID (AIOAzureAppID) der Entra-Anwendung aus, die Sie angelegt haben (Einrichtung Azure AD-Anmeldung - ACS - Finance 2024.1#EntraIDOAuth2.0Anwendungen)
Client Secret	Tragen Sie den Geheimschlüssel (AIOAzureAppKeyValue) ein, den Sie bei der Einrichtung erhalten haben (Einrichtung Azure AD-Anmeldung - ACS - Finance 2024.1#ErläuterungdesSkriptes)
Scope	Der Scope setzt sich zusammen aus der Application ID URI der WebClient App-Registrierung, den Berechtigungen .default und offline_access: Beispiel: api://XXXXXX-XXXXXX-XXXXX-XXXXX/.default offline_access Die URI finden Sie in Ihrer AppProperties.json (Einrichtung Azure AD-Anmeldung - ACS - Finance 2024.1#ErläuterungdesSkriptes)

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:

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

Browser not supported