Login

Try consentmanager
Book a call

API générale : types d'actions

preauth

Afin d'authentifier un utilisateur, veuillez d'abord interroger le type d'action preauth . Envoyez le nom d'utilisateur avec votre requête et vous recevrez des informations indiquant si l'utilisateur doit se connecter via un mot de passe et/ou une authentification à deux facteurs, ou si une redirection vers des serveurs tiers (SAML/OAuth) est nécessaire.

Exemple de texte source :

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

Exemple de résultat :

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

La réponse contient les informations suivantes :

Champ Description
sso_type

Type d'authentification unique :

0 : Pas d'authentification à deux facteurs

1 : LDAP

2 : SAML

3 : OAuth
sso_redirect URL vers laquelle rediriger l'utilisateur (utilisée avec SAML + OAuth)
twofactor_type

Type d'authentification à deux facteurs

0 : Pas d'authentification à deux facteurs

1 : OTP

2 : E-mail

3 : SMS
twofactor_required Nécessité ou non d'un deuxième facteur (tous les types d'authentification à deux facteurs, sauf 0)

Remarque : lorsqu'une sso_redirect URL est présente, vous devez rediriger l'utilisateur vers le point de terminaison SSO pour l'authentification. Une fois que l'utilisateur revient, vous pouvez passer aux étapes d'authentification suivantes.

Remarque : lorsque l'e-mail ou le SMS sont utilisés comme authentification à deux facteurs, le système enverra automatiquement l'e-mail/SMS contenant la demande de pré-authentification.

auth

Afin d'authentifier l'utilisateur, veuillez utiliser le type d'action auth. Envoyez avec votre requête le nom d'utilisateur et le mot de passe (ainsi que le code 2FA si nécessaire) et vous recevrez un jeton d'authentification en réponse. Ce jeton pourra ensuite être utilisé pour traiter les requêtes suivantes.

Exemple de texte source :

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

Exemple de résultat :

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

Enregistrez la valeur trouvée sous kmd et envoyez-la dans tous les appels suivants à l'API en tant que valeur d'entrée kmd.

Remarque : en cas d'authentification à deux facteurs, l'appel à auth renverra un code d'erreur en fonction de la méthode d'authentification si 2fa n'a pas été envoyé. Si tel est le cas, vous devrez afficher à l'utilisateur une page d'authentification à deux facteurs correspondant au code d'erreur (par exemple, pour saisir le code reçu par e-mail ou l'OTP). Veuillez utiliser le jeton (kmd) que vous avez reçu et utilisez l'action verifyauth afin de (re)soumettre le code 2fa.

verifyauth

L'action verifyauth peut être utilisée soit pour vérifier si un jeton (kmd) est toujours valide et/ou pour soumettre un code 2FA pour l'authentification à deux facteurs.

Exemple de texte source :

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

Exemple de résultat :

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

Enregistrez la valeur trouvée sous kmd et envoyez-la dans tous les appels suivants à l'API en tant que valeur d'entrée kmd.

déconnexion

L' logout action met fin à une session existante (déconnexion).

Exemple de texte source :

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

droits

Le type d'action rights peut être utilisé pour obtenir une vue d'ensemble des modèles et des actions auxquels l'utilisateur a le droit d'accéder.

Exemple de texte source :

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

Exemple de résultat :

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

liste

Le type d'action list peut être utilisé pour demander une liste d'entrées d'un modèle spécifique à partir de la base de données. Ce type d'action est destiné à offrir un aperçu des éléments à un utilisateur (plutôt que d'afficher des détails spécifiques).

Exemple de texte source attendu :

{
  ... 
 "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)
}

Exemple de réponse :

{
  "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
  }
}

Les données de sortie se composent d'un data tableau et d’un tableau d’en-tête correspondant. Le tableau de données contient les lignes à afficher à l’utilisateur. Le tableau d’en-tête contiendra les informations spécifiques de l’en-tête (par exemple, le tri, le texte de l’en-tête, etc.) pour chaque colonne du tableau.

Les données de l'exemple ci-dessus donneraient lieu à l'affichage du tableau suivant :

Valeurs converties

Pour les champs de type liste (sous-types de champ 1, 2 et 12), vous pouvez utiliser le suffixe :convert dans cols propriété de la requête afin d’obtenir la valeur lisible du contenu au lieu de la valeur brute (par exemple, le nom d’une colonne au lieu de l’ID). Si une colonne comportant ce suffixe est trouvée, le résultat contiendra la colonne deux fois, une fois en tant que valeur brute et une fois en tant que valeur convertie.

Exemple de texte source attendu :

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

Exemple de réponse :

{
 ...
  "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"
      }
    ],
   ...
  }
}

