--- updatedAt: 2026-08-27T09:05:57.000Z agentTools: projectIndex: https://docs.soulclick.ch/llms.txt --- # Spenden abrufen Liest die Spenden eines Zeitraums. Der Endpunkt liefert alle Spendenarten: - **Bestellungen** (Einmalspenden, Crowdfunding, erste Zahlung einer Dauerspende) - **Online-Dauerspenden** (wiederkehrende Kartenzahlungen) - **Dauerspenden per Rechnung** (wiederkehrende QR-Rechnungen) Sortiert nach Erstellungsdatum, neueste zuerst. ## Authentifizierung Zwei Methoden stehen zur Verfügung: - **JWT Token**: Header `Authorization: Bearer ` - **Basic Auth**: Header `Authorization: Basic ` Beide setzen ein Konto mit Admin-Rechten voraus. ## Datumsformat Alle Datumsangaben im Format **MM-DD-YYYY**, also Monat-Tag-Jahr (`01-15-2024` für den 15. Januar 2024). ## Filter Die Spenden lassen sich einschränken nach: - **Zeitraum**: `dateFrom` und `dateTo` sind erforderlich - **Umgebung**: `TEST` oder `PRODUCTION` - **Zahlungsstatus**: `paid_only=True` liefert nur bestätigte Zahlungen - **E-Mail**: Adresse der spendenden Person - **Anzahl**: maximale Anzahl Ergebnisse # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "Soulclick API v1", "version": "v1", "description": "## Soulclick API\n\nDie öffentliche API einer Soulclick-Plattform: Spenden- und Kontaktdaten für Drittsysteme sowie die\nSpenden-Konfiguration von Kampagnen-Links für selbst gebaute Spenden-Teaser.\n\n**Dieses Dokument beschreibt `/api/v1/`** und listet genau die Felder auf, die diese Version\nzurückgibt. Die Versionsauswahl oben auf `/api/swagger/` wechselt zwischen den Dokumenten.\n\n### API-Root\n\nAlle öffentlichen Endpunkte liegen unter einem gemeinsamen, versionierten Root und sind nach Bereich\ngruppiert:\n\n- `/api/v1/crm/*` – Spenden- und Kontaktdaten (Authentifizierung erforderlich)\n- `/api/v1/campaign-links//config/` – öffentliche Spenden-Konfiguration eines Kampagnen-Links\n\nDie CRM-Endpunkte sind weiterhin auch unter ihrem früheren Prefix `/crm-api/*` erreichbar, das genau\nwie bisher antwortet – `v1`-Payloads – und für laufende Integrationen bestehen bleibt. Neue\nIntegrationen verwenden die neuste Version.\n\n### Authentifizierung\n\nDie CRM-Endpunkte unterstützen zwei Methoden:\n\n1. **JWT Bearer Token**\n - Token über `/authentication/create` beziehen\n - Header: `Authorization: Bearer `\n\n2. **HTTP Basic Auth**\n - Header: `Authorization: Basic `\n - Praktisch für einfache Integrationen und externe Anbieter\n\nBeide setzen ein Konto mit Admin-Rechten voraus. Die Konfiguration eines Kampagnen-Links ist\nöffentlich und benötigt keine Zugangsdaten.\n\n### Umgebungen\n\nDie CRM-Endpunkte lesen aus zwei Umgebungen:\n- `TEST` – Testdaten\n- `PRODUCTION` – echte Daten\n\n### Seitenweises Lesen\n\n`next` und `previous` verweisen auf dasselbe Prefix wie die Anfrage: ein Aufruf von\n`/api/v1/crm/contacts/` erhält wieder `/api/v1/crm/contacts/`-Links zurück, ein Aufruf\nüber das alte Prefix entsprechend alte Links.\n\n### Versionierung und Kompatibilität\n\nDie Version steht im Pfad. Jede Version bleibt verfügbar und antwortet weiterhin genau so wie zum\nZeitpunkt der Integration: ein später eingeführtes Feld kommt nicht mehr dazu.\n\n| Version | Root | Eingeführt |\n|:---|:---|:---|\n| `v1` | `/api/v1/` | Die ursprüngliche Antwort. Das liefert auch `/crm-api/*`. |\n| `v2` | `/api/v2/` | `custom_fields`: die Antworten der spendenden Person auf die eigenen Checkout-Felder der Plattform, am Kontakt einer Spende. |\n| `v2.1` | `/api/v2.1/` | `checkout` an jedem Spendeneintrag und `positions` an jeder Spende eines Kontakts: ein Multi-Checkout ist ein Eintrag mit allen Positionen. 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`. |\n\nEin Wechsel auf eine höhere Version heisst, einen anderen Root aufzurufen; an der Anfrage ändert\nsich sonst nichts, und Endpunkte, Parameter und Authentifizierung sind über alle Versionen gleich.\n\nEine Integration **muss** trotzdem:\n- unbekannte JSON-Felder ignorieren statt die Antwort abzulehnen\n- sich nicht auf die Reihenfolge der Felder verlassen\n- nicht davon ausgehen, dass die Feldliste abgeschlossen ist\n\nManche Änderungen lassen sich nicht über eine Version zurückhalten – ein neuer Enum-Wert in einem als\nerweiterbar dokumentierten Feld oder ein neuer Endpunkt – und können jederzeit erscheinen. Ein\n**Breaking Change** (ein Feld entfernen oder umbenennen, den Typ eines Feldes ändern, ein Feld\nerforderlich oder optional machen, die Authentifizierung ändern) kommt in die nächste Version und\nwird vorab über den vereinbarten Support-Kanal angekündigt und abgestimmt." }, "paths": { "/api/v1/crm/donations/": { "get": { "operationId": "api_v1_crm_donations_list", "description": "Liest die Spenden eines Zeitraums.\n\nDer Endpunkt liefert alle Spendenarten:\n- **Bestellungen** (Einmalspenden, Crowdfunding, erste Zahlung einer Dauerspende)\n- **Online-Dauerspenden** (wiederkehrende Kartenzahlungen)\n- **Dauerspenden per Rechnung** (wiederkehrende QR-Rechnungen)\n\nSortiert nach Erstellungsdatum, neueste zuerst.\n\n## Authentifizierung\n\nZwei Methoden stehen zur Verfügung:\n- **JWT Token**: Header `Authorization: Bearer `\n- **Basic Auth**: Header `Authorization: Basic `\n\nBeide setzen ein Konto mit Admin-Rechten voraus.\n\n## Datumsformat\n\nAlle Datumsangaben im Format **MM-DD-YYYY**, also Monat-Tag-Jahr (`01-15-2024` für den 15. Januar 2024).\n\n## Filter\n\nDie Spenden lassen sich einschränken nach:\n- **Zeitraum**: `dateFrom` und `dateTo` sind erforderlich\n- **Umgebung**: `TEST` oder `PRODUCTION`\n- **Zahlungsstatus**: `paid_only=True` liefert nur bestätigte Zahlungen\n- **E-Mail**: Adresse der spendenden Person\n- **Anzahl**: maximale Anzahl Ergebnisse", "summary": "Spenden abrufen", "parameters": [ { "in": "query", "name": "dateFrom", "schema": { "type": "string" }, "description": "Startdatum des Zeitraums (Format: MM-DD-YYYY)", "required": true, "examples": { "ExampleDate": { "value": "01-01-2024", "summary": "Beispieldatum", "description": "1. Januar 2024" } } }, { "in": "query", "name": "dateTo", "schema": { "type": "string" }, "description": "Enddatum des Zeitraums (Format: MM-DD-YYYY)", "required": true, "examples": { "ExampleDate": { "value": "12-31-2024", "summary": "Beispieldatum", "description": "31. Dezember 2024" } } }, { "in": "query", "name": "email", "schema": { "type": "string" }, "description": "Spenden nach der E-Mail-Adresse der spendenden Person filtern (exakte Übereinstimmung)", "examples": { "FilterByEmail": { "value": "max.muster@example.com", "summary": "Nach E-Mail filtern", "description": "Nur Spenden von dieser E-Mail-Adresse" } } }, { "in": "query", "name": "environment", "schema": { "type": "string", "enum": [ "PRODUCTION", "TEST" ], "default": "TEST" }, "description": "Umgebung, aus der gelesen wird", "examples": { "TestEnvironment": { "value": "TEST", "summary": "Testumgebung", "description": "Spenden aus der Testumgebung" }, "ProductionEnvironment": { "value": "PRODUCTION", "summary": "Produktivumgebung", "description": "Echte Spenden aus der Produktivumgebung" } } }, { "in": "query", "name": "limit", "schema": { "type": "integer", "default": 0 }, "description": "Maximale Anzahl Ergebnisse (0 = keine Begrenzung)", "examples": { "NoLimit": { "summary": "Keine Begrenzung", "description": "Alle passenden Spenden" }, "LimitTo100": { "value": 100, "summary": "Auf 100 begrenzen", "description": "Maximal 100 Spenden" } } }, { "in": "query", "name": "paid_only", "schema": { "type": "string", "enum": [ "False", "True" ], "default": "False" }, "description": "Nur bestätigte, bezahlte Spenden zurückgeben", "examples": { "AllDonations": { "value": "False", "summary": "Alle Spenden", "description": "Alle Spenden unabhängig vom Zahlungsstatus" }, "PaidOnly": { "value": "True", "summary": "Nur bezahlte", "description": "Nur bestätigte, bezahlte Spenden" } } } ], "tags": [ "Spenden" ], "security": [ { "AdminJWTAuth": [] }, { "AdminBasicAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DonationResponseSchema" } }, "examples": { "SuccessfulResponse": { "value": [ [ { "environment": "PRODUCTION", "contact_id": 12345, "contact_type": "private", "gender": "male", "company": "", "email": "max.muster@example.com", "first_name": "Max", "last_name": "Muster", "postal_code": "8000", "city": "Zürich", "street": "Bahnhofstrasse", "street_number": "1", "po_box": "", "country": "CH", "language": "de", "orders": [ { "id": "ORD-2024-001234", "initial_order_nr": "", "created_at": "2024-06-15T14:30:00Z", "amount": "50.00", "currency": "CHF", "campaign": { "id": 42, "title": "General Donation" }, "purpose": "Wildlife Conservation", "payment": { "transaction_id": "TXN123456", "method": "VIS", "status": "completed", "paid_out_amount": 47.85, "fee_amount": 2.15, "reconciled": true }, "invoice": null, "payment_type": "single", "payment_interval": null } ] } ] ], "summary": "Erfolgreiche Antwort" } } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseSchema" }, "examples": { "MissingDateParameters": { "value": { "error": "please provide dateTo and dateFrom" }, "summary": "Fehlende Datumsangaben" }, "InvalidEnvironment": { "value": { "error": "please provide environment as 'TEST' or 'PRODUCTION'" }, "summary": "Ungültige Umgebung" } } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "Inhalt nicht näher beschrieben" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "type": "object", "additionalProperties": {}, "description": "Inhalt nicht näher beschrieben" } } }, "description": "" } } } } }, "components": { "schemas": { "BlankEnum": { "enum": [ "" ] }, "CampaignSchema": { "type": "object", "description": "Angaben zur Spendenaktion einer Spende.", "properties": { "id": { "type": "integer", "description": "Datenbank-ID der Spendenaktion" }, "title": { "type": "string", "description": "Titel der Spendenaktion" } }, "required": [ "id", "title" ] }, "ContactTypeEnum": { "enum": [ "private", "company" ], "type": "string", "description": "* `private` - private\n* `company` - company" }, "DonationResponseSchema": { "type": "object", "description": "Eine Spende in der Antwort der API.\n\nSie beschreibt einen Kontakt mit den zugehörigen Bestellungen.", "properties": { "environment": { "allOf": [ { "$ref": "#/components/schemas/EnvironmentEnum" } ], "description": "Umgebung, in der die Spende verarbeitet wurde\n\n* `TEST` - TEST\n* `PRODUCTION` - PRODUCTION" }, "contact_id": { "type": "integer", "description": "Eindeutige Kennung des Kontakts" }, "contact_type": { "allOf": [ { "$ref": "#/components/schemas/ContactTypeEnum" } ], "description": "Art des Kontakts: private oder company\n\n* `private` - private\n* `company` - company" }, "gender": { "description": "Anrede des Kontakts\n\n* `male` - male\n* `female` - female\n* `prefer-not-to-say` - prefer-not-to-say\n* `` -", "oneOf": [ { "$ref": "#/components/schemas/GenderEnum" }, { "$ref": "#/components/schemas/BlankEnum" } ] }, "company": { "type": "string", "description": "Firmenname (nur bei Firmenkontakten)" }, "email": { "type": "string", "format": "email", "description": "E-Mail-Adresse des Kontakts" }, "first_name": { "type": "string", "description": "Vorname des Kontakts" }, "last_name": { "type": "string", "description": "Nachname des Kontakts" }, "postal_code": { "type": "string", "description": "Postleitzahl" }, "city": { "type": "string", "description": "Ort" }, "street": { "type": "string", "description": "Strasse" }, "street_number": { "type": "string", "description": "Hausnummer" }, "po_box": { "type": "string", "description": "Postfach oder Adresszusatz" }, "country": { "type": "string", "description": "Ländercode nach ISO 3166-1 alpha-2 (z. B. CH, DE, FR)" }, "language": { "allOf": [ { "$ref": "#/components/schemas/LanguageEnum" } ], "description": "Bevorzugte Korrespondenzsprache\n\n* `de` - de\n* `fr` - fr\n* `it` - it\n* `en` - en" }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/OrderDetailSchema" }, "description": "Bestellungen dieses Kontakts" } }, "required": [ "city", "company", "contact_id", "contact_type", "country", "email", "environment", "first_name", "gender", "language", "last_name", "orders", "po_box", "postal_code", "street", "street_number" ] }, "EnvironmentEnum": { "enum": [ "TEST", "PRODUCTION" ], "type": "string", "description": "* `TEST` - TEST\n* `PRODUCTION` - PRODUCTION" }, "ErrorResponseSchema": { "type": "object", "description": "Antwort im Fehlerfall.", "properties": { "error": { "type": "string", "description": "Fehlermeldung mit der Ursache" } }, "required": [ "error" ] }, "GenderEnum": { "enum": [ "male", "female", "prefer-not-to-say" ], "type": "string", "description": "* `male` - male\n* `female` - female\n* `prefer-not-to-say` - prefer-not-to-say\n* `` -" }, "LanguageEnum": { "enum": [ "de", "fr", "it", "en" ], "type": "string", "description": "* `de` - de\n* `fr` - fr\n* `it` - it\n* `en` - en" }, "OrderDetailSchema": { "type": "object", "description": "Eine einzelne Bestellung einer Spende.", "properties": { "id": { "type": "string", "description": "Eindeutige Bestellnummer" }, "initial_order_nr": { "type": "string", "description": "Bestellnummer der ersten Zahlung einer Dauerspende (leer bei Einmalspenden)" }, "created_at": { "type": "string", "format": "date-time", "description": "Datum und Zeit der Zahlung (Format ISO 8601)" }, "amount": { "type": "string", "format": "decimal", "pattern": "^-?\\d{0,8}(?:\\.\\d{0,2})?$", "description": "Gesamtbetrag (Anzahl × Einzelpreis). Ab `v2.1`: was bezahlt wurde, inklusive der von der spendenden Person übernommenen Gebühren, in `currency`." }, "currency": { "type": "string", "description": "Währungscode (z. B. CHF, EUR, USD)" }, "campaign": { "allOf": [ { "$ref": "#/components/schemas/CampaignSchema" } ], "description": "Angaben zur Spendenaktion" }, "purpose": { "type": "string", "description": "Spendenzweck" }, "payment": { "allOf": [ { "$ref": "#/components/schemas/PaymentSchema" } ], "description": "Angaben zur Zahlung" }, "invoice": { "type": "string", "nullable": true, "description": "Referenznummer der QR-Rechnung (bei Rechnungszahlungen)" }, "payment_type": { "allOf": [ { "$ref": "#/components/schemas/PaymentType10fEnum" } ], "description": "Art der Zahlung: single, recurring_init, recurring_interval oder crowdfunding\n\n* `single` - single\n* `recurring_init` - recurring_init\n* `recurring_interval` - recurring_interval\n* `crowdfunding` - crowdfunding" }, "payment_interval": { "type": "string", "nullable": true, "description": "Intervall der Dauerspende (z. B. monatlich, jährlich)" } }, "required": [ "amount", "campaign", "created_at", "currency", "id", "initial_order_nr", "invoice", "payment", "payment_interval", "payment_type", "purpose" ] }, "PaymentSchema": { "type": "object", "description": "Angaben zur Zahlung einer Spende.", "properties": { "transaction_id": { "type": "string", "description": "Transaktions-ID der Zahlung" }, "method": { "type": "string", "description": "Verwendete Zahlungsart (z. B. VIS, ECA, TWI, PAP, INV)" }, "status": { "type": "string", "description": "Zahlungsstatus (completed oder pending)" }, "paid_out_amount": { "type": "number", "format": "double", "nullable": true, "description": "Von Stripe ausgezahlter Netto-Betrag nach Gebühren (null ohne Stripe oder vor dem Abgleich)" }, "fee_amount": { "type": "number", "format": "double", "nullable": true, "description": "Von Stripe abgezogene Gebühr (null ohne Stripe oder vor dem Abgleich)" }, "reconciled": { "type": "boolean", "description": "Ob die Zahlung mit den BalanceTransaction-Daten von Stripe abgeglichen ist" } }, "required": [ "fee_amount", "method", "paid_out_amount", "reconciled", "status", "transaction_id" ] }, "PaymentType10fEnum": { "enum": [ "single", "recurring_init", "recurring_interval", "crowdfunding" ], "type": "string", "description": "* `single` - single\n* `recurring_init` - recurring_init\n* `recurring_interval` - recurring_interval\n* `crowdfunding` - crowdfunding" } }, "securitySchemes": { "AdminBasicAuth": { "type": "http", "scheme": "basic", "description": "Basic-Authentifizierung, erfordert Admin-Rechte" }, "AdminJWTAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "JWT-Authentifizierung, erfordert Admin-Rechte" } } }, "tags": [ { "name": "Spenden", "description": "Spendendaten lesen" } ] } ```