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.
Nutzung per PHP:
$url = "https://www.vereinonline.org/IHRVEREIN/"; $usr = "..."; // der API-Benutzername mit entsprechenden Rollenrechten ("admin" ist nicht zulässig!) $pwd = "..."; // das zugehörige Passwort print_r(VereinOnlineRequest($url, "GetMembers", array(), $usr, $pwd)); function VereinOnlineRequest($url, $funktion, $daten, $usr, $pwd) { $url.="?json"; $url.="&function=$funktion"; foreach($daten as $k=>$v) $url.="&$k=".urlencode($v); $url.="&token=A/$usr/".md5($pwd); $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/?json&function=GetMembers', success: function(result) { ... }, error: function(r,e,txt) { ... } });
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" und "gruppen" und Extrafelder "key_..." ohne Angabe werden standardmäßig geliefert: id,mandant,vorname,nachname,firma,p_freigabe,g_freigabe,freigabe,foto |
filter | optional: SQL-Ausdruck zur Einschränkung der Datensätze, Felder aus der Mitglieder-Feldliste oder "rolle"=rollenid | |
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 | |
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, $usr, $pwd); 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), $usr, $pwd); 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
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"), $usr, $pwd); 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), $usr, $pwd); 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")!
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: feld=wert | |
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 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:
|
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 |
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 |
Anlage eines Mitglieds: "CreateMember"
Art | Name | Beschreibung |
Methodenname | CreateMember | |
Übergabeparameter | vorname nachname ... key_FELDNAME1 rolle gruppe | Daten |
Rückgabeparameter | id des neuen Datensatzes |
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 | |
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!) | |
Rückgabeparameter | Array | mit "email","vorname","nachname","token","rolle", "id" bzw. falls Fehler: "error" |