Erweiterungen

orgaMAX Online: Eigene Erweiterung erstellen

orgaMAX Online bietet eine REST-Schnittstelle an, womit Sie Ihre eigene Anwendung schreiben und an orgaMAX Online anbinden können.

Viele Web-Anwendungen bieten eine direkte API an, um mit anderen Anwendungen zu kommunizieren. orgaMAX Online hat sich dieser Schnittstellen-Logik ebenfalls geöffnet. Im folgenden Beitrag wird kurz beschrieben, wie Sie Ihre eigene Anwendung erstellen, die Tokens ermitteln und testweise eine Liste der Artikel abrufen.

 

API-Key erstellen

Zuerst wechseln Sie bitte in den Marketplace von orgaMAX Online und erstellen Ihre eigene Erweiterung wie im folgenden Screenshot angezeigt.

Im folgenden Dialog geben Sie Ihrer Erweiterung einen aussagekräftigen Namen (in diesem Fall "Coeptum API Zugriff") und definieren eine Callback-URL. Die Callback-URL ist die Webseite unter der Ihre erstelle Erweiterung erreichbar ist.

Klicken Sie bitte den Button API-Key generieren. Nun wird ein individueller API-Key und dazu ein Secret erstellt.  

Für den weiteren Verlauf wird eine individuelle OwnershipID benötigt. Diese Zeichenfolge bekommen Sie, sobald Sie den Button Erweiterung testen klicken. Sobald Ihre App genehmigt wurde und ein orgaMAX-Account diese buchen kann, wird beim Klick auf "Erweiterung öffnen" die Callback-URL mit der OwnershipID des jeweiligen orgaMAX-Accounts aufgerufen. Die Callback-URL sollte nun in einem neuen Tab im Browser geöffnet werden. Achten Sie bitte in der Adresszeile bzw. in der URL auf die Zeichenfolge nach der Variable "/?iid=" in Ihrer Callback-URL.

Bei dieser Zeichenfolge handelt es sich um die OwnershipID. 

 

Scopes

Scrollen Sie bitte weiter nach unten in den Bereich API-Zugriffe. Hier müssen Sie konkreter bestimmen, welche Zugriffe über die Erweiterung in orgaMAX Online gewährt werden. Es muss mindestens ein Zugriff aktiviert werden. Der Screenshot zeigt ein Beispiel, wenn Sie den Vollzugriff auf die Artikel erhalten möchten.

Hinweis: Sobald Sie alle Einstellungen definiert haben, vergessen Sie nicht die Erweiterung als Entwurf zu speichern. Der Button ist oben rechts zu finden.

Token erstellen

Als nächstes wechseln Sie bitte in die API-Dokumentation von orgaMAX Online. Die REST-Schnittstelle kann direkt und unkompliziert über die Seite der API-Dokumentation gegengetestet werden. Um einen Token zu erstellen gehen Sie wie folgt vor.

Klicken Sie bitte rechts auf den Button Authorize. Ein weiteres Fenster zur Anmeldung wird angezeigt. 

Unter Username muss der "API-Key" aus der Erweiterung hinterlegt werden. Im Feld Passwort bitte der "Secret API-Key". Klicken Sie danach auf den Button Authorize

Der Token für die Kommunikation mit den einzelnen Endpunkte muss als nächstes über den spezifischen Endpunkt erstellt werden. 

Öffnen Sie bitte den Bereich /auth/token und klicken Sie auf den Button Try it out.

Der Bereich "Request body" wird geöffnet und erlaubt die Möglichkeit die OwnershipID mit Ihrer eigenen OwnershipID (welche beim Klick auf  "Erweiterung testen" mit der Callback-URL generiert wird) setzen. Klicken Sie danach bitte auf den Button Execute

Nachdem die Abfrage abgesendet wurde, sollte sich der Bereich "Response" aktualisiert haben. Sobald der Response-Code 200 zurückgegeben wurde, sollte der Token auf Basis der vorher angegeben Scopes ausgegeben werden. Kopieren Sie nun den Wert der Variable "Token" aus der JSON-Reponse.

Der Token konnte nun korrekt erstellt werden. Scrollen Sie als nächstes bitte wieder direkt zum Anfang der Schnittstellen-Dokumentation und klicken Sie erneut auf den Button Authorize. Im Bereich BearerAuth kopieren Sie bitte den Token in das Feld "Value" und bestätigen Sie die Eingabe mit Klick auf Authorize

 

Testen der Schnittstelle

Die Umgebung wurde nun aufgebaut. Entsprechend den Berechtigungen, welche über die Scopes freigeben wurden, können Sie nun die passenden Endpunkte der API ansprechen. Im folgenden Beispiel lassen wir uns eine Liste der Artikel als JSON zurückgeben.

Als erster Endpunkt wird die Auflistung der Artikel angeboten:

Klicken Sie auf den Button Try it out und danach wieder auf Execute. Das Ergebnis sollte die Artikel als JSON-Output zurückgeben.

Damit wäre die Grundlage gegeben, eine eigene Erweiterung für orgaMAX Online als Developer zu entwickeln. Beachten Sie, dass Sie Ihre eigene Anwendung zusätzlich in unserem Marketplace einreichen können und somit allen anderen orgaMAX Online Usern zur Verfügung zu stellen.

 

Weitere Informationen zur öffentlichen Schnittstelle

Die obere Anleitung zeigt, wie Sie für sich eine Private App hinterlegen können. Falls Sie eine öffentliche App entwickeln möchten, entfällt der Punkt "Erweiterung testen" beim User, welcher über unseren Store die App aktiviert.

Stattdessen gibt es den Punkt "Erweiterung öffnen". (Beispiel anhand des DATEV-Cloud-Services):

Der Klick öffnet die Callback-URL. Diese gibt wieder als Parameter die "/?iid=" zurück, welches den orgaMAX-Account eindeutig identifiziert. Mit der iid und dem bereits erhaltenen API-Key und Secret können Sie nun für den jeweiligen orgaMAX-Account über die bereits oben genannten Endpunkte den BearerToken generieren. Ab diesem Zeitpunkt können Sie auf alle angeforderten Endpunkte der REST-Schnittstelle zugreifen.