Login

Try consentmanager
Book a call

Allgemeine API: Aktionstypen

preauth

Um einen Benutzer zu authentifizieren, fragen Sie bitte zunächst den Aktionstyp ab preauth ab. Senden Sie mit Ihrer Anfrage den Benutzernamen, und Sie erhalten die Information, ob sich der Benutzer per Passwort und/oder 2-Faktor-Authentifizierung anmelden muss oder ob eine Weiterleitung an Server von Drittanbietern (SAML/OAuth) erforderlich ist.

Beispiel für den Eingabetext:

{
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username  
  "api_key":    ""         //API-Key
}

Beispiel für die Übersetzung:

{
  ...
  "data":
  {
    "sso_type":          0/1/2/3,
    "sso_redirect":      "https://...",
    "twofactor_type":     0/1/2/3,
    "twofactor_required": true|false
  }
}

Die Antwort enthält folgende Informationen:

Feld Beschreibung
sso_type

Art des Single-Sign-On:

0: Keine 2FA

1: LDAP

2: SAML

3: OAuth
sso_redirect URL, zu der der Benutzer weitergeleitet werden soll (wird bei SAML + OAuth verwendet)
twofactor_type

Art der Zwei-Faktor-Authentifizierung

0: Keine 2FA

1: OTP

2: E-Mail

3: SMS
twofactor_required Ob ein zweiter Faktor erforderlich ist (alle twofactor_types außer 0)

Hinweis: Wenn eine sso_redirect URL vorhanden ist, müssen Sie den Nutzer zur Authentifizierung an den SSO-Endpunkt weiterleiten. Sobald der Nutzer zurückkehrt, können Sie mit den nächsten Authentifizierungsschritten fortfahren.

Hinweis: In Fällen, in denen E-Mail oder SMS als Zwei-Faktor-Authentifizierung verwendet werden, sendet das System automatisch die E-Mail/SMS mit der Vorab-Authentifizierungsanfrage.

auth

Um den Benutzer zu authentifizieren, verwenden Sie bitte den Aktionstyp auth. Senden Sie mit Ihrer Anfrage den Benutzernamen und das Passwort (sowie gegebenenfalls den 2FA-Code) und Sie erhalten als Antwort ein Authentifizierungstoken. Das Token kann dann zur Bearbeitung nachfolgender Anfragen verwendet werden.

Beispiel für den Eingabetext:

{
  "accessType": 0|1|2|...,
  "kname":      "...",     //Username
  "kpass":      "...",     //Password
  "2fa":        "...",     //optional
  "longlife":   0|1 ,      //optional
  "api_key":    ""         //optional
}

Beispiel für die Übersetzung:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Speichere den unter kmd und sende ihn bei allen nachfolgenden Aufrufen der API als Eingabewert kmd.

Bitte beachten Sie: Bei der Zwei-Faktor-Authentifizierung führt der Aufruf von auth gibt je nach Authentifizierungsmethode einen Fehlercode zurück, falls 2fa nicht gesendet wurde. In diesem Fall müssen Sie dem Benutzer eine Seite zur Zwei-Faktor-Authentifizierung anzeigen, die dem Fehlercode entspricht (z. B. zur Eingabe des E-Mail-Codes oder OTP). Bitte verwenden Sie das Token (kmd), das Sie erhalten haben, und verwenden Sie die Aktion verifyauth , um den 2FA-Code (erneut) zu übermitteln.

verifyauth

Die Aktion verifyauth kann verwendet werden, um entweder zu überprüfen, ob ein Token (kmd) noch gültig ist und/oder um einen 2FA-Code für die Zwei-Faktor-Authentifizierung zu übermitteln.

Beispiel für den Eingabetext:

{
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
  "2fa":        "...",     //2fa code    
}

Beispiel für die Übersetzung:

{
  ...
  "data":
  {
    "kmd":"token"
  }
}

Speichern Sie den unter kmd und sende ihn bei allen nachfolgenden Aufrufen der API als Eingabewert kmd.

Abmelden

Die logout Aktion beendet eine bestehende Sitzung (Abmeldung).

Beispiel für den Eingabetext:

{
  "accessType": 0|1|2|...,
  "token":      "...",     //Token from auth  
}