Filtres

Le

filters

La propriété dans la requête JSON peut être utilisée pour rechercher des éléments spécifiques ou réduire la liste de résultats. Le

filters

La propriété se compose d'un tableau d'éléments de filtrage. Chaque élément est un objet de la structure suivante :

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

Pour effectuer une recherche dans tous les champs, le nom de champ query peut être utilisé.

Les valeurs possibles comparison sont :

Type de comparaison Description
eql Égal. Rechercher les lignes où le contenu de fieldname est exactement le même que value. (Ce type est utilisé par défaut si comparison n'est pas utilisé dans l'objet.)
lt Inférieur à. Rechercher les lignes où le contenu de fieldname est inférieur à value.
gt Plus grand que. Rechercher les lignes où le contenu de fieldname est supérieur à value.
lte Inférieur à/Égal à. Rechercher les lignes où le contenu de fieldname est inférieur à value ou égal à value.
gte Supérieur ou égal à. Rechercher les lignes où le contenu de fieldname est supérieur à value ou égal à value.
like Contient. Rechercher les lignes où value est contenu dans le contenu de fieldname (en partie ou en totalité).
in Fait partie de la liste. Rechercher les lignes où le contenu de fieldname est exactement identique à l'un des éléments de value. Dans ce cas, value doit être un tableau.
is Est NULL. Rechercher les lignes où le contenu de fieldname est NULL.
isnot N'est pas NULL. Rechercher les lignes où le contenu de fieldname n'est pas NULL.

Exemple :

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

… trouvera des lignes où age est égal ou supérieur à 27 et lastname contient « man » (par exemple Hofmann, Superman ou Mandy)

Obtenir

Le type d'action get peut être utilisé pour demander une ou plusieurs entrées d'un modèle spécifique à la base de données lorsque les identifiants des entrées sont déjà connus. Ce type d'action est destiné à afficher les données dans un formulaire en vue de leur modification. La réponse fournira donc également des informations détaillées sur chaque champ.

Exemple de texte source attendu :

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

Veuillez envoyer un tableau vide ids afin d'obtenir uniquement la définition des champs. Cela peut vous aider à créer une nouvelle entrée en vous basant sur la définition des champs.

Exemple de réponse :

{
  "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
  }
}

L'exemple ci-dessus pourrait donner lieu à un formulaire ressemblant à ceci :

Créer

Pour créer de nouvelles entrées, vous pouvez utiliser le type d'action create.

Exemple de texte source attendu :

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

Le résultat d'une mise à jour réussie correspond à l'exemple donné pour le get type d'action. Exemple de résultat :

{
  "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
  }
}

Veuillez noter que create cela échouera si le modèle portant le même ID existe déjà. Si vous souhaitez remplacer les paramètres existants, vous pouvez envoyer les deux champs insertIgnore (value=1) et/ou onDuplicateUpdate (value=1). L'envoi de insertIgnore indiquera au système de ne pas renvoyer d'erreur si l'insertion échoue. onDuplicateUpdate indique au système de mettre à jour toutes les valeurs si un élément existant porte le même ID.

Mise à jour

Pour modifier une ou plusieurs entrées existantes, vous pouvez utiliser le type d'action update.

Exemple de texte source attendu :

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

Le résultat d'une mise à jour réussie correspond à l'exemple donné pour le get type d'action. Exemple de résultat :

{
  "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
  }
}

En cas d'erreur de mise à jour, le système affichera un message d'erreur comme celui-ci :

{
  "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"
  }
}

supprimer

Le type d'action delete peut être utilisé pour supprimer une ou plusieurs entrées d’un modèle spécifique de la base de données lorsque les ID des entrées sont déjà connus.

Exemple de texte source attendu :

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

Exemple de réponse :

{
  "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!