API-Schnittstelle zu VereinOnline
Die API-Schnittstelle ermöglicht den Abruf der Daten per JSON. Der Web-Server fragt dabei im Hintergrund den VereinOnline-Server an. Die API-Schnittstelle muss zunächst freigeschaltet sein.
Anschließend benötigt Sie einen entsprechend berechtigten Benutzerzugang (wie ein normales Mitglied mit Userlogin, Passwort un einer zugeordneten Rollen mit den gewünschten Rechten, z.B. Veranstaltungen lesen usf.).
Es existiert zudem ein WordPress-Plugin, welches genau dieses API nutzt und selbst WordPress-Tags bereitstellt.
Die Erklärung erfolgt im Nachfolgendem anhand von PHP, dies ist aber nur beispielhaft zu sehen.
Alle Parameter müssen utf8-codiert übergeben werden.
Nutzung per PHP - Variante 1: Übergabe der Parameter als JSON-Daten
$url = "https://www.vereinonline.org/IHRVEREIN/"; $usr = "..."; // der API-Benutzername mit entsprechenden Rollenrechten ("admin" ist nicht zulässig!) $pwd = "..."; // das zugehörige Passwort $token="A/$usr/".md5($pwd); print_r(VereinOnlineRequest($url, "GetMembers", array("suche"=>utf8_encode("müller")), $token)); function VereinOnlineRequest($url, $funktion, $daten, $token) { $curl=curl_init(); curl_setopt($curl, CURLOPT_URL, $url."?api=$funktion"); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_HTTPHEADER, array("Content-Type: application/json", "Authorization: $token")); curl_setopt($curl, CURLOPT_POST, 1); curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($daten)); return json_decode(curl_exec($curl)); }
Nutzung per PHP - Variante 2: Übergabe der Parameter als Aufrufparameter
$url = "https://www.vereinonline.org/IHRVEREIN/"; $usr = "..."; // der API-Benutzername mit entsprechenden Rollenrechten ("admin" ist nicht zulässig!) $pwd = "..."; // das zugehörige Passwort $token="A/$usr/".md5($pwd); print_r(VereinOnlineRequest($url, "GetMembers", array("suche"=>utf8_encode("müller")), $token)); function VereinOnlineRequest($url, $funktion, $daten, $token) { $url.="?api=$funktion&token=$token"; foreach($daten as $k=>$v) $url.="&$k=".urlencode($v); $curl=curl_init(); curl_setopt($curl, CURLOPT_URL, $url); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); return json_decode(curl_exec($curl)); }
Nutzung per JavaScript: (mit Hilfe der jQuery-Bibliothek):
jQuery.ajax( { type: 'GET', crossDomain: true, url: ' https://www.vereinonline.org/IHRVEREIN/?api=GetMembers&token=...', success: function(result) { ... }, error: function(r,e,txt) { ... } });
Nutzung per PowerShell: (Bereitgestellt von einem VereinOnline-Nutzer)
PowerShellSample.ps1
Funktionen der Schnittstelle
Abruf Mitgliederliste: "GetMembers"
Art | Name | Beschreibung |
Methodenname | GetMembers (analog "GetContacts" für externe Kontakte) | |
Übergabeparameter | felder | optional: Liste der zusätzlich angefragten Felder, auch "rollen","gruppen","beitraege","beitraegewert" und Extrafelder "key_..." ohne Angabe werden standardmäßig geliefert: id,mandant,vorname,nachname,firma,p_freigabe,g_freigabe,freigabe,foto |
filter | optional: Folgende Möglichkeiten:
| |
rolle | optional: Einschränkung auf eine Rolle, z.B. "Mitglieder" | |
gruppe | optional: Einschränkung auf eine Gruppe, z.B. "Tennis" | |
sort | optional: Angabe von Feldern zur Sortierung. Standard: nachname, vorname | |
suche | optional: Suchbegriff, sucht in Vorname und Nachname | |
plz | optional: PLZ, gibt die Geoposition des Mitglieds und die Luftlinie in km zurück (Geodaten müssen aktiviert sein) Übergabe: ##### oder D-##### oder A-#### oder CH-#### | |
km | optional: Kilometer-Wert, schränkt die Rückgabe der PLZ-Suche auf den km-Radius ein | |
Rückgabeparameter | Array | Liste Datensätze
|
zum Beispiel alle Mitglieder mit der Rolle "Mitglied", deren Nachname mit "Mü" beginnen:
$parameter=array(); $parameter["filter"]="nachname LIKE 'Mü%'"; $parameter["rolle"]="Mitglied"; $daten=VereinOnlineRequest($url, "GetMembers", $parameter, $token); if ($daten->error!="") { echo $daten->error."<BR>"; } else { foreach($daten as $mitglied) { echo "ID=".$mitglied->id.", "; echo "Name=".$mitglied->vorname." ".$mitglied->nachname."<BR>"; } }
Optionale Konfigurierbarkeit in Administration/Basiskonfiguration/Parameter:
- Einschränkung der gelieferten Felder, andere Felder werden nicht zurückgegeben selbst wenn über das API angefordert:
api.getmembers.felder.freigegeben=vorname,nachname,p_email,g_email
- Weitere Bedingungen:
api.getmembers.datensatz.freigegeben=key_ABC=123|branche=Finanzen
- Ergänzende Felder, die das API zurückliefern soll (analog "felder" aus der Anfrage):
api.getmembers.felder=p_email,g_email
- Mitglieds-Feld, das nicht leer sein darf:
api.getmembers.filter=mitgliedsnummer
Abruf aller Daten eines Mitglieds: "GetMember"
Art | Name | Beschreibung |
Methodenname | GetMember (analog "GetContact" für externe Kontakte) | |
Übergabeparameter | id | ID der Mitglieds |
Rückgabeparameter | Objekt | Ein Objekt
|
Zum Beispiel das Mitglied mit der ID=12345:
$daten=VereinOnlineRequest($url, "GetMember", array("id"=>12345), $token); if ($daten->error!="") { echo $daten->error."<BR>"; } else { echo "ID=".$daten->id.", "; echo "Vorname=".$daten->vorname.", "; echo "Nachname=".$daten->nachname.", "; echo "Strasse=".$daten->p_strasse.", "; echo "Ort=".$daten->p_ort."<BR>"; //... viele weitere Daten! }
Optionale Konfigurierbarkeit in Administration/Basiskonfiguration/Parameter:
- Einschränkung der gelieferten Felder, andere Felder werden nicht zurückgegeben selbst wenn über das API angefordert:
api.getmembers.felder.freigegeben=vorname,nachname,p_email,g_email
- Weitere Bedingungen:
api.getmembers.datensatz.freigegeben=key_ABC=123|branche=Finanzen
Anlage eines Mitglieds: "CreateMember"
Art | Name | Beschreibung |
Methodenname | CreateMember | |
Übergabeparameter | vorname nachname ... key_FELDNAME1 rolle gruppe | Daten |
Rückgabeparameter | id des neuen Datensatzes |
Ändern eines Mitglieds: "UpdateMember"
Art | Name | Beschreibung |
Methodenname | UpdateMember | |
Übergabeparameter | id | ID des zu ändernden Datensatzes |
vorname nachname ... key_FELDNAME1 rollen=[-]Name1,.. gruppen=[-]Name1,.. beitraege=[-]Name1,.. | Daten |
Abruf Veranstaltungsliste: "GetEvents"
Art | Name | Beschreibung |
Methodenname | GetEvents | |
Übergabeparameter | typ | optional 1=öffentliche Veranstaltung, 11=interne Veranstaltung 100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge) |
filter | optional: SQL-Ausdruck zur Einschränkung der Datensätze | |
jahr | optional: "2020": nur aus dem Jahr 2020 (beispielhaft) "zukunft": für alle zukünftigen Termine "zukunft12" für alle ab in 12 Monaten "aktuellermonat" "vergangenheit": für vergangene Termine "aktuellesjahr" "naechstermonat" | |
gruppenid | optional: "1234": nur Gruppentermine der angegebenen Gruppen-ID 1234 (beispielhaft) "1234+" es werden auch alle Veranstaltungen der Untergruppen zurückgegeben. "#gruppenid#" es wird die Gruppen-ID aus dem Url-Parameter "id" entnommen. | |
monat | optional: nur Termine aus dem angegebenen Monat (Format: "YYYYMM") | |
abmonat | optional: nur Termine ab dem angegebenen Monat (Format: "YYYYMM") | |
kostenfremd | optional: nur ein Kostenbereich (z.B. "1000-2000") | |
search | optional: Suchbegriff, der in den Feldern "titel", "beschreibung", "ort" sucht | |
restriction | optional: Angabe von Einschränkungen: feldname=wert;... | |
sichtbar | optional: "alle" = die Veranstaltungen aller Sichtbarkeiten werden geliefert | |
Rückgabeparameter | Array | Liste Datensätze
|
Hinweis: Es werden nur öffentliche Termine geliefert (Feld "Sichtbarkeit")!
$daten=VereinOnlineRequest($url, "GetEvents", array("jahr"=>"zukunft"), $token); if ($daten->error!="") { echo $daten->error."<BR>"; } else { foreach($daten as $veranstaltung) { echo "ID=".$veranstaltung->id.", "; echo "Datum=".$veranstaltung->datum.", "; echo "Titel=".$veranstaltung->titel."<BR>"; } }
Optionale Konfigurierbarkeit in Administration/Basiskonfiguration/Parameter:
- Angabe der Sortierung:
api.getevents.order=datum DESC, zeit
- Fester Titel, um den echten Titel zu verbergen
api.getevents.titel=belegt
Abruf aller Daten einer Veranstaltung: "GetEvent"
Art | Name | Beschreibung |
Methodenname | GetEvent | |
Übergabeparameter | id | ID der Veranstaltung |
typ | optional 1=öffentliche Veranstaltung, 11=interne Veranstaltung 100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge) | |
Rückgabeparameter | Objekt | Ein Objekt
|
Zum Beispiel die Veranstaltung mit der ID=2345:
$daten=VereinOnlineRequest($url, "GetEvent", array("id"=>2345), $token); if ($daten->error!="") { echo $daten->error."<BR>"; } else { echo "ID=".$daten->id.", "; echo "Datum=".$daten->datum.", "; echo "Titel=".$daten->titel.", "; echo "Ort=".$daten->ort.", "; echo "Zeit=".$daten->zeit."<BR>"; //... viele weitere Daten! }
Abruf von Anmeldungen: "GetRegistrations"
Art | Name | Beschreibung |
Methodenname | GetRegistrations | |
Übergabeparameter | id | ID der Veranstaltung |
Rückgabeparameter | Array | Liste Datensätze:
|
Ändern einer Anmeldung: "ChangeRegistration"
Art | Name | Beschreibung |
Methodenname | ChangeRegistration | |
Übergabeparameter | anmeldeid | ID der Anmeldung |
status | Neuer Status der Anmeldung (0=angemeldet, 1=angemeldet, 3=auf Warteliste) | |
anmerkung | Text, der als Anmerkung ergänzt wird | |
kurs | ="1": Passt die Anmeldung in allen verbundenen Serienterminen an |
Abruf von Anmeldungen: "GetCalendar": zentralen Kalender-Daten eines Monats
Art | Name | Beschreibung |
Methodenname | GetCalendar | |
Übergabeparameter | m | Monat |
y | Jahr | |
typ | optional 1=öffentliche Veranstaltung, 11=interne Veranstaltung 100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge) | |
Rückgabeparameter | offset | 1. Tag des Monats (0…6) |
tage | Anzahl Tage des Monats | |
text | "Monatsname Jahreszahl" | |
tag | Liste von Tagen, an denen Veranstaltungen stattfinden | |
id | Liste der IDs zu den Veranstaltungen aus "tag" | |
datum | Liste zu Datumswerten | |
titel | Liste der Veranstaltungstitel (bei mehr als 1 Termin pro Tag: "X Termine") |
Hinweis: Es werden nur öffentliche Termine geliefert (Feld "Sichtbarkeit")!
Anlage eines Mitglieds: "CreateEvent"
Art | Name | Beschreibung |
Methodenname | CreateEvent | |
Übergabeparameter | datum titel ... | Daten der Veranstaltung |
key_FELDNAME1 key_... | Extrafelder der Veranstaltung | |
anmeldung1=... anmeldung2=... | Anlage von "Extrafelder für die Anmeldung bei der Veranstaltung" Format: Beschreibung|Feldname|Feldtyp|FeldtypDetails|Pflicht Beispiel: anmeldung1=Extra+1|extra1 anmeldung2=Extra+2|extra2|select|AAA~BBB~CCC|1 | |
Rückgabeparameter | id des neuen Datensatzes |
Ändern eines Mitglieds: "UpdateEvent"
Art | Name | Beschreibung |
Methodenname | UpdateEvent | |
Übergabeparameter | datum titel ... key_FELDNAME1 | Daten |
kurs | ="1": Passt die Veranstaltung in allen verbundenen Serienterminen an |
Abruf aller öffentlichen Newsletter: "GetNewsletter"
Art | Name | Beschreibung |
Methodenname | GetNewsletter | |
Rückgabeparameter | Array | Liste aller Datensätze:
|
Abruf aller öffentlichen Newsletter-Beiträge: "GetNewsletterBeitrag"
Art | Name | Beschreibung |
Methodenname | GetNewsletter | |
Übergabeparameter | id | optional: ID des Beitrags |
Rückgabeparameter | Array | Liste aller Datensätze:
|
Anlage eines Newsletter-Abonnenten: "CreateSubscriber"
Art | Name | Beschreibung |
Methodenname | CreateSubscriber | |
Übergabeparameter | vorname nachname g_email gruppe | Daten |
Rückgabeparameter | "error"- oder "ok"-Wert |
Abruf aller aktuellen Meldungen: "GetNews"
Art | Name | Beschreibung |
Methodenname | GetNews | |
Übergabeparameter | alle=ja | optional: liefert auch bereits (gültig bis) abgelaufene News. |
maximal | optional: maximale Anzahl der News | |
id | optional: nur diese ID laden | |
condition | optional: Sie haben folgende Möglichkeiten:
| |
Rückgabeparameter | Array | Liste Datensätze
|
Hinweis: Es werden nur gültige öffentliche News zurückgegeben (gültig ab/bis, keine Rollen/Gruppen-Einschränkung, extern sichtbar)
Abruf von Rechnungsdaten: "GetRechnung"
Art | Name | Beschreibung |
Methodenname | GetRechnung | |
Übergabeparameter | id | ID der Rechnung |
Rückgabeparameter | Objekt | Ein Objekt
|
Abruf aller Gruppen: "GetGroups"
Art | Name | Beschreibung |
Methodenname | GetGroups | |
Übergabeparameter | typ | optional: ="v": nur Veranstaltungs-Gruppen |
Rückgabeparameter | Array | Liste Datensätze:
|
Abruf von Bildergalerie: "GetPictures"
Art | Name | Beschreibung |
Methodenname | GetPictures | |
Rückgabeparameter | Array | Liste Datensätze:
|
Abruf von Shop-Artikeln: "GetShop"
Art | Name | Beschreibung |
Methodenname | GetShop | |
Übergabeparameter | maximal | optional: maximale Menge Datensätze |
kategorie | optional: Filter auf Kategorie | |
mandant | optional: Filter auf eine Einhet (nur VerbandOnline) | |
Rückgabeparameter | Array | Liste Datensätze
|
Abruf der flexiblen Listen-Defintionen: "GetLists"
Art | Name | Beschreibung |
Methodenname | GetLists | |
Rückgabeparameter | Array | Liste Datensätze:
|
Abruf von Daten aus einer flexiblen Liste: "GetList"
Art | Name | Beschreibung |
Methodenname | GetList | |
Übergabeparameter | id | ID der flexiblen Liste |
filter | optional: ein Wert im Datensatz, z.B. "mitglied=1234" | |
return | optional: "object": gibt die Daten als Object (Key-Value-Array) zurück | |
Rückgabeparameter | Array | Liste aller Datensätze:
|
Anlage eines Datensatzen in einer flexible Liste: "CreateListData"
Art | Name | Beschreibung |
Methodenname | CreateListData | |
Übergabeparameter | id | ID der flexiblen Liste |
POST-Daten | FELDNAME1=WERT &FELDNAME2=WERT &DATEIFELDNAME1=filename|content &DATEIFELDNAME2[]=filename|content &DATEIFELDNAME2[]=filename|content | |
Rückgabeparameter | id des neuen Datensatzes, bzw. "error" falls die Listen-ID nicht existiert |
Prüfung einer Platzbelegung: "CheckPlace"
Art | Name | Beschreibung |
Methodenname | CheckPlace | |
Übergabeparameter | platz | Platzname oder Platz-ID |
beginn | Beginn-Zeitpunkt: YYYY-MM-DD HH:MM | |
ende | Ende-Zeitpunkt: YYYY-MM-DD HH:MM | |
Text | Rückgabeparameter | "-" falls frei ansonsten "belegt" oder Detailsinfo |
Prüfung eines Logins
Methode 1:Art | Name | Beschreibung |
Methodenname | VerifyLogin | |
Übergabeparameter | user | Userlogin |
password | Passwort | |
result | ="id": als Ergebnis wird die "id" geliefert statt vorname/nachname ="nameemail": ale Ergebnis wird ein Array mit "name" und "email" geliefert | |
Rückgabeparameter | Array | falls Fehler leerer String, ansonsten: "nachname, vorname" bzw."id" |
Methode 2:
Art | Name | Beschreibung |
Methodenname | CheckLogin | |
Hinweis | Aufruf nur erlaubt wenn zuvor authentifizert | |
Übergabeparameter | user | Userlogin |
password | Passwort | |
auth | (optional), prüft Rollen/Gruppen-ZUgehörigkeit z.B. "rolle:ROLLENNAME1,rolle:ROLLENNAME2,gruppe:GRUPPENNAME1" (auch Rollen/Gruppen-ID möglich!) | |
felder | (optional), gibt weitere Felder an, die mit dem positiven Ergebnis zurück geliefert werden: p_email,g_email,rollen,gruppen | |
Rückgabeparameter | Array | mit "email","vorname","nachname","token","rolle", "id" bzw. falls Fehler: "error" |
Optionale Konfigurierbarkeit in Administration/Basiskonfiguration/Parameter:
- Einschränkung der gelieferten Felder, andere Felder werden nicht zurückgegeben selbst wenn über das API angefordert:
api.checklogin.felder.freigegeben=p_email,g_email
Erstellung von Zugangsdaten
Art | Name | Beschreibung |
Methodenname | SendLogin | |
Übergabeparameter | id | ID des Mitglieds |
Rückgabeparameter | string | das Ergebnis |