Rechte

Aktionsart rights kann verwendet werden, um einen Überblick über Modelle und Aktionen zu erhalten, auf die der Benutzer Zugriffsrechte hat.

Beispiel für den Eingabetext:

{
  "accessType": 0|1|2|...,
  "token":      "..."
}

Beispiel für die Übersetzung:

{
  ...
  "data":
  [
    {
      "model":   "User",
      "actions": ["get","list","update"]
    },
    {
      "model":   "Subaccount",
      "actions": ["get","list","update","create","delete","deleteinfo"]
    }
  ]
}

Liste

Der Aktionstyp list kann verwendet werden, um eine Liste von Einträgen eines bestimmten Modells aus der Datenbank abzufragen. Dieser Aktionstyp ist dafür gedacht, einem Benutzer eine Übersicht über Elemente zu bieten (anstatt spezifische Details anzuzeigen).

Beispiel für den erwarteten Eingabe-Text:

{
  ... 
 "filters": [...],      // Filters to apply, see description (optional)
 "limit":   100,        // Limit of output rows (optional)
 "offset":  0,          // Start index of first row (optional)
 "order":   "...",      // Column to sort (optional)
 "sort":    "asc|desc", // Sorting direction of output (optional) 
 "cols":    [...]       // If set, will output the named fields, otherwise a default set of fields will be shown
 //optional: "assoc": true // If set, returns and associative array instead of a data list
 //optional: "dataonly": true // If set, returns the data list only (no header information)
}

Beispiel für eine Antwort:

{
  "status":     "Success",
  "statuscode": 0,
  "msg":        "Erfolgreich",
  "model":      "Subaccount",
  "action":     "list",
  "data":       
  {
    "data":    
    [
      {
        "id":  "542",
        "row": 
        [
          "542",
          "aaa",
          "Aktiv"
        ]
      },
      {
        "id":  "543",
        "row": 
        [
          "543",
          "bbb",
          "Aktiv"
        ]
      }
    ],
    "head":    
    [
      {        
        "headline":     "ID",
        "colsort":      false,
        "colorder":     "intID",
        "colname":      "intID"
      },
      {
        "headlineType": "string",
        "headline":     "Nutzername",
        "colsort":      false,
        "colorder":     "strLogin",
        "colname":      "strLogin"
      },
      {
        "headlineType": "string",
        "headline":     "Status",
        "colsort":      false,
        "colorder":     "intStatus",
        "colname":      "intStatus"
      }
    ],
    "caption": "User",
    "count":   2,
    "total":   2
  }
}

Die Ausgabedaten bestehen aus einem data Array und einem entsprechenden Kopf-Array. Das Daten-Array enthält die Zeilen, die dem Benutzer angezeigt werden sollen. Das Kopf-Array enthält die spezifischen Kopfzeileninformationen (z. B. Sortierung, Kopfzeilentext usw.) für jede Spalte der Tabelle.

Die oben genannten Beispieldaten würden dazu führen, dass die folgende Tabelle angezeigt wird:

Umgerechnete Werte

Für Felder vom Typ „Liste“ (Felduntertypen 1, 2 und 12) kannst du das Suffix :convert in cols Eigenschaft der Anfrage verwenden, um den lesbaren Wert des Inhalts anstelle des Rohwerts zu erhalten (z. B. den Namen einer Spalte anstelle der ID). Wird eine Spalte mit diesem Suffix gefunden, enthält die Ausgabe die Spalte zweimal, einmal als Rohwert und einmal als konvertierten Wert.

Beispiel für den erwarteten Eingabe-Text:

{
  ... 
 "model":   "Design",  
 "action":  "list",
 "cols":    ['strName', 'intPosition:convert']  
}

Beispiel für eine Antwort:

{
 ...
  "data":       
  {
    "data":    
    [
      {
        "id":  "542",
        "row": 
        [
          "myDesign",
          "3",
          "Center middle"
        ]
      },
      ...
    ],
    "head":    
    [
      {        
        "headline":     "name",
        "colsort":      false,
        "colorder":     "strName",
        "colname":      "strName"
      },
      {        
        "headline":     "Position",
        "colsort":      false,
        "colorder":     "intPosition",
        "colname":      "intPosition"
      },
      {        
        "headline":     "Position",
        "colsort":      false,
        "colorder":     "intPosition",
        "colname":      "intPosition:convert"
      }
    ],
   ...
  }
}

