orgaMAX Buchhaltung bietet eine REST-Schnittstelle an, womit Sie Ihre eigene Anwendung schreiben und an orgaMAX Buchhaltung anbinden können.
Vorab: Neben der Möglichkeit, eigene Erweiterungen zu erstellen, gibt es bereits eine Vielzahl an fertigen kostenfreien und kostenpflichtigen Erweiterungen für orgaMAX Buchhaltung. Diese finden Sie im Menüpunkt Erweiterungen → Marketplace.
Dieser Anleitungsartikel gilt ausschließlich für orgaMAX Buchhaltung. Die Funktion einer API-Anbindung steht in orgaMAX ERP nicht zur Verfügung!
Viele Web-Anwendungen bieten eine direkte API an, um mit anderen Anwendungen zu kommunizieren. orgaMAX Buchhaltung 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 Buchhaltung 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 Ownership-ID 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 Ownership-ID des jeweiligen orgaMAX-Accounts aufgerufen. Die Callback-URL sollte jetzt 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 Ownership-ID.
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 Buchhaltung 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 Buchhaltung. Die REST-Schnittstelle kann direkt und unkompliziert über die Seite der API-Dokumentation gegen getestet 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 Endpunkten 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 Ownership-ID mit Ihrer eigenen Ownership-ID (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 indessen aufgebaut. Entsprechend den Berechtigungen, welche über die Scopes freigeben wurden, können Sie jetzt 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 Buchhaltung als Developer zu entwickeln. Sobald die Erweiterung im Entwurfsmodus bei Ihnen gespeichert ist, können Sie diese direkt live verwenden.
Beachten Sie, dass Sie Ihre eigene Anwendung zusätzlich in unserem Marketplace einreichen können und somit allen anderen orgaMAX Buchhaltung Anwendern zur Verfügung stellen. Bitte nutzen Sie die Funktion "Erweiterung einreichen" nur, wenn Ihre Erweiterungen für andere orgaMAX Buchhaltung Anwender zur Verfügung gestellt werden soll. Andernfalls ist es nicht notwendig, dass Sie diese einreichen.
Der Review-Prozess kann bis zu 7 Tage dauern. Weiterhin beachten Sie, dass alle relevanten Felder für die Erweiterung korrekt gefüllt sind, wie "Detaillierte Beschreibung", API-Zugriffe und "Review Anmerkungen".
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 Anwender, 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.