Einrichtung
Für Die Anbindung zwischen CiviCRM und twingle wird eine Extentsion 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.
Verzögerte Übertragung
Bei Bedarf kann dies mit einer Verzögerung passieren, so dass auch nachgelieferte Kontaktdaten zu CiviCRM übertragen werden. Diese Verzögerung können Sie 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 bekommen Sie 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.
- 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":15,"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.
- Bei Bestellungen im Spendenshop wird in den products ein Array übergeben mit diesen Feldern: id, name, internal_id, count, price, total_value.