Der folgende Artikel beschreibt die Schritte zur Erstellung eines Spendenbarometers für Spenden, die über den RaiseNow Manager registriert wurden.
Voraussetzungen
Um dein eigenes Spendenbarometer zu erstellen, müssen folgende Voraussetzungen erfüllt sein:
- Ein RaiseNow-Konto für manage.raisenow.com
- Die RaiseNow-Händler-Kennung (Merchant Identifier)
- Einen RaiseNow-API-User, um die RaiseNow-API abzufragen. Du kannst einen API User erstellen, indem diesem Knowledge Base Artikel folgst: Wie erstelle ich einen neuen User im RaiseNow Manager. Wichtig dabei ist, dass du die API-Berechtigungen und das Flag für einen API-User festlegst, da der User sonst abläuft.
Anleitung zur Implementierung
Die vollständige Dokumentation ist auf GitHub zu finden.
Das Spendenbarometer besteht aus zwei Hauptkomponenten:
- einer serverseitigen Komponente, die die RaiseNow-API abfragt.
- der Frontend-Komponente, die die Spendenbetragsstatistik anzeigt.
1. Serverseitige Komponente
Um Spenden, die über RaiseNow für Ihre Organisation eingegangen sind, zusammenzutragen, kannst du die RaiseNow-Such-API von deiner serverseitigen Komponente aus abfragen. Sobald du die Spendendaten erhalten hast, kann die serverseitige Komponente eine API für dein Frontend bereitstellen.
Warum solltest du eine serverseitige Komponente zur Abfrage der Such-API verwenden? Die Such-API ist durch Berechtigungsnachweise geschützt. Wenn du die API vom Frontend aus abfragst, werden diese Berechtigungsnachweise der Öffentlichkeit zugänglich gemacht, so dass jeder sie verwenden und deine Daten bei RaiseNow abfragen und aktualisieren kann. Es liegt in deiner Verantwortung, diese Anmeldeinformationen geheim und sicher zu halten.
Autorisierung
Um auf die RaiseNow-API zuzugreifen, musst du die Anfrage per HTTP Basic Authentifizierung und deinen API-User Zugangsdaten authentifizieren.
Suchabfrage
Um die Daten über Ihre eingegangenen Spenden zu erhalten, können Sie die folgende API-Anfrage verwenden:
GET https://api.raisenow.com/epayment/api/<MERCHANT_IDENTIFIER>/transactions/search?<QUERY>'
wobei
MERCHANT_IDENTIFIER
ist deine RaiseNow Händler-KennungQUERY
ist die Suchanfrage in Form einer URL-kodierten Zeichenfolge in folgendem Format:- Ein Sortier-Auftrag, der beschreibt, wie die Spende sortiert werden soll. Wenn das Erstellungsdatum verwenden und absteigend sortiert wird, erhältst du die neueste Spende.
sort[0][field_name]=created
sort[0][order]=desc
- Ein Filter-Teil, der die Transaktionen filtert. Im Folgenden werden alle erfolgreich durchgeführten Spenden in CHF ausgegeben.
filters[0][field_name]=last_status
filters[0][type]=term
filters[0][value]=final_success
filters[1][field_name]=test_mode
filters[1][type]=term
filters[1][value]=production
filters[2][field_name]=currency_identifier
filters[2][type]=term
filters[2][value]=chf
- Ein Berechnungs- Teil (facets), der definiert, wie die Spenden verrechnet werden. Neben der Gesamtsumme der Spenden, die Ihrer Filterabfrage entsprechen, gibt diese Facette auch die Maximal-, Minimal-, Durchschnittswerte und die Standardabweichung an. Beachten Sie, dass der Name der Facette auch in der Antwort enthalten ist. Dies ist besonders nützlich, wenn mehrere Berechnungen definiert werden.
facets[0][field_name]=amount
facets[0][type]=stats
facets[0][name]=total_amount
- Ein Abschnitt, der definiert, welche Art von Feldern von der Suchanfrage ausgegeben werden.
displayed_fields=epp_transaction_id,created,currency_identifier,amount,payment_method_identifier
- Ein Abschnitt, der festlegt, wie viele Datensätze pro Seite zurückgegeben werden sollen.
records_per_page=5
- Die vollständige Liste der Optionen findest du auch in den RaiseNow Developer Docs und weitere Beispiele für Abfragen in unserer Knowledge Base Transaction Search API.
- Ein Sortier-Auftrag, der beschreibt, wie die Spende sortiert werden soll. Wenn das Erstellungsdatum verwenden und absteigend sortiert wird, erhältst du die neueste Spende.
Du erhälst dann eine Ausgabe, die wie folgt aussieht:
{
"result": {
"transactions": [
{
"epp_transaction_id": "<TRANACTION_IDENTIFIER>",
"created": "1642428270",
"currency_identifier": "<CURRENCY>",
"amount": <AMOUNT_IN_CENTS>,
"payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
},
{
"epp_transaction_id": "<TRANACTION_IDENTIFIER>",
"created": "1640073719",
"currency_identifier": "<CURRENCY>",
"amount": <AMOUNT_IN_CENTS>,
"payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
},
{
"epp_transaction_id": "<TRANACTION_IDENTIFIER>",
"created": "1639470666",
"currency_identifier": "<CURRENCY>",
"amount": <AMOUNT_IN_CENTS>,
"payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
},
{
"epp_transaction_id": "<TRANACTION_IDENTIFIER>",
"created": "1639415198",
"currency_identifier": "<CURRENCY>",
"amount": <AMOUNT_IN_CENTS>,
"payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
},
{
"epp_transaction_id": "<TRANACTION_IDENTIFIER>",
"created": "1639412837",
"currency_identifier": "<CURRENCY>",
"amount": <AMOUNT_IN_CENTS>,
"payment_method_identifier": "<PAYMENT_METHOD_IDENTIFIER>"
}
],
"sort": [
{
"fieldname": "created.raw",
"order": "desc"
}
],
"additional_info": {
"lang": "de",
"search_time": "138.7160",
"total_hits": 900,
"page": 1,
"total_pages": 180,
"records_per_page": "5"
},
"filters": [
{
"field_name": "last_status",
"type": "term",
"value": "final_success",
"filter_group": 0
},
{
"field_name": "test_mode",
"type": "term",
"value": "production",
"filter_group": 1
},
{
"field_name": "currency_identifier",
"type": "term",
"value": "chf",
"filter_group": 2
}
],
"facets": [
{
"name": "total_amount",
"type": "stats",
"stats": {
"min": 1,
"max": 5000,
"mean": 120.93333333333,
"count": 900,
"total": 108840,
"standard_deviation": 324.61111092095,
"sum_of_squares": 107997520,
"variance": 105372.37333333
}
}
]
}
}
wobei
transactions
enthält bis zurecords_per_page
Transaktionen, die mit Ihrer Filterabfrage übereinstimmen. Die Variablen sind wie folgt definiert:TRANACTION_IDENTIFIER
ist die Kennung der Spende bei RaiseNowCURRENCY
ist die Währung, in der die Spende getätigt wurde, z.B.chf
AMOUNT_IN_CENTS
ist der Spendenbetrag in Cents.PAYMENT_METHOD_IDENTIFIER
Kennung des Zahlungsmittels
sort
beschreibt, nach welchem Feld sortiert wurdeadditional_info
gibt Ihnen einen Eindruck davon, wie viele Datensätze mit Ihrer Abfrage übereinstimmenfilters
beschreibt, welche Filter in der Abfrage angewendet wurdenfacets
gibt Ihnen detaillierte Informationen
Normalerweise wird Ihre serverseitige Komponente nur die Summe (total
) der (facets
) ausgeben, um den gesammelten Gesamtbetrag anzuzeigen.
Example
Die vollständige Dokumentation ist auf GitHub zu finden.
Ein Beispiel für die serverseitige PHP-Komponente findest du in server/server.php
.
Um diese auszuführen, kannst du folgenden Schritten folgen:
- Installieren Sie die composer -Abhängigkeiten mit
composer install
. - Führe
php server.php
aus.
2. Frontend Komponente
Sobald du die serverseitige Komponente fertiggestellt hast, kannst mit dem Code in client/index.html
deinen Spenden-Barometer anzeigen.
Kommentare
0 Kommentare
Zu diesem Beitrag können keine Kommentare hinterlassen werden.