Login

Try consentmanager
Book a call

API general: Tipos de acción

preauth

Para autenticar a un usuario, consulta primero el tipo de acción preauth . Envía el nombre de usuario junto con tu solicitud y recibirás información sobre si el usuario debe iniciar sesión mediante contraseña y/o autenticación de dos factores, o si es necesario redirigirlo a servidores de terceros (SAML/OAuth).

Ejemplo de entrada:

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

Ejemplo de resultado:

{
  ...
  "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:

Campo Descripción
sso_type

Tipo de inicio de sesión único:

0: Sin 2FA

1: LDAP

2: SAML

3: OAuth
sso_redirect URL a la que redirigir al usuario (utilizada con SAML + OAuth)
twofactor_type

Tipo de autenticación de dos factores

0: Sin 2FA

1: OTP

2: Correo electrónico

3: SMS
twofactor_required Si se requiere o no un segundo factor (todos los tipos de dos factores, excepto el 0)

Nota: Cuando sso_redirect URL, debes redirigir al usuario al punto final de SSO para la autenticación. Una vez que el usuario regrese, puedes continuar con los siguientes pasos de autenticación.

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

auth

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

Ejemplo de entrada:

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

Ejemplo de resultado:

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

Guarda el valor que se encuentra en kmd y envíalo en todas las llamadas posteriores a la API como valor de entrada kmd.

Nota: 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 se ha enviado. Si ese es el caso, tendrás que mostrar al usuario una página de autenticación de dos factores que coincida con el código de error (por ejemplo, para introducir el código de correo electrónico o la OTP). Utiliza el token (kmd) que ha recibido y utilice la acción verifyauth para (re)enviar el código 2fa.

verifyauth

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

Ejemplo de entrada:

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

Ejemplo de resultado:

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

Guarda el valor que se encuentra en kmd y envíalo en todas las llamadas posteriores a la API como valor de entrada kmd.

cerrar sesión

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

Ejemplo de entrada:

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

derechos

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

Ejemplo de entrada:

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

Ejemplo de resultado:

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

lista

El tipo de acción list puede utilizarse para solicitar una lista de entradas de un modelo específico de la base de datos. Este tipo de acción está pensado para ofrecer al usuario una visión general de los elementos (en lugar de mostrar detalles específicos).

Ejemplo de entrada esperada:

{
  ... 
 "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 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 consisten en una data matriz y una matriz de encabezado correspondiente. La matriz de datos contiene las filas que se mostrarán al usuario. La matriz de encabezado contendrá la información específica del encabezado (p. ej., ordenación, texto del encabezado, etc.) para cada columna de la tabla.

Los datos del ejemplo anterior darían lugar a la siguiente tabla:

Valores convertidos

Para los campos de tipo lista (subtipos de campo 1, 2 y 12) puedes utilizar el sufijo :convert en cols propiedad de la solicitud para obtener el valor legible del contenido en lugar del valor sin procesar (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 esperada:

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

Ejemplo 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

El

filters

La propiedad del JSON de la solicitud se puede utilizar para buscar elementos específicos o reducir la lista de resultados. El

filters

La propiedad consiste en una matriz de elementos de filtro. Cada elemento es un objeto con la siguiente estructura:

{
  "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, se puede utilizar el nombre de campo query .

Los posibles comparison son:

Tipo de comparación Descripción
eql Igual. Busca filas en las que el contenido de fieldname sea exactamente igual que value. (Este tipo es el predeterminado si comparison no se utiliza en el objeto.)
lt Menor que. Busca filas en las que el contenido de fieldname es menor que value.
gt Mayor que. Busca filas en las que el contenido de fieldname es mayor que value.
lte Menor que/Igual a. Buscar filas en las que el contenido de fieldname es menor que value o igual a value.
gte Mayor que/Igual. Busca filas en las que el contenido de fieldname es mayor que value o igual a value.
like Contiene. Buscar filas en las que value está contenido en el contenido de fieldname (en parte o por completo).
in Está en la lista. Busca filas en las que el contenido de fieldname sea exactamente igual a uno de value. En este caso value debería ser una matriz.
is Es NULL. Busca filas en las que el contenido de fieldname sea NULL.
isnot No es NULL. Busca filas en las que el contenido de fieldname no sea NULL.

Ejemplo:

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

… encontrará filas en las que age sea igual o mayor que 27 y lastname contenga «man» (por ejemplo, Hofmann, 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 esperada:

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

Envía una matriz vacía de ids para obtener únicamente la definición de los campos. Esto puede ayudarte a crear una nueva entrada basada en la definición de los campos.

Ejemplo 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 dar lugar a un formulario con este aspecto:

crear

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

Ejemplo de entrada esperada:

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

El resultado de una actualización correcta se corresponde con el ejemplo dado para el get tipo de acción. Ejemplo de resultado:

{
  "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 ya existe un modelo con el mismo ID. Si quieres anular la configuración existente, puedes enviar los dos campos insertIgnore (value=1) y/o onDuplicateUpdate (valor=1). El envío de insertIgnore indicará al sistema que no devuelva un error si falla la inserción. onDuplicateUpdate indica al sistema que actualice todos los valores en caso de que exista un elemento con el mismo ID.

Actualizar

Para modificar una o varias entradas existentes, puedes utilizar el tipo de acción update.

Ejemplo de entrada esperada:

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

El resultado de una actualización correcta se corresponde con el ejemplo dado para el get tipo de acción. Ejemplo de resultado:

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

eliminar

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 esperada:

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

Ejemplo 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
  }
}

 

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!