SmartForms API

Die SmartForms API ermöglicht es, die Funktionalitäten von Evalanche-Formularen unabhängig von der standardmäßigen HTML-Darstellung zu nutzen. Gleichzeitig bleiben die Vorteile der engen Integration der Formularobjekte für Prozesse innerhalb von Evalanche erhalten.

Dadurch können Workflows weitgehend direkt über die Evalanche-GUI konfiguriert und gesteuert werden, ohne dass tiefgehende technische Anpassungen erforderlich sind. Dies erleichtert die effiziente Umsetzung und Verwaltung von Formularprozessen.

Eine Übersicht sowie ein Vergleich der Integrationsmöglichkeiten sind hier verfügbar.

Arbeitsweise der API

Die SmartForms API ist so konzipiert, dass das Verhalten eines Formularaufrufs sowie eines Formular-Submits vollständig abgebildet werden kann. Dadurch entspricht die Nutzung über die API weitgehend dem gewohnten Verhalten innerhalb der Standardumgebung.

Die meisten Einstellungen lassen sich weiterhin zentral über das jeweilige Formularobjekt in der Evalanche-GUI vornehmen. Dies ermöglicht eine konsistente und effiziente Verwaltung ohne zusätzlichen technischen Aufwand.

Konfigurationsaspekte, die die Verarbeitung und Darstellung der Daten auf Client-Seite betreffen, werden über die Schnittstelle bereitgestellt und gesteuert.

Zusammenspiel mit JavaScript

Bei der Entwicklung der SmartForms API wurde besonderer Wert auf eine einfache Integration mittels JavaScript in beliebige Webseiten gelegt. Aus diesem Grund wurde auf eine konventionelle Authentifizierung verzichtet.

Stattdessen kommen Security Tokens mit zeitlich begrenzter Gültigkeit sowie CORS-Header zur Absicherung der Kommunikation zum Einsatz.

Grundlagen

REST (Representational State Transfer) ist ein Architekturstil für Web-APIs, bei dem alle Inhalte als Ressourcen über eindeutige URLs adressiert werden. Der Zugriff und die Bearbeitung erfolgen über standardisierte HTTP-Methoden wie GET (Abruf), POST (Erstellung), PUT/PATCH (Aktualisierung) und DELETE (Löschen).

Jede Anfrage ist zustandslos, das heißt, sie enthält alle für die Verarbeitung erforderlichen Informationen. Zudem sind Client und Server klar voneinander getrennt. Die Datenübertragung erfolgt in der Regel in Form von JSON-Repräsentationen, was eine konsistente, skalierbare und gut verständliche API-Struktur unterstützt.

Das API-Schema ist unter folgendem Link verfügbar: https://scnem.com/api/form/v2/schema

Requests / Endpunkte

GET (Abruf der Formularkonfiguration)

Der GET-Request dient dem Abruf der Konfigurationsdaten des verwendeten Formulars. Mit der Antwort wird zusätzlich ein neuer, gültiger Security Token bereitgestellt.

Darüber hinaus besteht die Möglichkeit, über einen optionalen Parameter die Daten eines einzelnen Profils anzufordern. Dadurch kann das Formular bereits vorausgefüllt angezeigt werden.

GET https://[Versanddomain]/api/form/v2/[Formular- SID]?u=[UID des Profils, optional]

