API-Referenz
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.
API-Root
Alle öffentlichen Endpunkte liegen unter einem gemeinsamen Root und sind nach Bereich gruppiert. <version> steht für v1 oder v2:
| Endpunkt | Beschreibung | Authentifizierung |
|---|---|---|
/api/<version>/crm/donations/ | Spenden in einem Zeitraum | erforderlich |
/api/<version>/crm/contact/donations/ | Alle Spenden eines Kontakts | erforderlich |
/api/<version>/crm/contacts/ | Kontaktliste mit Spendenstatistik | erforderlich |
/api/<version>/campaign-links/<id>/config/ | Öffentliche Spenden-Konfiguration eines Kampagnen-Links | keine |
Interaktive API-Dokumentation
Die vollständige, interaktive API-Referenz findest du hier:
Dort kannst du alle Endpunkte, Parameter und Response-Formate einsehen und direkt testen.
Authentifizierung
Die CRM-Endpunkte unterstützen zwei Authentifizierungsmethoden:
| Methode | Beschreibung |
|---|---|
| JWT Bearer Token | Token-basierte Authentifizierung (empfohlen für automatisierte Zugriffe), Token über /authentication/create |
| HTTP Basic Auth | Benutzername und Passwort eines Admin-Kontos |
Dafür ist ein Admin-Konto erforderlich. Erstelle bei Bedarf ein separates Konto mit eingeschränkten Rechten für API-Zugriffe. Die Konfiguration eines Kampagnen-Links ist öffentlich und benötigt keine Zugangsdaten.
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 |
Ein Wechsel bedeutet nur einen anderen Root, Endpunkte, Parameter und Authentifizierung bleiben identisch. Neue optionale Parameter und neue Endpunkte kommen jederzeit dazu, ohne dass sich die Version ändert: Eine Integration muss unbekannte Felder deshalb ignorieren.
Swagger auf deiner Instanz
Zusätzlich zur API-Referenz oben steht auf jeder Soulclick-Instanz eine Swagger-UI bereit:
https://<deine-instanz>/api/swagger/Wähle dort oben die Version und teste Anfragen direkt gegen deine eigene Instanz.
Frühere Präfixe
Die CRM-Endpunkte waren früher unter einem eigenen Präfix erreichbar. Dieses bleibt unverändert aktiv, damit bestehende Integrationen weiterlaufen. Für neue Integrationen gilt der versionierte Root.
| Bisher | Neu |
|---|---|
/crm-api/<endpunkt>/ | /api/<version>/crm/<endpunkt>/ |
Die Swagger-UI unter /crm-api/swagger/ bleibt ebenfalls erreichbar und ist dort als Legacy gekennzeichnet.
Updated 4 days ago