Unterschiede

Hier werden die Unterschiede zwischen zwei Versionen angezeigt.

Link zu dieser Vergleichsansicht

Beide Seiten der vorigen Revision Vorhergehende Überarbeitung
de:survey:mailing-api [21.01.2019 21:55]
admin [Verwendung]
de:survey:mailing-api [21.01.2019 22:43] (aktuell)
admin Neu: Abruf des Seriennummer-Status
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 17: Zeile 18:
  
  
-===== Verwendung ​=====+===== Adresseinträge erstellen ​=====
  
   * Legen Sie zunächst unter **Einladungen verschicken** -> **Serienmails** eine neue Serienmail an. Diese wird zwar nicht verschickt, aber hier können Sie alle Einstellungen für den Link vornehmen und den Teilnahmestatus kontrollieren.   * Legen Sie zunächst unter **Einladungen verschicken** -> **Serienmails** eine neue Serienmail an. Diese wird zwar nicht verschickt, aber hier können Sie alle Einstellungen für den Link vornehmen und den Teilnahmestatus kontrollieren.
Zeile 38: Zeile 39:
  
  
-===== 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),​ kann auch dafür "​missbraucht"​ werden, manuell gültige Teilnahme-Links zu erstellen. Der **API-Zugriff** ist eigentlich für einen automatisierten Aufruf durch eine externe Software ausgelegt (Maschine-zu-Maschine Kommunikation),​ kann auch dafür "​missbraucht"​ werden, manuell gültige Teilnahme-Links zu erstellen.
Zeile 77: Zeile 78:
  
 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 [[:​de:​survey:​mailing#​seriennummern|Seriennummern-Funktion]] zum Einsatz kommen. 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 [[:​de:​survey:​mailing#​seriennummern|Seriennummern-Funktion]] zum Einsatz kommen.
 +
 +
 +===== Teilnahmestatus Seriennummer =====
 +
 +  * Wählen Sie unter **Einladungen verschicken** -> **API-Zugriff** bei //​Funktion//​ fest, dass Sie den Status einer Seriennummer abfragen möchten.
 +  * Mit dem Speichern-Symbol {{:​button.save.png?​nolink|Speichern}} erstellen Sie anschließend eine API-URL.
 +
 +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://​www.soscisurvey.de/​PROJEKT/?​act=exu83w7vaYqaeakXH7axpH2Y%%''​ lautet, könnte ein gültiger Aufruf zur Überprfung der Seriennummer "​CD246802"​ etwa wie folgt aussehen.
 +
 +    https://​www.soscisurvey.de/​PROJEKT/?​act=exu83w7vaYqaeakXH7axpH2Y&​serial=CD246802
 +
 +Als Rückgabewert wird ein JSON-String mit folgender Struktur geliefert:
 +
 +<code javascript>​
 +{
 +  result: ​   "​ok",​
 +  code:      "​CD246802",​
 +  started: ​  true,
 +  completed: false,
 +  notice: ​   "",​
 +  error: ​    null
 +}
 +</​code>​
 +
 +Die Attribute haben die folgende Bedeutung:
 +
 +  * ''​result''​ -- Rückgabewert der Anfrage, kann die Wert "​ok"​ oder "​error"​ annehmen
 +  * ''​code''​ -- Die abgefragte Seriennummer
 +  * ''​started''​ -- Wurde die Seriennummer verwendet, um einen Fragebogen zu starten (boolean)
 +  * ''​completed''​ -- Wurde der begonnene Fragebogen bis zur letzten Seite ausgefüllt (boolean)
 +  * ''​notice''​ -- Eine eventuell für die Seriennummer gespeicherter Notiz
 +  * ''​error''​ -- Fehlermeldung,​ falls ''​result''​ den Wert "​error"​ hat
 +    * "not found" -- Die gesuchte Seriennummer ist im Befragungsprojekt nicht bekannt
 +
 +Im Fehlerfall wird nur der Status-Code und eine Fehlermeldung zurückgegeben,​ falls vorhanden auch die angefragte Seriennummer:​
 +
 +<code javascript>​
 +{
 +  result: ​   "​error",​
 +  error: ​    "​not found",​
 +  code:      "​CD246802"​
 +}
 +</​code>​
de/survey/mailing-api.txt · Zuletzt geändert: 21.01.2019 22:43 von admin
 
Falls nicht anders bezeichnet, ist der Inhalt dieses Wikis unter der folgenden Lizenz veröffentlicht: CC Attribution-Share Alike 4.0 International
Driven by DokuWiki