Kurzantwort
Öffne Erweiterungen > Marketplace, erstelle eine eigene Erweiterung und generiere API-Key und Secret. Erstelle anschließend über die API-Dokumentation einen Token mit Deiner Ownership-ID und nutze diesen, um API-Endpunkte per „Try it out“ und „Execute“ zu testen.
ℹ️ Vorabinformationen
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.
❗ Wichtig
Dieser Anleitungsartikel gilt ausschließlich für orgaMAX Buchhaltung. Die Funktion einer API-Anbindung steht in orgaMAX ERP nicht zur Verfügung!
Schritt-für-Schritt-Anleitung
Schritt 1: Herausgeberkonto anlegen
Öffne über das Kachelsymbol oben rechts Erweiterungen. Wechsle in den Abschnitt Erweiterung erstellen und gib die entsprechenden Daten ein.
Schließe die Eingaben mit Speichern ab.
Nun kannst du unter diesem Herausgeberkonto eigene Erweiterungen erstellen.
Schritt 2: Eigene Erweiterungen anlegen
Wechsle im Marketplace auf Eigene Erweiterungen und klicke auf Erweiterung erstellen.
Vergib einen aussagekräftigen Namen und hinterlege eine Callback-URL.
Die Callback-URL ist die Adresse Deiner Anwendung, über die Deine Erweiterung aufgerufen wird.
Schritt 2: API-Key und Secret erstellen
Klicke auf „API-Key generieren“.
orgaMAX erstellt automatisch:
- einen API-Key
- ein Secret
Diese Daten benötigst Du später für die Authentifizierung an der API.
Schritt 3: Ownership-ID ermitteln
Klicke auf „Erweiterung testen“.
Deine Callback-URL öffnet sich in einem neuen Tab.
In der URL findest Du den Parameter /?iid=.
Die Zeichenfolge hinter diesem Parameter ist Deine Ownership-ID.
Sie identifiziert Deinen orgaMAX-Account eindeutig und wird für die Token-Erstellung benötigt.
ℹ️ Hinweis
Sobald Deine 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. Achte 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.
Schritt 4: API-Zugriffe festlegen (Scopes)
Aktiviere im Abschnitt API-Zugriffe die benötigten Berechtigungen.
Du legst fest, auf welche Daten Deine Erweiterung zugreifen darf, zum Beispiel:
- Artikel
- Kunden
- Belege
Aktiviere mindestens einen Zugriff, sonst kann kein Token erstellt werden.
Schritt 5: Erweiterung speichern
Speichere die Erweiterung als Entwurf.
Die Erweiterung steht Dir danach direkt zur Verfügung und kann für API-Anfragen genutzt werden.
Schritt 6: API-Dokumentation öffnen und autorisieren
Öffne die orgaMAX-API-Dokumentation und klicke auf Authorize.
Ein weiteres Fenster zur Anmeldung wird angezeigt.
Trage folgende Daten ein:
- Username: API-Key
- Passwort: Secret
Bestätige die Eingabe mit Authorize.
Schritt 7: Token erstellen
Öffne den Endpunkt /auth/token
Klicke auf Try it out.
Trage im Request Body Deine Ownership-ID ein und klicke auf Execute.
Nachdem die Abfrage abgesendet wurde, sollte sich der Bereich "Response" aktualisiert haben.
Wenn der Response-Code 200 zurückgegeben wird, wurde der Token erfolgreich erstellt.
Kopiere den Token aus der JSON-Antwort.
Schritt 8: Token hinterlegen
Klicke erneut auf Authorize und füge den Token im Bereich BearerAuth ein.
Bestätige die Eingabe mit Authorize.
Du bist jetzt für weitere API-Anfragen authentifiziert.
Schritt 9: API-Endpunkt testen
Wähle einen Endpunkt aus und klicke auf Try it out.
Führe die Anfrage mit Execute aus.
Im Response-Bereich erhältst Du die Daten als JSON, zum Beispiel eine Liste von Artikeln.
Damit ist die API einsatzbereit und Du kannst eigene Anwendungen anbinden.
ℹ️ Informationen zur öffentlichen Schnittstelle
Weitere Informationen zur öffentlichen Schnittstelle
Die obere Anleitung zeigt, wie Du für Dich eine private App hinterlegen kannst. Falls Du eine öffentliche App entwickeln möchtest, 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 kannst Du 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.
Häufige Fragen
Warum funktioniert die Token-Erstellung nicht?
Prüfe:
- API-Key und Secret korrekt eingetragen
- richtige Ownership-ID verwendet
- mindestens ein Scope aktiviert
Fehlende oder falsche Angaben verhindern die Erstellung des Tokens.
Kann ich die Erweiterung direkt verwenden, ohne sie zu veröffentlichen?
Ja. Solange die Erweiterung als Entwurf gespeichert ist, kannst Du sie bereits für Deine eigene Nutzung einsetzen.
Wann muss ich eine Erweiterung im Marketplace einreichen?
Nur wenn andere Nutzer Deine Erweiterung verwenden sollen. Für die eigene Nutzung ist keine Veröffentlichung notwendig.
Was ist der Unterschied zwischen „Erweiterung testen“ und „Erweiterung öffnen“?
„Erweiterung testen“ nutzt Du für Deine eigene Erweiterung.
„Erweiterung öffnen“ wird bei veröffentlichten Erweiterungen verwendet und übergibt die Ownership-ID des jeweiligen Nutzers.
Kann ich die API auch außerhalb der Dokumentation verwenden?
Ja. Du kannst die Endpunkte auch in eigenen Anwendungen oder Tools wie Postman nutzen, sobald Du einen gültigen Token hast.