Login

Try consentmanager
Book a call

API generale: Tipi di azione

preauth

Per autenticare un utente, si prega di interrogare prima il tipo di azione preauth . Invia il nome utente insieme alla tua richiesta e riceverai informazioni sul fatto che l’utente debba effettuare il login tramite password e/o autenticazione a due fattori oppure se sia necessario un reindirizzamento a server di terze parti (SAML/OAuth).

Esempio di input:

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

Esempio di output:

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

La risposta contiene le seguenti informazioni:

Campo Descrizione
sso_type

Tipo di Single-Sign-On:

0: No 2FA

1: LDAP

2: SAML

3: OAuth
sso_redirect URL a cui reindirizzare l'utente (utilizzato con SAML + OAuth)
twofactor_type

Tipo di autenticazione a due fattori

0: Nessuna 2FA

1: OTP

2: E-mail

3: SMS
twofactor_required Se è richiesto o meno un secondo fattore (tutti i tipi di autenticazione a due fattori, eccetto 0)

Nota: quando è presente un sso_redirect URL, devi reindirizzare l'utente all'endpoint SSO per l'autenticazione. Una volta che l'utente ritorna, puoi procedere con i passaggi successivi dell'autenticazione.

Nota: nei casi in cui l'e-mail o l'SMS vengano utilizzati come autenticazione a due fattori, il sistema invierà automaticamente l'e-mail/SMS con la richiesta di pre-autenticazione.

auth

Per autenticare l'utente, usa il tipo di azione auth. Invia la richiesta indicando nome utente e password (e codice 2FA se necessario) e riceverai in risposta un token di autenticazione. Il token potrà poi essere utilizzato per elaborare le richieste successive.

Esempio di input:

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

Esempio di output:

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

Salva il valore che trovi sotto kmd e invialo in tutte le successive chiamate all'API come valore di input kmd.

Nota bene: in caso di autenticazione a due fattori, la chiamata a auth restituirà un codice di errore a seconda del metodo di autenticazione se 2fa non è stato inviato. In tal caso, dovrai mostrare all'utente una pagina di autenticazione a due fattori corrispondente al codice di errore (ad es. per l'inserimento del codice via e-mail o dell'OTP). Ti preghiamo di utilizzare il token (kmd) che hai ricevuto e usa l'azione verifyauth per (ri)inviare il codice 2fa.

verifyauth

L'azione verifyauth può essere utilizzata sia per verificare se un token (kmd) sia ancora valido e/o per inviare un codice 2fa per l'autenticazione a due fattori.

Esempio di input:

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

Esempio di output:

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

Salva il valore che trovi sotto kmd e invialo in tutte le successive chiamate all'API come valore di input kmd.

logout

L' logout azione termina una sessione esistente (logout).

Esempio di input:

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

diritti

Tipo di azione rights può essere utilizzato per ottenere una panoramica dei modelli e delle azioni a cui l'utente ha diritto di accedere.

Esempio di input:

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

Esempio di output:

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

elenco

Il tipo di azione list può essere utilizzato per richiedere un elenco di voci di un modello specifico dal database. Questo tipo di azione è pensato per essere utilizzato per offrire una panoramica degli elementi a un utente (piuttosto che mostrare dettagli specifici).

Esempio di input previsto:

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

Esempio di risposta:

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

I dati di output consistono in un data array e da un corrispondente array di intestazioni. L’array dei dati contiene le righe da mostrare all’utente. L’array delle intestazioni conterrà le informazioni specifiche relative alle intestazioni (ad es. ordinamento, testo dell’intestazione e così via) per ciascuna colonna della tabella.

I dati dell'esempio sopra riportato darebbero come risultato la visualizzazione della seguente tabella:

Valori convertiti

Per i campi di tipo elenco (sottotipi di campo 1, 2 e 12) puoi usare il suffisso :convert nella cols proprietà della richiesta per ottenere il valore leggibile del contenuto invece del valore grezzo (ad es. il nome di una colonna invece dell’ID). Se viene trovata una colonna con questo suffisso, l’output conterrà la colonna due volte, una volta come valore grezzo e una volta come valore convertito.

Esempio di input previsto:

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

Esempio di risposta:

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

Filtri

Il

filters

La proprietà nel JSON della richiesta può essere utilizzata per cercare elementi specifici o ridurre l'elenco dei risultati. Il

filters

La proprietà consiste in un array di elementi di filtro. Ogni elemento è un oggetto della seguente struttura:

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

Per effettuare la ricerca in tutti i campi, è possibile utilizzare il nome del campo query .

I possibili comparison sono:

Tipo di confronto Descrizione
eql Uguale. Trova le righe in cui il contenuto di fieldname è esattamente uguale a value. (Questo tipo è predefinito se comparison non viene utilizzato nell'oggetto.)
lt Minore di. Trova le righe in cui il contenuto di fieldname è minore di value.
gt Maggiore di. Trova le righe in cui il contenuto di fieldname è maggiore di value.
lte Minore di/Uguale a. Trova le righe in cui il contenuto di fieldname è minore di value o uguale a value.
gte Maggiore di/Uguale a. Trova le righe in cui il contenuto di fieldname è maggiore di value o uguale a value.
like Contiene. Trova le righe in cui value è contenuto nel contenuto di fieldname (in parte o completamente).
in È nell'elenco. Trova le righe in cui il contenuto di fieldname è esattamente uguale a uno di value. In questo caso value dovrebbe essere un array.
is È NULL. Trova le righe in cui il contenuto di fieldname è NULL.
isnot Non è NULL. Trova le righe in cui il contenuto di fieldname non è NULL.

Esempio:

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

… troverai righe in cui age è uguale o maggiore di 27 e lastname contiene "man" (ad es. Hofmann o Superman o Mandy)

ottenere

Il tipo di azione get può essere utilizzato per richiedere una o più voci di un modello specifico dal database quando gli ID delle voci sono già noti. L'uso previsto di questo tipo di azione è quello di visualizzare i dati in un modulo per la modifica. Pertanto la risposta fornirà anche informazioni dettagliate su ciascun campo.

Esempio di input previsto:

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

Invia un array vuoto di ids per ottenere solo la definizione dei campi. Questo può aiutarti a creare una nuova voce basata sulla definizione dei campi.

Esempio di risposta:

{
  "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'esempio sopra riportato potrebbe tradursi in un modulo simile a questo:

crea

Per creare nuove voci puoi utilizzare il tipo di azione create.

Esempio di input previsto:

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

Il risultato di un aggiornamento riuscito corrisponde all'esempio fornito per il get tipo di azione. Esempio di risultato:

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

Tieni presente che create l'operazione fallirà se esiste già un modello con lo stesso ID. Se desideri sovrascrivere le impostazioni esistenti, puoi inviare i due campi insertIgnore (value=1) e/o onDuplicateUpdate (value=1). L'invio di insertIgnore indicherà al sistema di non restituire un errore se l’inserimento fallisce. onDuplicateUpdate indica al sistema di aggiornare tutti i valori nel caso in cui esista già un elemento con lo stesso ID.

aggiornamento

Per modificare una o più voci esistenti puoi utilizzare il tipo di azione update.

Esempio di input previsto:

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

Il risultato di un aggiornamento riuscito corrisponde all'esempio fornito per il get tipo di azione. Esempio di risultato:

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

In caso di errore di aggiornamento, il sistema risponderà con un messaggio di errore simile a questo:

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

elimina

Il tipo di azione delete può essere utilizzato per eliminare una o più voci di un modello specifico dal database quando gli ID delle voci sono già noti.

Esempio di input previsto:

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

Esempio di risposta:

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