API-Referenz Übersicht: Soulclick

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/v1/

Ersetze <deine-instanz> durch die Domain deiner Soulclick-Plattform.

Versionierung

Die Version steht im Pfad, aktuell gilt /api/v1. Ergänzungen wie neue Felder, neue optionale Parameter oder neue Endpunkte kommen jederzeit dazu, ohne dass sich die Version ändert – eine Integration muss deshalb unbekannte Felder ignorieren. Nur ein Breaking Change führt zu einer neuen Version: sie erscheint dann als /api/v2, während /api/v1 unverändert weiterläuft.

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/v1/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/v1/crm/donations/?dateFrom=01-01-2024&dateTo=12-31-2024
Authorization: Basic base64(username:password)

API-Endpunkte

Methode	Pfad	Beschreibung	Authentifizierung
`GET`	`/api/v1/crm/donations/`	Spenden nach Zeitraum abfragen	erforderlich
`GET`	`/api/v1/crm/contact/donations/`	Alle Spenden einer Kontaktperson	erforderlich
`GET`	`/api/v1/crm/contacts/`	Kontaktliste mit Spendenstatistik (paginiert)	erforderlich
`GET`	`/api/v1/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 2024

Umgebung (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/v1/swagger/

Dort kannst du Anfragen direkt gegen deine eigene Instanz testen.