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"

ArtNameBeschreibung
MethodennameGetMembers
(analog "GetContacts" für externe Kontakte)
Übergabeparameterfelder 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
rolleoptional:
Einschränkung auf eine Rolle, z.B. "Mitglieder"
gruppeoptional:
Einschränkung auf eine Gruppe, z.B. "Tennis"
sortoptional:
Angabe von Feldern zur Sortierung. Standard: nachname, vorname
sucheoptional:
Suchbegriff, sucht in Vorname und Nachname
RückgabeparameterArrayListe Datensätze
  • Mitgliedsfelder: id,mandant,vorname,nachname,firma,p_freigabe,g_freigabe,freigabe,foto)
  • zusätzlich angefragte Felder ("felder") aus Anfrage bzw. Parameter (s.u.)
  • "name": voller Name des Mitglieds
  • "fotourl": Url zum Foto

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"

ArtNameBeschreibung
MethodennameGetMember
(analog "GetContact" für externe Kontakte)
ÜbergabeparameteridID der Mitglieds
RückgabeparameterObjektEin Objekt
  • Alle Daten des Mitglieds ("vorname", "nachname", ...)
  • Alle Extradelder (key_extrafeld1, ...)
  • "rollen"
  • "gruppen"

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"

ArtNameBeschreibung
MethodennameGetEvents
Übergabeparametertypoptional
1=öffentliche Veranstaltung, 11=interne Veranstaltung
100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge)
filteroptional:
SQL-Ausdruck zur Einschränkung der Datensätze
jahroptional:
"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"
gruppenidoptional:
"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.
monatoptional:
nur Termine aus dem angegebenen Monat (Format: "YYYYMM")
abmonatoptional:
nur Termine ab dem angegebenen Monat (Format: "YYYYMM")
kostenfremdoptional:
nur ein Kostenbereich (z.B. "1000-2000")
searchoptional:
Suchbegriff, der in den Feldern "titel", "beschreibung", "ort" sucht
restrictionoptional:
Angabe von Einschränkungen: feldname=wert;...
sichtbaroptional:
"alle" = die Veranstaltungen aller Sichtbarkeiten werden geliefert
RückgabeparameterArrayListe Datensätze
  • alle Veranstaltungsfelder ("id", "datum", "titel", "ort", ...)
  • Alle Extrafelder "key_..."
  • "anmeldungen": Anzahl Anmeldungen
  • "freieplaetze": Anzahl der noch freien Plätze
  • "url": VereinOnline-Url der veranstaltenden Einheit
  • "ampel": liefert den Anmeldestatus "gruen","rot","gelb"
  • "link" Link zur Veranstaltung

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"

ArtNameBeschreibung
MethodennameGetEvent
ÜbergabeparameteridID der Veranstaltung
typoptional
1=öffentliche Veranstaltung, 11=interne Veranstaltung
100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge)
RückgabeparameterObjektEin Objekt
  • Alle Daten der Veranstaltung ("id", "datum", "titel", "ort", ...)
  • Alle Extrafelder "key_..."
  • "anmeldungen": Anzahl Anmeldungen
  • "freieplaetze": Anzahl der noch freien Plätze
  • "gruppenname": Name der veranstaltenden Gruppe
  • "link": Link zur Veranstaltung

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"

ArtNameBeschreibung
MethodennameGetRegistrations
ÜbergabeparameteridID der Veranstaltung
RückgabeparameterArrayListe Datensätze:
  • "veranstaltungid"
  • "vorname"
  • "nachname"
  • "geburtstag"
  • "email"
  • "adresse"
  • "firma"
  • "status"
  • "userid"
  • "anmeldeid"
  • "key_..."


Ändern einer Anmeldung: "ChangeRegistration"

ArtNameBeschreibung
MethodennameChangeRegistration
ÜbergabeparameteranmeldeidID der Anmeldung
statusNeuer Status der Anmeldung
(0=angemeldet, 1=angemeldet, 3=auf Warteliste)
anmerkungText, der als Anmerkung ergänzt wird


Abruf von Anmeldungen: "GetCalendar": zentralen Kalender-Daten eines Monats

ArtNameBeschreibung
MethodennameGetCalendar
ÜbergabeparametermMonat
yJahr
typoptional
1=öffentliche Veranstaltung, 11=interne Veranstaltung
100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge)
Rückgabeparameteroffset1. Tag des Monats (0…6)
tageAnzahl Tage des Monats
text"Monatsname Jahreszahl"
tagListe von Tagen, an denen Veranstaltungen stattfinden
idListe der IDs zu den Veranstaltungen aus "tag"
datumListe zu Datumswerten
titelListe 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"