{
    "token":
    "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpcCI6IjkzLjE5Ny4xOTEuMjMxIiwiYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMC4xNTsgcnY6MTQ4LjApIEdlY2tvLzIwMTAwMTAxIEZpcmVmb3gvMTQ4LjAiLCJ0YXJnZXRfaG9zdCI6InNjbmVtMi5jb20iLCJleHAiOjE3NzQyNzE5MTh9.5SeI6vGVXmIcpeN9gKZeIUum0Oyc-e22ZAOS2NcGav8",
    "captcha": {
    "type": "RECAPTCHA",
    "public_key": "6LfU4tkUAAAAACHsryZA8oCvgjpXZTmFr2iVwZTW"
    },
    "form": {
    "action": "https:\/\/****.com\/art_resource.php?sid=***.***",
    "title": "Newsletter-Anmeldung",
    "shorttext": "",
    "language": "",
    "translation": {
    "preface_validation": "Bitte korrigieren Sie folgende Fehler",
    "duplicate_validation": "Sie sind bereits eingetragen",
    "missing_validation": "Markierte Pflichtfelder nicht ausgef\u00fcllt",
    "failed_validation": "Die Anmeldung ist fehlgeschlagen",
    "submit": "Abschicken"
    },
    "tracking": {
    "link": "",
    "campaign": ""
    },
    "limit": {
    "entry": {
    "active": false,
    "maximum_subscription_count": 0,
    "redirect_url": "",
    "limit_reached": false
    },
    "time": {
    "start": {
    "active": false,
    "date": "1970-01-01T00:00:00+00:00",
    "redirect_url": "",
    "limit_reached": false
    },
    "end": {
    "active": false,
    "date": "1970-01-01T00:00:00+00:00",
    "redirect_url": "",
    "limit_reached": false
    }
    }
    }
    },
    "fields": [
    {
    "label": "eMail",
    "required": true,
    "name": "form_EMAIL",
    "pool_attribute_id": 13431,
    "sort": 0,
    "translation": {
    "validation_error": "Keine g\u00fcltige eMail-Adresse"
    },
    "hidden": false,
    "readonly": true,
    "default_value": "",
    "widget_id": 10,
    "auto_display": false,
    "write_protection": false,
    "type": "",
    "options": []
    },
    {
    "label": "MF f\u00fcr Checkbox",
    "required": false,
    "name": "form_MFFUERCHECKBOX",
    "pool_attribute_id": 261960,
    "sort": 1,
    "translation": {
    "validation_error": ""
    },
    "hidden": false,
    "readonly": false,
    "default_value": [],
    "widget_id": 5,
    "auto_display": false,
    "write_protection": false,
    "type": "checkbox",
    "options": [
    {
    "key": 381458,
    "value": "eine Option"
    }
    ]
    }
    ],
    "profile": {
    "uid": "78fdf425ac9e139b0e619ba42516a649",
    "data": [
    {
    "name": "form_EMAIL",
    "pool_attribute_id": 13431,
    "value": "***@sc-networks.com"
    },
    {
    "name": "form_MFFUERCHECKBOX",
    "pool_attribute_id": 261960,
    "value": [
    381458
    ]
    }
    ]
    }
}
                    

Dabei ist zu beachten, dass bei einem personalisierten Aufruf die Profildaten in einem separaten Bereich der Response bereitgestellt werden. Die Zuordnung zu den einzelnen Formularfeldern muss clientseitig erfolgen.

Die in der Response enthaltenen Widget-IDs repräsentieren die in der Formularkonfiguration gewählte Darstellungsart der jeweiligen Formularfelder.

Hier finden Sie eine Liste.

POST (Datenübertragung zum Formular)

Der POST-Request dient der Übermittlung von Daten an das Evalanche-Formular. Dabei erfolgt eine Validierung der übermittelten Daten anhand der Formularkonfiguration sowie des Security Tokens.

Im Fehlerfall werden entsprechende Fehlercodes zurückgegeben. Im Erfolgsfall werden die gespeicherten Daten einschließlich einer gegebenenfalls neu generierten UID sowie die im Formular hinterlegte URL der Bestätigungsseite zurückgegeben, sofern eine Weiterleitung vorgesehen ist.

