Eine API in der Sage 100 stellt immer Funktionalität für bestimmte Szenarien zur Verfügung. Sie besteht aus

Endpunkten (immer mit ‘ept’ am Anfang des Namens als Präfix), um die relevanten Ressourcen zu bearbeiten oder abzurufen
und zusätzlich erforderliche Funktionen, die in der Regel dazu dienen, notwendige Zusatzinformationen zu lesen.

Datenreferenzen

Ein wichtiges Feature sind Datenreferenzen. Manche Felder einer Ressource dürfen nur mit Werten aus einer vorgegebene Menge gefüllt werden. Diese können über die Anfrage gegen eine Datenreferenz ermittelt werden. Datenreferenz-Ressourcen beginnen in der Url immer mit dem Präfix ‘dtr’. Aus der API-Referenz ist ersichtlich, welche Felder mit welcher Datenreferenz verknüpft sind. Dabei gibt es folgende Ausprägungen:

Der Wert MUSS ein Wert aus der Datenreferenz sein. Es wird Provider-seitig validiert, dass diese Bedingung eingehalten wird.
Der Wert KANN ein Wert aus der Datenreferenz sein. Der Client kann die Datenreferenz verwenden, um z.B. Vorschlagswerte für die Eingabe zu erhalten.

Datenreferenzen können nur via Query gelesen werden. Sie bestehen in der Regel aus einer Collection von Elementen, die jeweils die Bezeichnung und den zu verwendeten Wert enthalten. Welches das Feld mit dem Wert ist, in der API-Referenz dokumentiert.

Beispiel:

Für das Feld ‘steuerklasse' der Ressource ‘eptArtikel.Sage.API’ muss mit einem Wert der Datenreferenz 'dtrSteuerklasse.Sage.System’ gefüllt werden.

Bei der Anfrage einer Datenreferenz muss immer der Http-Header 'X-ApiEndpoint' mit dem Element, für den die Datenreferenz gelesen wird, gefüllt sein.

Die Anfrage

GET https:[basurl]/sdata/ol/apiArtikel.Sage.API/OLDemoReweAbfD;123/dtrSteuerklasse.Sage.System
X-ApiEndpoint: eptArtikel.Sage.API

liefert folgendes Ergebnis:

{
  "$resources": [
    {
      "Steuerklasse": 0,
      "Bezeichnung": "steuerfrei"
    },
    {
      "Steuerklasse": 1,
      "Bezeichnung": "Normalsatz"
    },
    {
      "Steuerklasse": 2,
      "Bezeichnung": "Ermäßigter Satz"
    },
    {
      "Steuerklasse": 3,
      "Bezeichnung": "AZR steuerfrei"
    },
    {
      "Steuerklasse": 4,
      "Bezeichnung": "AZR Normalsatz"
    },
    {
      "Steuerklasse": 5,
      "Bezeichnung": "AZR Ermäßigter Satz"
    }
  ]
}

In der API-Referenz ist dokumentiert, dass der Inhalt des Feldes 'Steuerklasse' für das Füllen des Feldes ‘steuerklasse' der Ressource ‘eptArtikel.Sage.API’ verwendet werden muss.

Suchen von Ressourcen

Sofern eine direkte Suche auf einem Endpunkt nicht möglich ist, stellt die API zusätzliche Funktionen zum Auflisten und Finden von Datensätzen zur Verfügung. Dies ist beispielsweise bei dem Endpunkt ‘eptVKBeleg.Sage.API’ der API ‘apiBelegerfassung.Sage.API’ der Fall. Über den Endpunkt 'eptVKBelegSuche.Sage.API' ist eine Auflistung und Suche möglich. Das Suchergebnis beinhaltet immer den Primärschlüssel der gesuchten Ressource. Die Vorgehensweise ist i.d.R. immer:

Suchen der Ressource über die Suchanfrage
Lesen der Ressource über den Endpunkt der Ressource

Sage 100

4.1. Organisation der Sage 100 API

Datenreferenzen

Suchen von Ressourcen

Related content