ArtNameBeschreibung
MethodennameGetNews
Übergabeparameteralle=jaoptional:
liefert auch bereits (gültig bis) abgelaufene News.
maximaloptional:
maximale Anzahl der News
idoptional:
nur diese ID laden
conditionoptional:
feld=wert
RückgabeparameterArrayListe Datensätze
  • Alle Datenfelder ("datum", "subject", "body", ...)
  • alle Extrafelder ("key_feldname1", ...)
  • "bodyteaser": liefert die ersten Zeichen der Nachricht (gemäß Zeichenzahl in der Nachricht)
  • Falls mit zugeordneter Veranstaltung:
    zusätzliche Felder: "veranstaltungtitel", "veranstaltungdatum", "veranstaltunganztage"

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"

ArtNameBeschreibung
MethodennameGetNewsletter
RückgabeparameterArrayListe aller Datensätze:
  • "id"
  • "datum"
  • "titel"
  • "html": HTML-Ansicht des Newsletters
  • "beitraege": Array von IDs (nutzbar für API "GetNewsletterBeitrag")

Abruf aller öffentlichen Newsletter-Beiträge: "GetNewsletterBeitrag"

ArtNameBeschreibung
MethodennameGetNewsletter
Übergabeparameteridoptional:
ID des Beitrags
RückgabeparameterArrayListe aller Datensätze:
  • "id"
  • "rubrik"
  • "datum"
  • "subject"
  • "body"
  • "attachments"
  • "newsletterid"


Abruf von Rechnungsdaten: "GetRechnung"

ArtNameBeschreibung
MethodennameGetRechnung
ÜbergabeparameteridID der Rechnung
RückgabeparameterObjektEin Objekt
  • Alle Daten der Rechnung ("datum", "rechnungsnummer", "betrag", ...)
  • "mwststd"


Abruf aller Gruppen: "GetGroups"

ArtNameBeschreibung
MethodennameGetGroups
Übergabeparametertypoptional:
="v": nur Veranstaltungs-Gruppen
RückgabeparameterArrayListe Datensätze:
  • "id"
  • "name"
  • ...


Abruf von Bildergalerie: "GetPictures"

ArtNameBeschreibung
MethodennameGetPictures
RückgabeparameterArrayListe Datensätze:
  • "id"
  • "datum"
  • "titel"
  • "nachlese"
  • "bilder"
  • "bildersmall"
  • "text"


Abruf von Shop-Artikeln: "GetShop"

ArtNameBeschreibung
MethodennameGetShop
Übergabeparametermaximaloptional:
maximale Menge Datensätze
RückgabeparameterArrayListe Datensätze
  • alle Felder ("id", "textkurz", ...)
  • alle Extrafelder
  • "bestand": Bestandsanzahl
  • "url": Url der Einheit


Abruf der flexiblen Listen-Defintionen: "GetLists"

ArtNameBeschreibung
MethodennameGetLists
RückgabeparameterArrayListe Datensätze:
  • "id"
  • "name"
  • "schemaid"
  • "schemaname"


Abruf von Daten aus einer flexiblen Liste: "GetList"

ArtNameBeschreibung
MethodennameGetList
ÜbergabeparameteridID der flexiblen Liste
filteroptional:
ein Wert im Datensatz, z.B. "mitglied=1234"
returnoptional:
"object": gibt die Daten als Object (Key-Value-Array) zurück
RückgabeparameterArrayListe aller Datensätze:
  • Array von "key=wert" bzw. "key"=>"wert"


Anlage eines Datensatzen in einer flexible Liste: "CreateListData"

ArtNameBeschreibung
MethodennameCreateListData
ÜbergabeparameteridID der flexiblen Liste
POST-DatenFELDNAME1=WERT
&FELDNAME2=WERT
&DATEIFELDNAME1=filename|content
&DATEIFELDNAME2[]=filename|content
&DATEIFELDNAME2[]=filename|content
Rückgabeparameterid des neuen Datensatzes, bzw. "error" falls die Listen-ID nicht existiert


Anlage eines Mitglieds: "CreateMember"

ArtNameBeschreibung
MethodennameCreateMember
Übergabeparametervorname
nachname
...
key_FELDNAME1
rolle
gruppe
Daten
Rückgabeparameterid des neuen Datensatzes


Prüfung eines Logins

Methode 1:
ArtNameBeschreibung
MethodennameVerifyLogin
ÜbergabeparameteruserUserlogin
passwordPasswort
result="id": als Ergebnis wird die "id" geliefert statt vorname/nachname
RückgabeparameterArrayfalls Fehler leerer String, ansonsten: "nachname, vorname" bzw."id"

Methode 2:
ArtNameBeschreibung
MethodennameCheckLogin
HinweisAufruf nur erlaubt wenn zuvor authentifizert
ÜbergabeparameteruserUserlogin
passwordPasswort
auth(optional), prüft Rollen/Gruppen-ZUgehörigkeit
z.B. "rolle:ROLLENNAME1,rolle:ROLLENNAME2,gruppe:GRUPPENNAME1"
RückgabeparameterArraymit "email","vorname","nachname","token","rolle"
bzw. falls Fehler: "error"