Hier werden die Unterschiede zwischen zwei Versionen angezeigt.
Nächste Überarbeitung | Vorhergehende ÜberarbeitungNächste ÜberarbeitungBeide Seiten der Revision | ||
de:survey:mailing-api [30.01.2018 20:19] – angelegt admin | de:survey:mailing-api [30.03.2023 17:12] – [Manueller Aufruf] admin | ||
---|---|---|---|
Zeile 6: | Zeile 6: | ||
* Optional den Versand einzelner Serienmails auslösen, ebenfalls automatisiert durch eine externe Software. | * Optional den Versand einzelner Serienmails auslösen, ebenfalls automatisiert durch eine externe Software. | ||
* Personalisierte Links zum Fragebogen erstellen, die genauso funktionieren wie die personalisierten Links in Serienmails. | * Personalisierte Links zum Fragebogen erstellen, die genauso funktionieren wie die personalisierten Links in Serienmails. | ||
+ | * Abruf des Teilnahmestatus für ein Serienmail. | ||
Eine wesentliche Anwendung der API-Funktion für Serienmails ist die Anbindung eines Shop-Systems. So kann man einem Kunden etwa nach Kauf der Zugangsberechtigung einen gültigen Teilnahme-Link zum Fragebogen übermitteln. | Eine wesentliche Anwendung der API-Funktion für Serienmails ist die Anbindung eines Shop-Systems. So kann man einem Kunden etwa nach Kauf der Zugangsberechtigung einen gültigen Teilnahme-Link zum Fragebogen übermitteln. | ||
Zeile 12: | Zeile 13: | ||
===== Hintergrund ===== | ===== Hintergrund ===== | ||
- | Für gewöhnlich erstellt SoSci Survey eine personalisierten URL zur Teilnahme an einer Befragung in dem Moment, wenn Sie eine [[: | + | Für gewöhnlich erstellt SoSci Survey eine personalisierten URL zur Teilnahme an einer Befragung in dem Moment, wenn Sie eine [[: |
- | Mit der Funktion **Einladungen verschicken** -> **API-Zugriff** können Sie personalisierte Links zum Fragebogen erstellen und ggf. in einer externen Software verwenden, die genauso funktionieren wie die personalisierten Links in Serienmails. Allerdings wird dabei keine E-Mail verschickt | + | Mit der Funktion **Einladungen verschicken** -> **API-Zugriff** können Sie personalisierte Links zum Fragebogen erstellen und ggf. in einer externen Software verwenden, die genauso funktionieren wie die personalisierten Links in Serienmails. Allerdings wird dabei nicht zwangsläufig eine E-Mail verschickt. Wenn keine Serienmail verschickt werden soll, ist nicht einmal eine E-Mail-Adresse notwendig. |
- | ===== Verwendung | + | ===== Adresseinträge erstellen |
- | * Legen Sie zunächst unter **Einladungen verschicken** -> **Serienmails** eine neue Serienmail an. Diese wird zwar nicht verschickt, | + | * Legen Sie zunächst unter **Einladungen verschicken** -> **Serienmails** eine neue Serienmail an. Diese wird nicht zwangsläufig |
* Anschließend wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** diese // | * Anschließend wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** diese // | ||
* Mit dem Speichern-Symbol {{: | * Mit dem Speichern-Symbol {{: | ||
- | Beim Aufruf der API-URL erwartet SoSci Survey, dass eines der folgenden Identifikationsmerkmale für den (eventuell neuen) Adresseintrag mittels GET oder POST übermittelt wird: | + | Beim Aufruf der API-URL erwartet SoSci Survey, dass mindestens |
* //email// E-Mail-Adresse | * //email// E-Mail-Adresse | ||
* //mobile// Mobil-Nummer für SMS-Versand | * //mobile// Mobil-Nummer für SMS-Versand | ||
- | * //uid// Eindeutige Kennung für den Adressat | + | * //uid// Eindeutige Kennung für den Adressat |
Wenn die API-URL '' | Wenn die API-URL '' | ||
Zeile 33: | Zeile 34: | ||
https:// | https:// | ||
- | Falls ein passender Eintrag in der Adressliste gefunden wird, wird diese verwendet. Ansonsten wird unter **Einladungen verschicken** -> **Adressliste** ein neuer Eintrag erstellt. | + | Falls ein passender Eintrag in der Adressliste gefunden wird, wird dieser |
SoSci Survey erstellt nun einen gültigen Teilnahmelink und übermittelt diesen als Antwort auf den Aufruf als JSON zurück. | SoSci Survey erstellt nun einen gültigen Teilnahmelink und übermittelt diesen als Antwort auf den Aufruf als JSON zurück. | ||
- | ===== Rückgabewert | + | ==== Rückgabewert ==== |
Die Antwort auf eine gültige Anfrage könnte etwa wie folgt aussehen: | Die Antwort auf eine gültige Anfrage könnte etwa wie folgt aussehen: | ||
Zeile 62: | Zeile 63: | ||
- | ===== Manueller Aufruf | + | ==== Manueller Aufruf ==== |
Der **API-Zugriff** ist eigentlich für einen automatisierten Aufruf durch eine externe Software ausgelegt (Maschine-zu-Maschine Kommunikation), | Der **API-Zugriff** ist eigentlich für einen automatisierten Aufruf durch eine externe Software ausgelegt (Maschine-zu-Maschine Kommunikation), | ||
Legen Sie dafür einen API-Link an, wie oben beschrieben. Rufen Sie anschließend die API-URL mit unterschiedlichen Identifikationsmerkmalen auf. Etwa mit den Kennungen '' | Legen Sie dafür einen API-Link an, wie oben beschrieben. Rufen Sie anschließend die API-URL mit unterschiedlichen Identifikationsmerkmalen auf. Etwa mit den Kennungen '' | ||
+ | |||
+ | Die Teilnehmer-ID muss dabei jeweils manuell in die Adresszeile eingetragen werden. | ||
https:// | https:// | ||
Zeile 74: | Zeile 77: | ||
Ihr Browser zeigt nach jedem Aufruf eine gültige Teilnahme-URL an, die etwa per E-Mail an die Teilnehmer verschickt werden kann. | Ihr Browser zeigt nach jedem Aufruf eine gültige Teilnahme-URL an, die etwa per E-Mail an die Teilnehmer verschickt werden kann. | ||
- | Eine Funktion zum automatisierten Erstellen einer größeren Anzahl von Teilnahmelinks ohne externe Software ist in Planung, derzeit allerdings nur mit geringer Priorität. Falls die Anonymität nicht kritisch ist (oder wenn sie ganz besonders kritisch ist), kann dafür die [[: | + | Eine Funktion zum automatisierten Erstellen einer größeren Anzahl von Teilnahmelinks ohne externe Software ist in Planung, derzeit allerdings nur mit geringer Priorität. Falls die Anonymität nicht kritisch ist (oder wenn sie ganz besonders kritisch ist), kann dafür die [[: |
+ | |||
+ | |||
+ | ===== Teilnahmestatus Seriennummer ===== | ||
+ | |||
+ | * Wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** bei // | ||
+ | * Mit dem Speichern-Symbol {{: | ||
+ | |||
+ | Beim Aufruf der API-URL erwartet SoSci Survey, dass ein Parameter //serial// mit der zu prüfenden Seriennummer übermittelt wird. | ||
+ | |||
+ | Wenn die API-URL '' | ||
+ | |||
+ | https:// | ||
+ | |||
+ | Als Rückgabewert wird ein JSON-String mit folgender Struktur geliefert: | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | result: | ||
+ | code: " | ||
+ | started: | ||
+ | completed: false, | ||
+ | notice: | ||
+ | error: | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | Die Attribute haben die folgende Bedeutung: | ||
+ | |||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * '' | ||
+ | * "not found" -- Die gesuchte Seriennummer ist im Befragungsprojekt nicht bekannt | ||
+ | |||
+ | Im Fehlerfall wird nur der Status-Code und eine Fehlermeldung zurückgegeben, | ||
+ | |||
+ | <code javascript> | ||
+ | { | ||
+ | result: | ||
+ | error: | ||
+ | code: " | ||
+ | } | ||
+ | </ |