POST https://[Versanddomain]/api/form/v2/[Formular- SID]?u=[UID des Profils, optional]
Inhalt
{
  "profile_uid": "",
  "data": [
    {
      "field_name": "form_SALUTATION",
      "value": "2"
    },
    {
      "field_name": "form_FIRSTNAME",
      "value": "SCN Test"
    },
    {
      "field_name": "form_NAME",
      "value": "SCN Test"
    },
    {
      "field_name": "form_EMAIL",
      "value": "***@sc-networks.com"
    },
    {
      "field_name": "form_COMPANY",
      "value": ""
    },
    {
      "field_name": "form_TRACKING_DISABLED",
      "value": "0"
    },
    {
      "field_name": "form_GANZEZAHL",
      "value": "12"
    },
    {
      "field_name": "form_P1404375631",
      "value": [
        4775
      ]
    },
    {
      "field_name": "form_P1404375632",
      "value": "4779"
    },
    {
      "field_name": "form_EINZEILIGEEINGABE",
      "value": ""
    }
  ],
  "options": {
    "force_new_profile": false,
    "allow_empty_profile": false
  },
  "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpcCI6IjkzLjE5Ny4xOTEuMjMxIiwiYWdlbnQiOiJNb3ppbGxhLzUuMCAoTWFjaW50b3NoOyBJbnRlbCBNYWMgT1MgWCAxMC4xNTsgcnY6MTQ5LjApIEdlY2tvLzIwMTAwMTAxIEZpcmVmb3gvMTQ5LjAiLCJ0YXJnZXRfaG9zdCI6InNjbmVtMi5jb20iLCJleHAiOjE3NzYxNTk1MjZ9.tQsCH_1B0sBNCKPHZqabyMNI0R-jdce9rTrPNoW2pbM",
  "captcha_response": ""
}
                    

{
  "result": {
    "profile": {
      "uid": "***",
      "data": [
        {
          "name": "form_SALUTATION",
          "pool_attribute_id": 13428,
          "value": [
            2
          ]
        },
        {
          "name": "form_FIRSTNAME",
          "pool_attribute_id": 13429,
          "value": "SCN Test"
        },
        {
          "name": "form_NAME",
          "pool_attribute_id": 13430,
          "value": "SCN Test"
        },
        {
          "name": "form_EMAIL",
          "pool_attribute_id": 13431,
          "value": "***@sc-networks.com"
        },
        {
          "name": "form_COMPANY",
          "pool_attribute_id": 13432,
          "value": ""
        },
        {
          "name": "form_TRACKING_DISABLED",
          "pool_attribute_id": 50005,
          "value": "0"
        },
        {
          "name": "form_GANZEZAHL",
          "pool_attribute_id": 250964,
          "value": "333"
        },
        {
          "name": "form_P1404375631",
          "pool_attribute_id": 13456,
          "value": [
            4776
          ]
        },
        {
          "name": "form_MEHRZEILIGEEINGABEFUERSMARTFORMS",
          "pool_attribute_id": 260703,
          "value": "hier Link <a href="\">klick<\>"
        },
        {
          "name": "form_P1404375632",
          "pool_attribute_id": 13457,
          "value": [
            4779
          ]
        },
        {
          "name": "form_EINZEILIGEEINGABE",
          "pool_attribute_id": 260734,
          "value": "Test"
        }
      ]
    },
    "redirection_url": "https:\/\/scnem2.com\/art_resource.php?sid=***,u=***"
  }
}

Validierung

Die Schnittstelle validiert die übermittelten Daten anhand der Konfiguration des Evalanche-Formulars. Im Fehlerfall werden die entsprechenden Informationen in einem Fehlerblock innerhalb der Antwort zurückgegeben. Dieser enthält einen Code zur Beschreibung der Fehlerart sowie mehrere Listen, die jeweils die internen Namen der betroffenen Felder enthalten.

• validation_error_attributes: Array mit Feldern, bei denen Typ- oder Formatfehler vorliegen
• mandatory_error_attributes: Array mit nicht ausgefüllten Pflichtfeldern
• subscription_limit_redirection: Zeichenkette mit der URL im Falle einer Limitüberschreitung (z. B. nach einer maximalen Anzahl von Einträgen oder einem definierten Zeitintervall)

