Soulclick bietet eine REST-API für den programmatischen Zugriff auf Spenden- und Kontaktdaten sowie auf die Spenden-Konfiguration von Kampagnen-Links. Die API eignet sich für CRM-Integrationen, Reporting-Tools, eigene Auswertungen und selbst gebaute Spenden-Teaser.
Base-URL
https://<deine-instanz>/api/v2.1/Ersetze <deine-instanz> durch die Domain deiner Soulclick-Plattform. Bestehende Integrationen auf v1 oder v2 bleiben unter https://<deine-instanz>/api/v1/ bzw. https://<deine-instanz>/api/v2/ unverändert erreichbar.
Versionierung
Die Version steht im Pfad. Jede Version bleibt verfügbar und antwortet weiterhin so, wie du sie integriert hast: Ein später ergänztes Feld kommt in einer älteren Version nicht dazu.
| Version | Root | Enthält |
|---|---|---|
v1 | /api/v1/ | Die bisherige Payload, ebenso unter /crm-api/ |
v2 | /api/v2/ | Zusätzlich custom_fields: die Antworten der Kontaktperson auf die eigenen Felder des Spendenformulars |
v2.1 | /api/v2.1/ | Zusätzlich checkout an jedem Eintrag von /crm/donations/, mit Nummer, Gesamtbetrag und Währung des Multi-Checkouts, und positions an jeder Spende eines Kontakts, mit Betrag, Kampagne, Spendenzweck und Zahlungsart jeder Position. Jeder Betrag ist, was bezahlt wurde, inklusive der Gebühren, die die spendende Person übernommen hat, in der Währung der Spende. Zeitangaben stehen in UTC mit Z |
Alle Versionen sind unten als eigener Abschnitt dokumentiert: Soulclick API v2.1, Soulclick API v2 und Soulclick API v1. Sie bieten dieselben Endpunkte, Parameter und Authentifizierung; eine ältere Version liefert eine Teilmenge der Felder. Ab v2.1 ist ein Multi-Checkout bei den Spenden eines Kontakts ein einziger Eintrag mit dem Gesamtbetrag, und die Kontaktliste zählt ihn als eine Spende; vor v2.1 erscheint jede Position als eigene Spende. Für neue Integrationen gilt v2.1.
Neue optionale Parameter und neue Endpunkte kommen jederzeit dazu, ohne dass sich die Version ändert: Eine Integration muss unbekannte Felder deshalb ignorieren.
Authentifizierung
Die API unterstützt zwei Authentifizierungsmethoden. Beide erfordern ein Admin-Konto (Staff-Berechtigung).
JWT Bearer Token (empfohlen)
Token-basierte Authentifizierung über JSON Web Tokens. Empfohlen für automatisierte Zugriffe und Integrationen.
Token anfordern:
POST /authentication/create
Content-Type: application/json
{
"username": "[email protected]",
"password": "your-password"
}Antwort:
{
"access": "eyJ0eXAiOiJKV1Qi...",
"refresh": "eyJ0eXAiOiJKV1Qi..."
}Token verwenden:
GET /api/v2.1/crm/donations/?dateFrom=01-01-2024&dateTo=12-31-2024
Authorization: Bearer eyJ0eXAiOiJKV1Qi...Token-Endpunkte:
| Endpunkt | Methode | Beschreibung |
|---|---|---|
/authentication/create | POST | Access- und Refresh-Token anfordern |
/authentication/refresh | POST | Neuen Access-Token mit Refresh-Token anfordern |
/authentication/verify | POST | Token auf Gültigkeit prüfen |
/authentication/logout | POST | Refresh-Token sperren (Blacklist) |
Token-Gültigkeit:
| Token | Gültigkeit |
|---|---|
| Access-Token | 5 Minuten |
| Refresh-Token | 1 Tag |
Refresh-Tokens werden nach Verwendung automatisch rotiert und der alte Token gesperrt.
HTTP Basic Auth
Für einfache Integrationen, die keine Token-Verwaltung benötigen:
GET /api/v2.1/crm/donations/?dateFrom=01-01-2024&dateTo=12-31-2024
Authorization: Basic base64(username:password)API-Endpunkte
| Methode | Pfad | Beschreibung | Authentifizierung |
|---|---|---|---|
GET | /api/v2.1/crm/donations/ | Spenden nach Zeitraum abfragen | erforderlich |
GET | /api/v2.1/crm/contact/donations/ | Alle Spenden einer Kontaktperson | erforderlich |
GET | /api/v2.1/crm/contacts/ | Kontaktliste mit Spendenstatistik (paginiert) | erforderlich |
GET | /api/v2.1/campaign-links/<id>/config/ | Spenden-Konfiguration eines Kampagnen-Links | keine |
Die vollständige Dokumentation zu Parametern und Response-Formaten findest du in den einzelnen Endpunkt-Seiten unten.
Datumsformat
Alle Datumsparameter verwenden das Format MM-DD-YYYY (Monat-Tag-Jahr):
dateFrom=01-15-2024 → 15. Januar 2024
dateTo=12-31-2024 → 31. Dezember 2024Umgebung (Environment)
Jede Soulclick-Instanz verarbeitet Zahlungen in zwei Umgebungen:
| Wert | Beschreibung |
|---|---|
TEST | Testspenden (Standard, wenn kein Wert angegeben) |
PRODUCTION | Produktive Spenden |
Für Produktivdaten immer environment=PRODUCTION angeben.
Zahlungsmethoden-Codes
Zahlungsmethoden werden als Kürzel zurückgegeben:
| Kürzel | Zahlungsmethode |
|---|---|
VIS | Visa |
ECA | Mastercard |
TWI | TWINT |
PAP | PayPal |
PFC | PostFinance Card |
PEF | PostFinance E-Finance |
INV | QR-Rechnung |
Spendentypen
Spenden werden mit einem payment_type zurückgegeben:
| Typ | Beschreibung |
|---|---|
single | Einmalige Spende |
recurring_init | Erstspende einer Dauerspende |
recurring_interval | Folge-Intervall einer Dauerspende (Karte oder QR-Rechnung) |
crowdfunding | Crowdfunding-Spende |
Fehler-Responses
Bei Fehlern gibt die API einen JSON-Body mit error-Feld zurück:
{
"error": "please provide dateTo and dateFrom"
}| Status | Beschreibung |
|---|---|
400 | Ungültige Parameter (fehlende Pflichtfelder, falsches Format) |
401 | Fehlende oder ungültige Authentifizierung |
403 | Kein Admin-Zugriff (Konto ohne Staff-Berechtigung) |
404 | Kontaktperson nicht gefunden |
Swagger-UI
Auf jeder Soulclick-Instanz steht eine interaktive Swagger-Dokumentation bereit:
https://<deine-instanz>/api/swagger/Wähle dort oben die Version und teste Anfragen direkt gegen deine eigene Instanz.