StiftungOnline.org - Ihre Stiftungs-Software im Internet.

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" und "gruppen" 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: SQL-Ausdruck zur Einschränkung der Datensätze, Felder aus der Mitglieder-Feldliste, z.B.: nachname='Meier' AND YEAR(geburtstag)=1970 rolle=123 gruppe=456 gruppenleiter=123 gruppenleiter2=123 (1 steht für Leiter, 2 steht für Stellvertreter)
	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 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, $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 Alle Daten des Mitglieds ("vorname", "nachname", ...) Alle Extradelder (key_extrafeld1, ...) "rollen" "gruppen" "gruppenids" "code"

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
Übergabeparameter	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 alle Veranstaltungsfelder ("id", "datum", "titel", "ort", ...) Alle Extrafelder "key_..." "anmeldungen": Anzahl Anmeldungen "freieplaetze": Anzahl der noch freien Plätze "wotagdatum": formatiertes Datum "url": VereinOnline-Url der veranstaltenden Einheit "ampel": liefert den Anmeldestatus "gruen","rot","gelb" "link" Link zur Veranstaltung "beschreibungteaser": die ersten 200 Zeichen der Beschreibung

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
Übergabeparameter	typ	optional 1=öffentliche Veranstaltung, 11=interne Veranstaltung 100... eigene Typen (Administration/Optionen/Veranstaltungen/Details/Weitere "Veranstaltungsart"-Listeneinträge)
Rückgabeparameter	Objekt	Ein Objekt Alle Daten der Veranstaltung ("id", "datum", "titel", "ort", ...) Alle Extrafelder "key_..." "anmeldungen": Anzahl Anmeldungen "freieplaetze": Anzahl der noch freien Plätze "wotagdatum": formatiertes Datum "gruppenname": Name der veranstaltenden Gruppe "link": Link zur Veranstaltung "beschreibungteaser": die ersten 200 Zeichen der Beschreibung

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: "veranstaltungid" "vorname" "nachname" "geburtstag" "email" "adresse" "firma" "status" "userid" "anmeldeid" "anmerkungen" "anmerkungenpublic" "zeitpunkt" "key_..."

Ä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
Übergabeparameter	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: "id" "datum" "titel" "html": HTML-Ansicht des Newsletters "beitraege": Array von IDs (nutzbar für API "GetNewsletterBeitrag")

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: "id" "rubrik" "datum" "subject" "body" "attachments" "newsletterid"

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: feld=wert gruppenid=.. rollenid=..
Rückgabeparameter	Array	Liste 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 von Rechnungsdaten: "GetRechnung"

Art	Name	Beschreibung
Methodenname	GetRechnung
Übergabeparameter	id	ID der Rechnung
Rückgabeparameter	Objekt	Ein Objekt Alle Daten der Rechnung ("datum", "rechnungsnummer", "betrag", ...) "mwststd"

Abruf aller Gruppen: "GetGroups"

Art	Name	Beschreibung
Methodenname	GetGroups
Übergabeparameter	typ	optional: ="v": nur Veranstaltungs-Gruppen
Rückgabeparameter	Array	Liste Datensätze: "id" "name" ...

Abruf von Bildergalerie: "GetPictures"

Art	Name	Beschreibung
Methodenname	GetPictures
Rückgabeparameter	Array	Liste Datensätze: "id" "datum" "titel" "nachlese" "bilder" "bildersmall" "text"

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 alle Felder ("id", "textkurz", ...) alle Extrafelder "bestand": Bestandsanzahl "url": Url der Einheit

Abruf der flexiblen Listen-Defintionen: "GetLists"

Art	Name	Beschreibung
Methodenname	GetLists
Rückgabeparameter	Array	Liste Datensätze: "id" "name" "schemaid" "schemaname"

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: Array von "key=wert" bzw. "key"=>"wert"

Anlage eines Datensatzen in einer flexible Liste: "CreateListData"

Art	Name	Beschreibung
Methodenname	CreateListData
Übergabeparameter	id	ID der flexiblen Liste
Übergabeparameter	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 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!)
	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