Mit der Zeffy API loslegen

Dieser Leitfaden führt Sie durch die Einrichtung. Ausführliche technische Informationen zu jedem Endpunkt, Feld und Parameter finden Sie in der Zeffy API-Dokumentation.

Was können Sie mit der API tun?

Die Zeffy API ermöglicht Ihnen den Lesezugriff auf drei zentrale Bereiche Ihres Kontos:

Zahlungen — Rufen Sie eine Liste aller Ihrer Transaktionen ab oder suchen Sie nach einer bestimmten Zahlung. Filtern Sie nach Währung, Status, Typ (Online, manuell oder importiert), Kontakt, Kampagne oder Datumsbereich. Jede Zahlung enthält Einzelposten, Rückerstattungsdetails, Informationen zum Käufer und einen Link zur Zuwendungsbestätigung.

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 Gesamtsumme der Beiträge, die Adresse und die Kommunikationseinstellungen.

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

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

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

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

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

• Dankeschön-Abläufe oder interne Benachrichtigungen automatisieren, wenn eine Zahlung eingeht

Wer kann auf die API zugreifen?

Nur Administratoren können API-Schlüssel erstellen. Wenn Sie Mitglied (das) 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 die Art der Verbindung aus, die 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. Geben Sie ihn nicht öffentlich weiter und fügen Sie ihn nicht in clientseitigen Code ein. Jeder, der Ihren Schlüssel besitzt, 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

Damit wird eine paginierte Liste Ihrer Zahlungen zurückgegeben. 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. Für 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. — Datumsbereiche anhand von Unix-Zeitstempeln

Kontakte unterstützen das Filtern nach email sowie nach Datumsbereichen für created oder updated. Kampagnen unterstützen Datumsfilter für created.

Webhooks einrichten

Wenn Sie benachrichtigt werden möchten, sobald etwas passiert, anstatt 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 auftreten – so können Sie Aufgaben in anderen Tools auf Grundlage Ihrer Fundraising-Aktivitäten 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, unter der Sie Benachrichtigungen empfangen 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 Nachricht zuzustellen.

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 im Authorization-Header einschließen.

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

• 429 — Sie haben das Ratenlimit erreicht. Verlangsamen Sie Ihre Anfragen und versuchen Sie es in Kürze erneut.

Was ist mit Zapier?

Wenn Sie bereits Zapier verwenden, um Zeffy mit anderen Tools zu verbinden, funktioniert das weiterhin. Die API ist eine gute Option, wenn Sie mehr Kontrolle benötigen, eine benutzerdefinierte Integration erstellen möchten oder mit einem Entwickler zusammenarbeiten, der eine auf Ihre Anforderungen 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.