Mit der Zeffy API loslegen

Dieser Leitfaden führt Sie durch die Einrichtung. Vollständige technische Details zu jedem Endpunkt, Feld und Parameter finden Sie in der Zeffy API-Dokumentation.

Was können Sie mit der API tun?

Die Zeffy API bietet Ihnen Lesezugriff auf drei zentrale Bereiche Ihres Kontos:

Zahlungen — Rufen Sie eine Liste all Ihrer Transaktionen ab oder suchen Sie nach einer bestimmten Zahlung. Filtern Sie nach Währung, Status, Typ (Online, manuell oder importiert), Kontakt, Kampagne oder Zeitraum. Jede Zahlung enthält Einzelpositionen, Erstattungsdetails, Käuferinformationen und einen Link zur Spendenbescheinigung.

Kontakte — Rufen Sie Ihre vollständige Liste der Spender und Unterstützer ab oder suchen Sie anhand der ID oder E-Mail-Adresse nach einer bestimmten Person. Jeder Kontakt enthält die Spendenhistorie, die Gesamtbeiträge, die Adresse und die Kommunikationseinstellungen.

Kampagnen — Greifen Sie auf Ihre Spendenformulare, Events und andere Kampagnentypen zu. Sehen Sie Titel, Beschreibungen, Ziele, Termine, Vorkommen und die bisher gesammelte Summe ein.

Einige Beispiele dafür, wofür Organisationen die API nutzen

• Neue Spenden in Echtzeit mit einem Buchhaltungssystem wie QuickBooks oder Xero synchronisieren

• Ein CRM wie Salesforce oder HubSpot mit den neuesten Spenderinformationen auf dem aktuellen Stand halten

• Individuelle Dashboards oder Berichte erstellen, die Zeffy-Daten mit Daten aus anderen Quellen kombinieren

• Dankesprozesse oder interne Benachrichtigungen automatisieren, sobald eine Zahlung eingegangen ist

Wer kann auf die API zugreifen?

Nur Administratoren können API-Schlüssel erstellen. Wenn Sie Mitglied einer Organisation ohne Administratorberechtigungen sind, müssen Sie den Administrator Ihrer Organisation bitten, dies einzurichten.

Organisationen auf Zeffy haben nur einen Administrator. Wenn Sie den Administratorstatus auf ein anderes Mitglied Ihres Kontos übertragen möchten, führen Sie die in diesem Artikel beschriebenen Schritte aus.

So erhalten Sie Ihren API-Schlüssel

1. Melden Sie sich bei Ihrem Zeffy-Konto an und gehen Sie zu Einstellungen → Integrationen.

   

2. Im Bereich „Integrationen“ finden Sie die Option zum Erstellen eines API-Schlüssels. Zunächst stellen wir Ihnen einige Fragen, damit wir Ihre Anforderungen besser verstehen.

   

   
   

3. Wählen Sie aus, welche Art von Verbindung Sie herstellen möchten (API oder Webhook), und erstellen Sie Ihren Schlüssel. Kopieren Sie Ihren Schlüssel und bewahren Sie ihn an einem sicheren Ort auf. Sie verwenden ihn, um jede Anfrage an die API zu authentifizieren.

Wichtig: Behandeln Sie Ihren API-Schlüssel wie ein Passwort. Teilen Sie ihn nicht öffentlich und fügen Sie ihn nicht in clientseitigen Code ein. Jede Person mit Ihrem Schlüssel kann die Daten Ihrer Organisation lesen.

Ihre erste Anfrage senden

Jede API-Anfrage benötigt Ihren Schlüssel im Authorization-Header, formatiert als Bearer-Token. So sieht eine Anfrage aus:

GET https://api.zeffy.com/api/v1/payments
Authorization: Bearer YOUR_API_KEY

Dies gibt eine paginierte Liste Ihrer Zahlungen zurück. Standardmäßig erhalten Sie jeweils 10 Ergebnisse (Sie können bis zu 100 anfordern).

