API Schnittstelle - Was sind meine Möglichkeiten & Vorteile?

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 info@altruja.de wenden.

Beispiel: 
McDonalds Spendenshop

Was sind meine Möglichkeiten?

 

Altruja bietet drei verschiedene API-Schnittstellen um Spenderdaten in verschiedenen Arten automatisiert zu verarbeiten.

  1. Parameter Übergabe API: Öffentliche Daten sollen von der Website in das Spendentool übertragen werden
  2. Öffentliche Spenderdaten API: Öffentliche Daten sollen von dem Spendentool auf die Website übertragen werden
  3. 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, Email 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 - Email-Adressse 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/neuesten 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 Spender-Daten 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 der Kunde sich im Myaltruja anmeldet.

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'

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'