Filter

Die

filters

Die Eigenschaft im Anfrage-JSON kann verwendet werden, um nach bestimmten Elementen zu suchen oder die Ausgabeliste einzugrenzen. Die

filters

Die Eigenschaft besteht aus einem Array von Filterelementen. Jedes Element ist ein Objekt mit folgender Struktur:

{
  "fieldname":  "...", // Field the filter should apply to
  "comparison": "...", // (optional) Comparison type, see description
  "value"    :  "..."  // Value to compare the field to
}

Um in allen Feldern zu suchen, kann der Feldname query verwendet werden.

Mögliche comparison Werte sind:

Vergleichstyp Beschreibung
eql Gleich. Finde Zeilen, in denen der Inhalt fieldname genau dem von value. (Dieser Typ ist Standard, wenn comparison im Objekt nicht verwendet wird.)
lt Kleiner als. Suche nach Zeilen, in denen der Inhalt von fieldname kleiner ist als value.
gt Größer als. Finde Zeilen, in denen der Inhalt von fieldname größer als value.
lte Kleiner als/Gleich. Finde Zeilen, in denen der Inhalt von fieldname kleiner als value oder gleich value.
gte Größer als/Gleich. Finde Zeilen, in denen der Inhalt von fieldname größer als value oder gleich value.
like Enthält. Finde Zeilen, in denen value im Inhalt von fieldname (teilweise oder vollständig) enthalten ist.
in Ist in der Liste enthalten. Finde Zeilen, in denen der Inhalt von fieldname genau mit einem der folgenden übereinstimmt value. In diesem Fall value sollte ein Array sein.
is Ist NULL. Suche nach Zeilen, in denen der Inhalt von fieldname ist NULL.
isnot Ist nicht NULL. Finde Zeilen, in denen der Inhalt von fieldname nicht NULL.

Beispiel:

{
  ...
  "filters":
  [
    {
      "fieldname": "age",
      "comparison": "gte",
      "value" : 27
    },
    {
      "fieldname": "lastname",
      "comparison": "like",
      "value" : "man"
    }
  ]
}

… findet Zeilen, in denen age gleich oder größer als 27 ist und lastname „man“ enthält (z. B. Hofmann oder Superman oder Mandy)

erhalten

Der Aktionstyp get kann verwendet werden, um einen oder mehrere Einträge eines bestimmten Modells aus der Datenbank abzufragen, wenn die IDs der Einträge bereits bekannt sind. Der Verwendungszweck dieses Aktionstyps besteht darin, die Daten in einem Formular zur Bearbeitung anzuzeigen. Daher enthält die Antwort auch detaillierte Informationen zu jedem Feld.

Beispiel für den erwarteten Eingabe-Text:

{
  ... 
 "ids":     [...]  // Array of IDs
 }

Bitte senden Sie ein leeres Array ids , um nur die Felddefinition zu erhalten. Dies kann Ihnen helfen, einen neuen Eintrag auf Basis der Felddefinition zu erstellen.

Beispiel für eine Antwort:

