Was ist eine API Schnittstelle?
Eine Programmierschnittstelle, genauer Schnittstelle zur Anwendungsprogrammierung, häufig nur kurz API genannt, ist ein Programmteil, der von einem Softwaresystem anderen Programmen zur Anbindung an das System zur Verfügung gestellt wird. API Schnittstellen dienen der Kommunikation zwischen zwei Systemen – Beispielsweise zwischen Ihrem Altruja-Spendentool und Ihrer Website.
Was sind meine Vorteile?
Der Spendenprozess wird automatisierter und lässt sich flexibel anpassen. Sie können Ihr Spendenformular noch stärker an Ihre Bedürfnisse anpassen. Des Weiteren steigert sich Ihr Spendenerfolg, da Sie noch besser die Geschichte hinter Ihren Spendenaufrufen erzählen können.
Für mehr Informationen können Sie sich gerne an unseren Kundenservice [email protected] wenden.
Was sind meine Möglichkeiten?
Altruja bietet drei verschiedene API Schnittstellen, um Spenderdaten in verschiedenen Arten automatisiert zu verarbeiten.
- Parameter Übergabe API: Öffentliche Daten sollen von der Website in das Spendentool übertragen werden
- Öffentliche Spenderdaten API: Öffentliche Daten sollen vom Spendentool auf die Website übertragen werden
- Interne Spenderdaten API: Nicht öffentliche Daten sollen vom Spendentool z.B. zur Buchhaltung exportiert werden
1. Parameter Übergabe API
Mit Hilfe dieser Schnittstelle können Sie ein Spendenformular so aufrufen, dass einzelne Felder, wie z.B. Betrag, Name, E-Mail oder Verwendungszweck (Zusatzfelder), schon vorausgefüllt sind.
Wenn das Spendenformular z.B. unter
http://www.organisation.de/spenden/
eingebettet ist, kann folgende Adresse durch einen Link aufgerufen werden:
http://www.organisation.de/spenden/#betrag=100
Das Betragsfeld wurde mit 100 vorausgefüllt.
Nach dem Aufruf der Adresse werden die Parameter automatisch abgeschnitten, so dass der Spender nur diese Adresse sieht:
http://www.organisation.de/spenden/#
Wenn mehrere Parameter übergeben werden sollen, trennt man diese mit dem &-Zeichen.
Beispiel:
http://www.organisation.de/spenden/#betrag=100&recurring=monthly&vorname=Max&Nachname=Mustermann&gender=0
Wenn es sich nicht um ein Spendenformular handelt, muss der Spendenschritt direkt verlinkt werden.
Beispiel:
http://www.organisation.de/anlassspenden/?anlassspenden-1234/spende#betrag=100
Zur Zeit sind folgende Felder möglich:
betrag - Betrag der Spende
recurring - Intervall der Spende, kann sein: once, monthly, quarterly, yearly
custom1 - Zusatzfeld 1 (wenn es für die Seite angeschaltet ist )
custom2 - Zusatzfeld 2 (wenn es für die Seite angeschaltet ist )
custom3 - Zusatzfeld 3 (wenn es für die Seite angeschaltet ist )
gender - Anrede des Spenders: 0 - Herr, 1 - Frau
vorname - Vorname des Spenders
nachname - Nachname des Spenders
email - E-Mail-Adresse des Spenders
2. Öffentliche Spenderdaten API
Mit dieser Schnittstelle können Sie Daten über Ihre Spendenaktionen auslesen, die Sie öffentlich anzeigen können.
So können Sie z.B. den Spendenstand auf Ihrer Homepage präsentieren oder die Spenderliste (Ehrenwand) in anderer Form darstellen.
Es handelt sich um eine sogenannte REST-API.
Das bedeutet, dass Sie die Daten z.B. per Javascript bequem auslesen können, da die Daten als JSON zurückgegeben werden.
Für diese Schnittstelle benötigen Sie eine API-Url, die Sie bei unserem Support für die jeweilige Spendenseite erfragen können.
Die API-Url hat folgendes Format:
https://www.altruja.de/api/page/yngz
Die letzten 4 Zeichen sind das Kürzel, das die Spendenseite identifiziert (in diesem Fall yngz)
Die API-Url nimmt außerdem eine Reihe von Parametern entgegen:
https://www.altruja.de/api/page/yngz?details=1&num=10&ort=1&callback=test
Parameter:
details=1|0 - Details zur Aktion wie Beschreibungstext
num=<n> - Die letzten/neusten Spenden werden zurückgeliefert.
ort=1|0 - Zu den Spenden wird der Ort des Spenders ausgegeben, sofern der Spender diesen angegeben hat, ansonsten wird ein leerer String "" zurückgeliefert
callback=<fkt> - es wird statt einem reinen JSON Objekt ein Javascript Callback mit einem Objekt aufgerufen (für JQuery/AJAX).
JQuery Beispiel:
$.ajax({
type: 'GET',
url: 'https://www.altruja.de/api/page/yngz',
cache:true,
jsonp: "callback",
jsonpCallback: 'jsonCallback',
contentType: "application/json",
dataType: 'jsonp',
success: function(json) {
console.log(json);
}
});
3. Interne Spenderdaten API
Hiermit können Sie Spenderdaten für die Buchhaltung oder weitere Bearbeitung in CRM-Systemen automatisiert exportieren.
Diese Daten sind nur für den internen Gebrauch gedacht und sollen nicht öffentlich zugänglich gemacht werden.
Der Export entspricht den Daten, die Sie manuell aus dem MyAltruja-Backend exportieren können.
Es handelt sich um CSV-Daten - die Spalten werden durch das Tab-Zeichen getrennt. In der ersten Zeile sind die Namen der Spalten zu finden.
Sie können alle Filter, die Ihnen im MyAltruja zur Verfügung stehen, auch für diesen automatisierten Export verwenden.
Beispiel:
Hier eine Beschreibung am Beispiel von "curl".
username und password sind die Daten mit denen sich der Kunde im MyAltruja anmeldet (Hauptuser).
Alle Spenden:
curl -u username:password https://altruja.de/api/charity/export > export.csv
Spenden eines Zeitraums:
curl -u username:password 'https://altruja.de/api/charity/export?filter=range&criteria=YYYY-MM-DD_YYYY-MM-DD'
Aktualisierte Spenden eines Zeitraums:
curl -u username:password 'https://altruja.de/api/charity/export?filter=range-updated&criteria=YYYY-MM-DD_YYYY-MM-DD'
Spenden einer Altruja-Abrechnung:
curl -u username:password 'https://altruja.de/api/charity/export?filter=invoice&criteria=INVOICE-ID'
Individueller Filter auf Spaltenbasis
Sie können als Basis den Query String vom Export Link im MyAltruja nehmen:
curl -u username:password 'https://altruja.de/api/charity/export?filter=column&criteria=abetrag-datum&abetrag%5B0%5D=25&datum%5B0%5D=2016-01-15&datum%5B1%5D=2016-01-25'