Mit der Zeffy API loslegen
Diese Anleitung führt Sie durch die Einrichtung. Ausführliche technische Informationen zu allen Endpunkten, Feldern und Parametern finden Sie in der Zeffy API-Dokumentation.
Ausführliche technische Informationen finden Sie in der API-Dokumentation
Was können Sie mit der API tun?
Mit der Zeffy API haben Sie 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 Zeitraum. Jede Zahlung enthält Einzelposten, Angaben zu Rückerstattungen und Käufern sowie einen Link zur Zuwendungsbestätigung.
Kontakte — Rufen Sie die vollständige Liste Ihrer Spender und Unterstützer ab oder suchen Sie anhand der ID oder E-Mail-Adresse nach einer bestimmten Person. Jeder Kontakt enthält den Spendenverlauf, die Gesamtsumme der Beiträge, die Adresse und die Kommunikationseinstellungen.
Kampagnen — Greifen Sie auf Ihre Spendenformulare, Events und andere Kampagnentypen zu. Sehen Sie sich Titel, Beschreibungen, Ziele, Daten, Termine und die bisher gesammelte Summe an.
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
Benutzerdefinierte Dashboards oder Berichte erstellen, die Zeffy-Daten mit Daten aus anderen Quellen kombinieren
Dankesabläufe oder interne Benachrichtigungen automatisieren, wenn eine Zahlung eingeht
Wer kann auf die API zugreifen?
Nur Admins können API-Schlüssel erstellen. Wenn Sie als Mitglied (das) einer Organisation keine Admin-Berechtigungen haben, müssen Sie den Admin Ihrer Organisation bitten, die Einrichtung vorzunehmen.
Bei Organisationen auf Zeffy gibt es nur einen Admin. Wenn Sie den Admin-Status auf ein anderes Mitglied (das) Ihres Kontos übertragen möchten, folgen Sie den Schritten in diesem Artikel.
Wenn Integrationen in Ihren Einstellungen nicht angezeigt wird oder die Seite leer bleibt, wenn Sie versuchen, einen API-Schlüssel zu erstellen, sind Sie wahrscheinlich als Benutzer ohne Admin-Rechte angemeldet. Bitten Sie Ihren Admin, den Schlüssel zu erstellen und sicher mit Ihnen zu teilen.
Ein API-Schlüssel ist immer an ein aktives, verifiziertes Organisationskonto gebunden. Wir können keinen API-Zugriff direkt oder für Personen ohne Organisationskonto bereitstellen: Der Admin der Organisation muss den Schlüssel erstellen.
So erhalten Sie Ihren API-Schlüssel
Melden Sie sich bei Ihrem Zeffy-Konto an und gehen Sie zu Einstellungen → Integrationen.
Im Bereich Integrationen finden Sie die Möglichkeit, einen API-Schlüssel zu erstellen. Zunächst stellen wir Ihnen einige Fragen, damit wir Ihre Anforderungen besser verstehen.
Öffnen Sie den Tab API Key und klicken Sie auf Generate, um Ihren API-Schlüssel zu erstellen. Kopieren Sie den Schlüssel und bewahren Sie ihn sicher auf. Sie benötigen ihn, um jede Anfrage an die API zu authentifizieren. Webhooks richten Sie separat im Tab Webhook ein (siehe unten).
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. Jede Person mit Ihrem Schlüssel kann die Daten Ihrer Organisation lesen.
Ihr Schlüssel ist auf der Seite standardmäßig ausgeblendet. Klicken Sie auf Reveal key, um ihn anzusehen oder zu kopieren.
Einen neuen API-Schlüssel erstellen
Wenn Sie unter Einstellungen → Integrationen einen neuen Schlüssel erstellen, wird der alte sofort ungültig. Aktualisieren Sie daher alle Tools, die ihn verwenden. Es gibt keine andere Möglichkeit, eine Integration über Zeffy zurückzusetzen. Ein neuer Schlüssel ändert nichts an dem Tool, das Ihre Daten empfängt: Wenn eine Integration nicht mehr funktioniert, überprüfen Sie die Einstellungen in diesem Tool (den Endpunkt, den Authorization-Header, die Webhook-URL und die Feldzuordnung).
Ihre erste Anfrage senden
Für jede API-Anfrage muss Ihr Schlüssel im Authorization-Header als Bearer-Token angegeben werden. So sieht eine Anfrage aus:
GET https://api.zeffy.com/api/v1/payments
Authorization: Bearer YOUR_API_KEYDamit wird eine paginierte Liste Ihrer Zahlungen zurückgegeben. Standardmäßig erhalten Sie jeweils 10 Ergebnisse (Sie können bis zu 100 anfordern).
Seitennummerierung
Die API verwendet eine cursorbasierte Seitennummerierung. 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 folgenden Kriterien filtern:
currency—cadoderusdstatus—succeeded,failedoderpendingtype—online,manualoderimportedcontact— eine bestimmte Kontakt-IDcampaign— eine bestimmte Kampagnen-IDcreated[gte],created[lte]usw. — Zeiträume mithilfe von Unix-Zeitstempeln
Für Kontakte können Sie nach email sowie nach Zeiträumen für created oder updated filtern. Für Kampagnen sind Datumsfilter für created verfügbar.
Die insgesamt gesammelte Summe einer Kampagne abrufen
Verwenden Sie den Kampagnenendpunkt, wenn Sie nur Gesamtsummen benötigen, zum Beispiel für ein Fundraising-Thermometer auf Ihrer Website. Sie müssen dafür weder einzelne Zahlungen noch Spenderdaten abrufen.
GET https://api.zeffy.com/api/v1/campaigns/{id}
Authorization: Bearer YOUR_API_KEYDas Feld
volumeenthält die von der Kampagne insgesamt eingenommene Summe in Cent. Teilen Sie den Wert durch 100, um den Betrag in Dollar zu erhalten.Das funktioniert genauso für Spenden- und Ticketing-Kampagnen.
Bei einer Peer-to-Peer-Kampagne enthält
volumeder Hauptkampagne bereits alle Teilnehmer- und Teamseiten. Sie müssen die Werte daher nicht addieren.Um eine Gesamtsumme über mehrere Kampagnen hinweg anzuzeigen, rufen Sie sie mit
GET /api/v1/campaignsab und addieren Sie ihrevolume-Werte.
Webhooks einrichten
Wenn Sie benachrichtigt werden möchten, sobald etwas passiert, statt die API wiederholt abzufragen, sind Webhooks die richtige Lösung. Damit können Sie eine URL einrichten, an die Events aus Ihrem Zeffy-Konto gesendet werden. So können Sie Aufgaben in anderen Tools anhand Ihrer Fundraising-Aktivitäten automatisieren.
So richten Sie einen Webhook ein:
Unter Einstellungen → Integrationen finden Sie die Möglichkeit, eine Webhook-URL einzurichten.
Geben Sie die URL ein, an die Sie Benachrichtigungen erhalten möchten.
Wenn eine Zahlung abgeschlossen ist, sendet Zeffy eine POST-Anfrage mit allen 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 Statuscode 2xx antworten, um den Empfang zu bestätigen. Andernfalls versucht Zeffy erneut, die Daten zuzustellen.
Antwortcodes
Die verschiedenen Statuscodes bedeuten bei der Arbeit mit der API Folgendes:
200 — Ihre Anfrage war erfolgreich.
400 — Mit Ihren Abfrageparametern stimmt etwas nicht. Ü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 angeben.
404 — Die gesuchte Ressource ist nicht vorhanden. Überprüfen Sie die verwendete ID.
429 — Sie haben das Ratenlimit erreicht. Senden Sie Ihre Anfragen langsamer 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 benutzerdefinierte Integration erstellen möchten oder mit einem Entwickler zusammenarbeiten, der eine passende Lösung für Ihre Anforderungen einrichten kann. Zapier ist nach wie vor die einfachste Möglichkeit, Zeffy mit Tools wie Google Sheets, Slack oder Mailchimp zu verbinden, wenn Ihnen technische Ressourcen fehlen.
Nächste Schritte
Vollständige API-Dokumentation — Detaillierte Referenz zu allen Endpunkten, Parametern und Antwortfeldern.
Wenn Sie Fragen haben oder Hilfe bei der Einrichtung benötigen, wenden Sie sich an unser Support-Team. Wir sind für Sie da.