Einrichtung
Für die Anbindung zwischen CiviCRM und twingle wird eine Extension am CiviCRM benötigt. Diese wird von Systopia gepflegt. Informationen zur Einrichtung der Schnittstelle gibt es hier: https://docs.civicrm.org/twingle/en/latest/.
Um die Anbindung in twingle einzurichten müssen folgende Schritte ausgeführt werden:
1. Einloggen im twingleMANAGER
2. Öffnen der Einstellungen und hinterlegen der Zugangsdaten im Reiter Allgemein:
Wichtig: Die URL muss immer die vollständige URL zur Schnittstelle sein. Beispiele:
- Drupal (with the AuthX extension): https://example.org/civicrm/ajax/rest
- Drupal (legacy method): https://example.org/sites/all/modules/civicrm/extern/rest.php
- Wordpress (with CiviCRM < 5.25): https://example.org/wp-content/plugins/civicrm/civicrm/extern/rest.php
- Wordpress (with CiviCRM 5.25+): https://example.org/wp-json/civicrm/v3/rest
Hinweis für Wordpress: Schützt man seine Wordpress-Seite vor unautorisiertem Zugriff mit einem Plugin wie "Disable REST API", muss im Plugin der entsprechende Endpunkt geöffnet werden.
3. Aktivieren der Datenübertragung in den Projekteinstellungen aller Projekte wo dies notwendig ist im Reiter Kontaktdaten & Einbindung:
Nach der Aktivierung werden alle Transaktionen an das verknüpfte System geschickt.
Eine Liste der twingle-Felder, die an CiviCRM übermittelt werden, kann hier eingesehen werden.
Testen der Einrichtung
Wenn du die Zugangsdaten eingetragen hast und ein Projekt für die Übertragung aktiviert hast, kannst du im twingleMANAGER eine Testspende anlegen und prüfen ob diese übertragen wird. Öffne dazu das Dashboard, scrolle bis zur Liste der Zahlungen und lege über den Button "Neu" eine Zahlung mit der Zahlungsart "Überweisung" an. Diese sollte kurze Zeit später, je nach eingestellter Verzögerung, bei dir im CiviCRM zu sehen sein.
Setze die Spende danach auf "fehlgeschlagen", so vermeidest du Fehler in der Statistik.
Verzögerte Übertragung
Bei Bedarf kann dies mit einer Verzögerung passieren, so dass auch nachgelieferte Kontaktdaten zu CiviCRM übertragen werden. Diese Verzögerung kannst du in den Einstellungen konfigurieren. Der Standard sind 15min.
Hinweise:
- Sollte bei der Verbindung ein Fehler auftreten, versucht unser System die Daten mehrfach noch einmal zu übertragen. Spätestens nach einem knappen Tag bekommst du eine Info per Mail, wenn die Übertragung gescheitert ist.
- In einigen seltenen Fällen kann es vorkommen, dass gesonderte Felder an CiviCRM übertragen werden sollen. So genannte custom fields. Diese müssen vom twingle Support eingerichtet werden.
- Wird die Spendenseite mit dem Parameter tw_cid aufgerufen (siehe Kann ich meine Kampagnen tracken?), übermittelt twingle den Wert zusätzlich im Feld campaign_id.
- Einige typische Probleme sind auch in diesem Artikel beschrieben: Typische Fehler bei der CiviCRM Anbindung
Beispiel-Request
Für Entwickler ist hier ein Beispiel-Request mit den Daten einer Spende. Dieser Request wird per POST an die konfigurierte CiviCRM-URL geschickt.
{"entity":"TwingleDonation","api_key":"<APIKEY>","key":"<KEY>","action":"submit","json":{"project_id":"twXXXXXXXXXX","trx_id":"XXXXXXX","parent_trx_id":null,"confirmed_at":"20260101081500","booked_at":"20260101082000","purpose":"Allgemeine Spende","amount":1500,"currency":"EUR","remarks":null,"user_email":"mail@example.de","user_country":"DE","user_language":"de","payment_method":"paypal","donation_rhythm":"one_time","is_anonymous":0,"newsletter":0,"postinfo":0,"donation_receipt":0,"user_gender":"female","user_title":null,"user_firstname":"Monika","user_lastname":"Musterfrau","user_street":"Meine Strasse 1","user_postal_code":"12345","user_city":"Oberkirch","user_telephone":null,"user_company":null,"user_extrafield":null,"custom_fields":{"field1": "value1"}}}
Bei der Nutzung dieses Beispiels beachte das Folgende:
- <APIKEY> und <KEY> müssen durch die Zugangsdaten des Systems ersetzt werden.
- Damit du im richtigen Profil landest, musst du die project_id mit einem sinnvollen Wert ersetzen. Diese ist in den Projekteinstellungen zu finden.
- Anhand der trx_id wird eine Doublettenprüfung vorgenommen, diese muss ggf. immer geändert werden.
- Die custom_fields sind in der Regel leer, dort werden nur Werte übergeben, wenn diese vorher vom twingle Support konfiguriert werden.
- Bei der Zahlungsart (payment_method) können auch andere Werte stehen, beispielsweise: creditcard, debit_automatic, debit_manual, banktransfer, applepay, googlepay.
- Bei der Zahlungsart debit_manual werden weitere Felder übertragen: debit_iban, debit_bic, debit_mandate_reference, debit_account_holder.
- Das Feld is_anonymous ist nur auf 1, wenn keine E-Mail-Adresse bekannt ist.
- Die Felder newsletter, postinfo und donation_receipt sind 1, wenn die spendende Person die jeweilige Option gewählt hat.
- Bei Bestellungen im Spendenshop wird in den products ein Array übergeben mit diesen Feldern: id, name, internal_id, count, price, total_value.