Beispiel

{
  "error": {
    "code": 102,
    "validation_error_attributes": [
      "form_EMAIL"
    ],
    "mandatory_error_attributes": [],
    "subscription_limit_redirection": null
  }
}

Sicherheitshinweise

CORS

Die SmartForms API stellt in den relevanten Responses einen CORS-Header bereit, der im Formularobjekt unter Konfiguration → Erlaubte Domains konfiguriert werden kann.

Dadurch wird die Nutzung der Client-Anwendungen im Browser domänenübergreifend ermöglicht, während gleichzeitig die Sicherheit vor unautorisiertem Zugriff und Missbrauch erhöht wird.

Token Einführung

Der Token enthält verschlüsselte Informationen zum jeweiligen GET-Request sowie eine definierte Time-to-Live (TTL).

Der im GET-Request erhaltene Token muss bei einem nachfolgenden POST-Submit übergeben werden, um die Validierung des Submits sicherzustellen. Innerhalb der gültigen TTL kann der Token für mehrere POST-Requests verwendet werden und verhält sich damit wie ein Session-Token.

Validierte Parameter

Im Rahmen der Token-Validierung werden folgende Kriterien geprüft:

• Die TTL darf nicht überschritten sein. Hierbei wird ein zufälliger Zeitraum von 100–300 Sekunden zum Zeitstempel des GET-Requests addiert.
• Die IP-Adresse des GET-Requests muss mit der des POST-Requests übereinstimmen.
• Der User-Agent des GET-Requests muss identisch mit dem des POST-Requests sein.
• Der im GET-Request verwendete Host (Domain) muss mit dem des POST-Requests übereinstimmen. 

Kann der Token nicht erfolgreich validiert werden, wird der Fehlercode 107 zurückgegeben.

Schutz gegen missbräuchliche Eintragungen

Durch den Einsatz von Tokens sowie durch die im Vergleich zu einfachen GET- oder POST-Formularen erweiterten Übertragungsmechanismen wird bereits ein grundlegender Schutz gegen einfache, unerwünschte Schnittstellenzugriffe gewährleistet.

Darüber hinaus bietet die Version 2 der SmartForms API erstmals eine serverseitige Unterstützung von Captcha-Verfahren.

Weitere Informationen finden Sie bei den Anbietern unter:

• Google ReCaptcha
• FriendlyCaptcha 

Rate Limit

Code- und ID-Tabellen

Unabhängig davon können weitere Fehler auftreten, die durch HTTP-Statuscodes im Bereich 4XX oder 5XX gekennzeichnet sind. Diese sind gesondert zu behandeln.

Tipps und Tricks

Versteckte Felder

Felder, die im Evalanche-Formular als versteckt konfiguriert wurden, können über die API nicht mit abweichenden Werten überschrieben werden. Diese Felder werden serverseitig ignoriert, sodass im Profil der im Formular hinterlegte Wert verwendet wird.

Wenn Felder clientseitig ausgeblendet werden sollen, sollte stattdessen eine sichtbare Darstellungsart gewählt und die entsprechende Logik auf Clientseite umgesetzt werden, beispielsweise durch eine geeignete Feldbenennung oder Kennzeichnung.

Checkbox (invertiert)

Bei der invertierten Checkbox verhält sich die Schnittstelle abweichend zu den Evalanche-Formularen. Der übermittelte Eingabewert wird durch die Schnittstelle nicht invertiert.

Kurztext

Evalanche-Formulare verfügen über ein Freitextfeld mit der Bezeichnung Kurztext (in der Schnittstelle: shorttext). Dieses Feld dient nicht ausschließlich der Darstellung von Text, sondern kann auch zur Speicherung strukturierter Daten, beispielsweise für Konfigurationszwecke verwendet werden. Diese Daten werden dem Client entsprechend über die Schnittstelle bereitgestellt.

Codebeispiele