{
  "status":     "Success",
  "statuscode": 0,
  "msg":        "Erfolgreich",
  "model":      "Subaccount",
  "action":     "get",
  "data":       
  {
    "fields":     
    [
      {
        "fieldname":    "intID",
        "displayname":  "ID",
        "type":         2,
        "subtype":      8,
        "required":     true,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "542",
        "displayvalue": "",
        "listkeys":     [],
        "listvalues":   []
      },
      {
        "fieldname":    "strLogin",
        "displayname":  "Nutzername",
        "type":         1,
        "subtype":      0,
        "required":     true,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "aaa",
        "displayvalue": "aaa",
        "listkeys":     [],
        "listvalues":   []
      },
      {
        "fieldname":    "strPass",
        "displayname":  "Passwort",
        "type":         1,
        "subtype":      5,
        "required":     true,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "%%unchanged%%",
        "displayvalue": "********",
        "listkeys":     [],
        "listvalues":   []
      },
      {
        "fieldname":    "intStatus",
        "displayname":  "Status",
        "type":         2,
        "subtype":      1,
        "required":     false,
        "defaultvalue": null,
        "disabled":     false,
        "infotext":     false,
        "value":        "1",
        "displayvalue": "Aktiv",
        "listkeys":     [ 0, 1 ],
        "listvalues":   [ "Inaktiv", "Aktiv" ]
      }
    ],
    "caption":    "User: aaa",
    "groups":     [],
    "ids":        [ 542 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

Das obige Beispiel könnte zu einem Formular führen, das wie folgt aussieht:

Erstellen

Um einen neuen Eintrag zu erstellen, können Sie den Aktionstyp verwenden create.

Beispiel für den erwarteten Eingabe-Text:

{
  "ids":        [],
  "data":       {
    "intID":     "0",    
    "strLogin":  "new User",
    "strPass":   "ABCabc123!",
    "intStatus": "1"
  }
}

Das Ergebnis einer erfolgreichen Aktualisierung entspricht dem für den get Aktionsart. Beispiel für das Ergebnis:

{
  "status":         "Success",
  "statuscode":     0,
  "msg":            "Erfolgreich",
  "model":          "Subaccount",
  "action":         "get",
  "previousAction": "create",
  "data":           
  {
    "fields":     [...],
    "caption":    "User: new User",
    "groups":     [],
    "subgroups":  [],
    "ids":        [ 544 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

Bitte beachten Sie, dass create fehlschlägt, wenn das Modell mit derselben ID bereits existiert. Wenn du bestehende Einstellungen überschreiben möchtest, kannst du die beiden Felder insertIgnore (value=1) und/oder onDuplicateUpdate (value=1). Das Senden von insertIgnore wird das System anweisen, keinen Fehler zurückzugeben, falls der Einfügevorgang fehlschlägt. onDuplicateUpdate weist das System an, alle Werte zu aktualisieren, falls bereits ein Element mit derselben ID vorhanden ist.

Aktualisieren

Um einen oder mehrere bestehende Einträge zu ändern, können Sie den Aktionstyp update.

Beispiel für den erwarteten Eingabe-Text:

{
  "ids":        [ 542 ],
  "data":       
  {
    "intID":     "542",
    "strLogin":  "aaa",
    "strPass":   "abcabc",
    "intStatus": "1"
  }  
}

Das Ergebnis einer erfolgreichen Aktualisierung entspricht dem für den get Aktionsart. Beispiel für das Ergebnis:

{
  "status":         "Success",
  "statuscode":     0,
  "msg":            "Erfolgreich",
  "model":          "Subaccount",
  "action":         "get",
  "previousAction": "update",
  "data":           
  {
    "fields":     [...],
    "caption":    "User: aaa",
    "groups":     [],
    "subgroups":  [],
    "ids":        [ 542 ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

Im Falle eines Aktualisierungsfehlers gibt das System eine Fehlermeldung wie diese aus:

{
  "status": "Error",
  "statuscode": 113,
  "msg": "Update error, see error message. Field specific messages see response.data",
  "model": "Subaccount",
  "action": "update",
  "data": 
  {
    "strLogin": "Wert muss mindestens 6 Zeichen lang sein",
    "strPass":  "Wert muss Sonderzeichen beinhalten"
  }
}

löschen

Der Aktionstyp delete kann verwendet werden, um einen oder mehrere Einträge eines bestimmten Modells aus der Datenbank zu löschen, wenn die IDs der Einträge bereits bekannt sind.

Beispiel für den erwarteten Eingabe-Text:

{
  ... 
 "ids":     [...]  // Array of IDs
 }

Beispiel für eine Antwort:

{
  "status":         "Success",
  "statuscode":     0,
  "msg":            "Erfolgreich",
  "model":          "Subaccount",
  "action":         "create",
  "previousAction": "delete",
  "data":           
  {
    "fields":     [...],
    "caption":    "User: new User",
    "groups":     [],
    "subgroups":  [],
    "ids":        [  ],
    "canDelete":  true,
    "canSave":    true,
    "canSaveNew": true
  }
}

 

We do our best to keep this purely informative documentation up to date. However, if you notice that any of these guides need a little touch-up, let us know!