API general: tipos de acción

preautorización

Para autenticar a un usuario, consulte el tipo de acción preauth primero. Con su solicitud, envíe el nombre de usuario y recibirá información sobre si el usuario necesita iniciar sesión mediante contraseña y / o 2Factor o si es necesario un redireccionamiento a servidores de terceros (SAML / OAuth).

Ejemplo de entrada:

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

Ejemplo de salida:

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

La respuesta contiene la siguiente información:

Nota: Cuando un sso_redirect La URL está presente, debe reenviar al usuario al punto final SSO para la autenticación. Una vez que el usuario regrese, puede continuar con los siguientes pasos de autenticación.

Nota: En los casos en que el correo electrónico o SMS se utilizan como autenticación de dos factores, el sistema enviará automáticamente el correo electrónico / SMS con la solicitud de autorización previa.

auth

Para autenticar al usuario, utilice el tipo de acción auth. Con su solicitud, envíe el nombre de usuario y la contraseña (y el código 2FA si es necesario) y recibirá un token de autenticación como respuesta. El token se puede utilizar para procesar solicitudes posteriores.

Ejemplo de entrada:

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

Ejemplo de salida:

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

Guarde el valor que se encuentra en kmd y enviarlo en todas las llamadas posteriores a la API como valor de entrada kmd.

Tenga en cuenta: En caso de autenticación de dos factores, la llamada a auth devolverá un código de error dependiendo del método de autenticación si 2fa no fue enviado. Si ese es el caso, deberá mostrar una página de Autenticación de dos factores al usuario que coincida con el código de error (por ejemplo, para ingresar el código de correo electrónico u OTP). Utilice el token (kmd) que recibió y usa la acción verifyauth para (re) enviar el código 2fa.

Verificación

La acción verifyauth se puede usar para verificar si un token (kmd) sigue siendo válido y / o enviar un código 2fa para la autenticación de dos factores.

Ejemplo de entrada:

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

Ejemplo de salida:

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

Guarde el valor que se encuentra en kmd y enviarlo en todas las llamadas posteriores a la API como valor de entrada kmd.

Iniciar sesión

El logout La acción finaliza una sesión existente (cierre de sesión).

Ejemplo de entrada:

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

derechos

Tipo de acción rights se puede utilizar para obtener una descripción general de los modelos y las acciones a las que el usuario tiene derecho de acceso.

Ejemplo de entrada:

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

Ejemplo de salida:

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

lista

El tipo de acción list se puede utilizar para solicitar una lista de entradas de un modelo específico de la base de datos. Este tipo de acción está diseñado para ofrecer una descripción general de los elementos a un usuario (en lugar de mostrar detalles específicos).

Ejemplo de entrada esperado:

{
  ... 
 "model":   "...",  
 "action":  "list",
 "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)
}

Ejemplo de salida de respuesta:

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

Los datos de salida constan de un data matriz y una matriz de cabeza correspondiente. La matriz de datos contiene las filas que se mostrarán al usuario. La matriz de encabezados contendrá la información específica del título (por ejemplo, clasificación, texto del título, etc.) para cada columna de la tabla.

Los datos de ejemplo anteriores resultarían en la siguiente tabla que se mostraría:

Valores convertidos

Para los campos de la lista de tipos (subtipos de campo 1, 2 y 12) puede usar el sufijo :convert in cols propiedad de la solicitud para obtener el valor legible del contenido en lugar del valor bruto (por ejemplo, el nombre de una columna en lugar del ID). Si se encuentra una columna con este sufijo, la salida contendrá la columna dos veces, una como valor sin procesar y otra como valor convertido.

Ejemplo de entrada esperado:

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

Ejemplo de salida de respuesta:

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

Filtros

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

Para buscar en todos los campos, el nombre del campo query puede ser usado.

Posibles comparison los valores son:

Ejemplo:

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

... encontrará filas donde age es igual o mayor que 27 y lastname contiene al hombre (por ejemplo, Hofmann o Superman o Mandy)

obtener

El tipo de acción get se puede utilizar para solicitar una o más entradas de un modelo específico de la base de datos cuando ya se conocen los ID de las entradas. El uso previsto de este tipo de acción es mostrar los datos en un formulario para su edición. Por lo tanto, la respuesta también proporcionará información detallada sobre cada campo.

Ejemplo de entrada esperado:

{
  ... 
 "model":   "...",  
 "action":  "get",
 "ids":     [...]  // Array of IDs
 }

Envíe una matriz vacía de ids para obtener solo la definición del campo. Esto puede ayudarlo a crear una nueva entrada basada en la definición del campo.

Ejemplo de salida de respuesta:

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

El ejemplo anterior podría resultar en un formulario con este aspecto:

Para crear

Para crear nuevas entradas, puede utilizar el tipo de acción create.

Ejemplo de entrada esperado:

{
  "action":     "create",
  "accessType": 1,
  "model":      "Subaccount",
  "ids":        [],
  "data":       {
    "intID":     "0",    
    "strLogin":  "new User",
    "strPass":   "ABCabc123!",
    "intStatus": "1"
  }
}

El resultado de una actualización exitosa corresponde al ejemplo dado para el get tipo de acción. Ejemplo de salida:

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

Ten en cuenta que create fallará si el modelo con el mismo ID ya existe. Si desea anular la configuración existente, puede enviar los dos campos insertIgnore (valor = 1) y / o onDuplicateUpdate (valor = 1). Enviando insertIgnore le dirá al sistema que no devuelva un error si falla la inserción. onDuplicateUpdate le dice al sistema que actualice todos los valores en caso de que exista un artículo con el mismo ID.

actualización

Para cambiar una o más entradas existentes, puede usar el tipo de acción update.

Ejemplo de entrada esperado:

{
  "action":     "update",
  "accessType": 1,
  "model":      "Subaccount",
  "ids":        [ 542 ],
  "data":       
  {
    "intID":     "542",
    "strLogin":  "aaa",
    "strPass":   "abcabc",
    "intStatus": "1"
  }  
}

El resultado de una actualización exitosa corresponde al ejemplo dado para el get tipo de acción. Ejemplo de salida:

{
  "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 caso de un error de actualización, el sistema responderá con un mensaje de error como este:

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

borrar

El tipo de acción delete se puede utilizar para eliminar una o más entradas de un modelo específico de la base de datos cuando ya se conocen los ID de las entradas.

Ejemplo de entrada esperado:

{
  ... 
 "model":   "...",  
 "action":  "delete",
 "ids":     [...]  // Array of IDs
 }

Ejemplo de salida de respuesta:

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