Paginierung

Die API verwendet eine cursorbasierte Paginierung. Jede Listenantwort enthält ein Feld has_more, das angibt, ob weitere Ergebnisse vorhanden sind, sowie einen Wert next_cursor, den Sie als Parameter starting_after übergeben können, um die nächste Seite abzurufen.

Filtern

Die meisten Listenendpunkte unterstützen Filter, mit denen Sie die Ergebnisse eingrenzen können. Bei Zahlungen können Sie nach Folgendem filtern:

• currency — cad oder usd

• status — succeeded, failed oder pending

• type — online, manual oder imported

• contact — eine bestimmte Kontakt-ID

• campaign — eine bestimmte Kampagnen-ID

• created[gte], created[lte] usw. — Zeiträume anhand von Unix-Zeitstempeln

Kontakte unterstützen das Filtern nach email sowie nach Zeiträumen für created oder updated. Bei Kampagnen können Sie nach dem Erstellungsdatum created filtern.

Webhooks einrichten

Wenn Sie benachrichtigt werden möchten, sobald etwas geschieht, statt die API wiederholt abzufragen, sind Webhooks die richtige Lösung. Damit können Sie eine URL einrichten, die Events empfängt, die in Ihrem Zeffy-Konto eintreten. So können Sie auf Grundlage Ihrer Fundraising-Aktivitäten Aufgaben in anderen Tools automatisieren.

So richten Sie einen Webhook ein:

1. Unter Einstellungen → Integrationen finden Sie die Option zum Konfigurieren einer Webhook-URL.

2. Geben Sie die URL ein, an die Sie Benachrichtigungen erhalten möchten.

3. Wenn eine Zahlung abgeschlossen ist, sendet Zeffy eine POST-Anfrage mit den vollständigen Zahlungsdetails an Ihre URL.

Die Webhook-Nutzlast enthält einen Event-Typ (payment.completed), einen Zeitstempel und das vollständige Zahlungsobjekt.

Ihr Endpunkt muss mit einem 2xx-Statuscode antworten, um den Empfang zu bestätigen. Andernfalls versucht Zeffy erneut, die Zustellung vorzunehmen.

Antwortcodes

Hier erfahren Sie, was die verschiedenen Statuscodes bei der Arbeit mit der API bedeuten:

• 200 — Ihre Anfrage war erfolgreich.

• 400 — Mit Ihren Abfrageparametern ist etwas nicht in Ordnung. Überprüfen Sie Ihre Filter und das Format.

• 401 — Ihr API-Schlüssel fehlt oder ist ungültig. Stellen Sie sicher, dass Sie ihn in den Authorization-Header aufnehmen.

• 404 — Die gesuchte Ressource existiert nicht. Überprüfen Sie die verwendete ID.

• 429 — Sie haben das Ratenlimit erreicht. Reduzieren Sie die Anzahl Ihrer Anfragen und versuchen Sie es in Kürze erneut.

Was ist mit Zapier?

Wenn Sie Zapier bereits verwenden, um Zeffy mit anderen Tools zu verbinden, funktioniert das weiterhin. Die API ist eine gute Option, wenn Sie mehr Kontrolle benötigen, eine individuelle Integration erstellen möchten oder mit einer Entwicklerin oder einem Entwickler arbeiten, die oder der eine auf Ihre Bedürfnisse zugeschnittene Lösung einrichten kann. Zapier ist weiterhin der einfachste Weg, wenn Sie keine technischen Ressourcen haben und Zeffy mit Tools wie Google Sheets, Slack oder Mailchimp verbinden möchten.

Nächste Schritte

• Vollständige API-Dokumentation — Detaillierte Referenz zu jedem Endpunkt, Parameter und Antwortfeld.

Wenn Sie Fragen haben oder Hilfe bei der Einrichtung benötigen, wenden Sie sich an unser Support-Team. Wir sind für Sie da.