Schnittstellen (API)
Über die Schnittstellen (APIs) von Netxp-Verein können Sie eigene Anwendungen oder Skripte anbinden, um Vereinsdaten auszutauschen — etwa ein Skript, das neue Mitgliedsanträge von der Vereinswebsite übernimmt, eine schlanke Verwaltungsseite für den Vorstand oder ein Mitgliederbereich auf der Vereinshomepage.
Diese Seite zeigt, welche Schnittstelle zu Ihrem Vorhaben passt, und enthält alle Verbindungsdaten, die Sie für den Einstieg brauchen. Die einzelnen Methoden mit ihren Parametern und Rückgabewerten sind direkt in der jeweiligen Swagger-Oberfläche beschrieben.
Jeder Zugriff auf eine Schnittstelle setzt einen eingerichteten API-Client voraus. Dort legen Sie fest, wie sich Ihre Anwendung anmeldet und worauf sie zugreifen darf. Voraussetzung dafür ist Netxp-Verein Pro.
Diese Seite richtet sich an Personen, die eine Anbindung technisch umsetzen — Entwickler, Webmaster, Dienstleister und technisch versierte Vereinsadministratoren. Die Begriffe Client-ID, Secret, Token und Scope sind unter Grundbegriffe auf einen Blick erklärt.
Welche Schnittstelle für mein Vorhaben?
| Ihr Vorhaben | Schnittstelle | Beispiele |
|---|---|---|
| Eigener Mitgliederbereich auf der Vereinswebsite | MO-API (MitgliederOnline) | Eigenes Profil ansehen, Kontaktdaten selbst ändern, Termine und freigegebene Dateien anzeigen |
| Eigene Verwaltungsoberfläche für Vorstand, Abteilungsleiter oder Geschäftsstelle | VO-API (VereinOnline) | Vereinfachte Mitgliederliste einer Abteilung, Gruppen anzeigen, eigene Tabellen pflegen |
| Skript oder Dienst ohne eigene Oberfläche — Import, Abgleich, nächtliche Aufgaben | Verein-API | Mitgliedsanträge von der Website anlegen, Kontaktdaten mit einem Fremdsystem abgleichen, Beiträge oder Ehrungen zuweisen |
Die MO-API arbeitet immer im Namen eines angemeldeten Mitglieds mit freigeschaltetem MitgliederOnline-Zugang. Für Hintergrunddienste ohne Mitglieder-Anmeldung ist sie nicht gedacht — verwenden Sie dafür die Verein-API.
- Wie der Verein MitgliederOnline einrichtet und die Zugänge der Mitglieder verwaltet, beschreibt MitgliederOnline (Verein) — insbesondere Web-Zugänge.
- Wie sich Mitglieder anmelden und was sie im Portal tun können, beschreibt MitgliederOnline (Webportal) — insbesondere Login und Registrierung.
Verbindungsdaten
Anmeldung (für alle Schnittstellen)
Alle drei Schnittstellen melden sich über denselben Anmeldedienst (IdentityServer) von Netxp-Verein an. Er arbeitet nach den Standards OAuth 2.0 und OpenID Connect.
| Angabe | Wert |
|---|---|
| Issuer | https://zugang.netxp-verein.de/ |
| Authorization URL | https://zugang.netxp-verein.de/connect/authorize |
| Token URL | https://zugang.netxp-verein.de/connect/token |
| Revocation URL | https://zugang.netxp-verein.de/connect/revocation |
| Discovery-Dokument | https://zugang.netxp-verein.de/.well-known/openid-configuration |
| Client-Authentifizierung | client_secret_post (im Formular) oder client_secret_basic (HTTP-Header) |
| Gültigkeit eines Access Tokens | 3600 Sekunden (1 Stunde) |
Wie Sie damit ein Token anfordern, zeigt die Seite Authentifizierung.
Die drei Schnittstellen
| Angabe | MO-API | VO-API | Verein-API |
|---|---|---|---|
| Swagger-Oberfläche | moapi.netxp-verein.de/swagger | voapi.netxp-verein.de/swagger | vapi.netxp-verein.de/swagger |
| OpenAPI-Beschreibung | /swagger/v1/swagger.json | /swagger/v1/swagger.json | /swagger/verein/swagger.json |
| Basis-URL | https://moapi.netxp-verein.de | https://voapi.netxp-verein.de | https://vapi.netxp-verein.de |
| Pfade beginnen mit | /api/app/ | /api/app/ | /api/verein/ |
| Ressource im API-Client | Mitglieder Online API | Verein Online API | Verein API |
| Scopes beginnen mit | mo_ | vo_ | va_ |
| Anmeldung mit | E-Mail-Adresse + Passwort des Mitglieds, Login über Browser | API-Schlüssel, VereinsID + Benutzername + Passwort, Login über Browser | API-Schlüssel, VereinsID + Benutzername + Passwort, Client Credentials, Login über Browser |
| Es gelten die Rechte von | angemeldetem Mitglied | API-Benutzer bzw. angemeldetem Benutzer | API-Benutzer bzw. angemeldetem Benutzer |
| Redirect-URI für die Swagger-Oberfläche | https://moapi.netxp-verein.de/swagger/oauth2-redirect.html | https://voapi.netxp-verein.de/swagger/oauth2-redirect.html | https://vapi.netxp-verein.de/swagger/oauth2-redirect.html |
| Beispiel im Schnellstart | Eigene Mitgliedsdaten abrufen | Mitglieder suchen | Mitglieder abrufen |
Welche Anmeldung bei welcher Ressource möglich ist und wessen Rechte gelten, beschreibt die Seite API-Clients unter Welche Zugriffsart ist mit welcher Ressource möglich? und Wer meldet sich an?.
Scopes
Scopes legen fest, worauf ein Token zugreifen darf. Fordern Sie nur
Scopes an, die dem API-Client im Reiter
Scopes zugewiesen sind. Welche
Methode welchen Scope benötigt, sehen Sie in der Swagger-Oberfläche.
Die Standard-Scopes openid, profile, email und offline_access
sind unter
Welche Scopes gibt es?
beschrieben.
MO-API
| Scope | Bereich |
|---|---|
mo_club | Vereinsdaten |
mo_member | Mitgliederdaten |
mo_member_new | Neues Mitglied |
mo_scheduler | Terminplaner |
mo_file | Eigene Dateien |
mo_form | Eigene Formulare |
mo_dyntable | Eigene Tabellen |
mo_trainer | Übungsleiter |
mo_trainer_accounting | Übungsleiterabrechnung |
mo_trainer_contract | Übungsleiterverträge |
VO-API
| Scope | Bereich |
|---|---|
vo_member | Mitgliedsdaten |
vo_member_form | Mitgliedermasken |
vo_group | Gruppen |
vo_division | Sparten |
vo_fee | Beiträge |
vo_distinction | Ehrungen |
vo_dutybook | Tätigkeitsberichte |
vo_dyntable_data | Eigene Tabellen Daten |
vo_dyntable_groups | Eigene Tabellen Gruppen |
vo_dyntable_schema | Eigene Tabellen Schema |
vo_custom_design | Eigene Ansichten |
Verein-API
| Scope | Bereich |
|---|---|
va_beitrag | Beitragsdaten |
va_ehrung | Ehrungsdaten |
va_mitglied | Mitgliedsdaten |
va_mitglied_beitrag | Mitgliedsbeitragsdaten |
va_mitglied_ehrung | Mitgliedsehrungsdaten |
va_mitglied_eigenes_feld | Mitgliedseigene Felder |
va_mitglied_sparte | Mitgliedsspartendaten |
va_sparte | Spartendaten |
va_eigene_tabellen_daten | Eigene Tabellen Daten |
va_eigene_tabellen_gruppen | Eigene Tabellen Gruppen |
va_eigene_tabellen_schema | Eigene Tabellen Schema |
Mit der Swagger-Oberfläche arbeiten
Die Swagger-Oberfläche ist die vollständige Beschreibung einer Schnittstelle und dessen Funktionen/Methoden. Sie ist nach Bereichen gegliedert (z. B. Beitrag, Mitglied, Division). Ein Klick auf eine Methode zeigt
- die Beschreibung der Methode,
- die Parameter (Pfad, Abfrage, Inhalt),
- den Aufbau der Antwort (Schema) und
- die möglichen Statuscodes.
Die vollständige Adresse eines Aufrufs setzt sich aus der
Basis-URL und dem Pfad aus der Swagger-Oberfläche zusammen,
z. B. https://vapi.netxp-verein.de + /api/verein/mitglied.
Direkt ausprobieren
Sie können Methoden direkt in der Swagger-Oberfläche aufrufen — ganz ohne eigenen Code.
- API-Client vorbereiten:
- Zugriffsart Login über Browser ankreuzen
- die Redirect-URI der Swagger-Oberfläche (siehe Die drei Schnittstellen) im Reiter URIs eintragen
- die benötigten Scopes zuweisen
- speichern und einige Minuten warten
- In der Swagger-Oberfläche oben rechts auf „Authorize" klicken.
client_idundclient_secretIhres API-Clients eintragen.- Nur die Scopes anhaken, die dem API-Client zugewiesen sind, und erneut „Authorize" klicken.
- Auf der Anmeldeseite von Netxp-Verein anmelden:
- MO-API: mit E-Mail-Adresse und Passwort eines Mitglieds mit freigeschaltetem MitgliederOnline-Zugang.
- VO-API und Verein-API: mit Ihren Netxp-Verein-Benutzerdaten (VereinsID, Benutzer, Passwort) oder mit dem API-Schlüssel des API-Benutzers dieses Clients. Es gelten die Rechte dieses Benutzers bzw. API-Benutzers.
- Zurück in der Swagger-Oberfläche eine Methode aufklappen, auf „Try it out" und anschließend auf „Execute" klicken.
Diese Meldung (invalid_request, Code ID2051) erscheint, wenn
mindestens ein angehakter Scope dem API-Client nicht zugewiesen
ist. Haken Sie ihn ab oder weisen Sie ihn dem Client zu. Zugewiesene
Scopes wirken erst nach einigen Minuten — siehe
Speichern und Wirksamwerden.
Jeder Aufruf — auch „Execute" in der Swagger-Oberfläche — wirkt
sofort auf die echten Daten Ihres Vereins. Beginnen Sie mit
lesenden Methoden (GET) und weisen Sie dem API-Client zunächst nur
lesende Scopes und Benutzerrollen mit Leserechten zu. Methoden, die
Daten anlegen, ändern oder löschen (POST, PUT, DELETE), führen
Sie erst aus, wenn Sie die Wirkung kennen.
OpenAPI-Beschreibung weiterverwenden
Die OpenAPI-Beschreibung (swagger.json, Links in
Die drei Schnittstellen) enthält alle
Methoden in maschinenlesbarer Form. Sie können sie
- in Postman oder ähnliche Werkzeuge importieren (Import → Link einfügen) — tragen Sie dort im Reiter Authorization den Typ OAuth 2.0 mit Authorization URL, Token URL, Client-ID, Secret und Scopes ein;
- mit Generatoren wie NSwag oder OpenAPI Generator in fertigen Client-Code für Ihre Programmiersprache umwandeln.
Wie geht es weiter?
- Schnellstart — der erste Aufruf je Schnittstelle in wenigen Minuten
- Authentifizierung — alle Anmeldewege, Umgang mit Tokens und sichere Ablage der Zugangsdaten
- Fehlerbehandlung — Statuscodes und Fehlermeldungen richtig auswerten
Verwandte Themen
- API-Clients — API-Client einrichten, Zugriffsart, Scopes, Secret und API-Schlüssel
- Benutzerrollen — Rechte des API-Benutzers
- Netxp-Verein Pro — Voraussetzung für API-Clients
- MitgliederOnline (Verein) — Einrichtung von MitgliederOnline und Web-Zugänge der Mitglieder
- MitgliederOnline (Webportal) — Anmeldung und Funktionen für Mitglieder