API documentation

The Vensoft API is a JSON interface available at https://api.vensoft.de/. The most recent version can be access at https://api.vensoft.de/stable/.
The API is organized around REST. The API attempts to use predictable, resource-oriented URLs and to use HTTP response codes to indicate errors. The API will occasionally deviate from REST principles to reduce chattiness so that latency is minimised.

Most of the API calls require a valid SessionKey which can be obtained via login method, described in the Authentification section. To use the method successfully you need to supply your own Vensoft username (e-mail address) and password. If you already have access credentials for the Vensoft portal, you can re-use them for the API. If you do not have access credentials or if you would like to have separate credentials for your API implementation, don't hesitate to contact us.


Return codes

If an API call success, the HTTP status code 200 is returned, otherwise the status code 500 (Internal server error) is returned.

In case of an error, the result will always include a JSON object with the following content:
Parameter Description
codeError code.
messageA human readable message explaining the error. The language used is always english.
The error code is either 14 for unknown errors or otherwise obtained from http://www.postgresql.org/docs/current/static/errcodes-appendix.html.


Example
{
  "code": 42501,
  "message": "The sessionKey could not be validated."
}


Codes Used
The following codes are used within the Vensoft API. Other codes may occur aswell.

Code Description
01007privilege_not_granted
0B000invalid_session_initiation
22004null_value_not_allowed (some parameter is empty but required)
22023invalid_parameter_value
28P01invalid_password
42501insufficient_privilege
42701duplicate_column
42809wrong_object_type
42883undefined_function
P0002no_data_found
XX000internal_error (unknown exception)

Authentification

The authentification methods include Login, Logout and Validate. For most of all other methods provided by the API a SessionKey is required which can be retrieved via Login method. In special cases the predefined SessionKey anonymous can be used.

For mobile devices, a DeviceToken can be supplied. If a DeviceToken is supplied, the SessionKey will be valid for a longer period and some methods will contain fewer information.



Login

HTTP Request
POST https://api.vensoft.de/stable/auth/login/


HTTP Parameters
Parameter Description
UsernameThe username to be validated. Vensoft uses the e-mail address as the username.
PasswordClear text password to be validated.
DeviceTokenOptional Parameter supplied in the Header.

Response
A simple object containing the SessionKey.

Example Call
curl "https://api.vensoft.de/stable/auth/login/" -X POST -d "Username=Username" -d "Password=password"


Example Call for mobile devices
curl "https://api.vensoft.de/stable/auth/login/" -X POST -H "DeviceToken: 00:ab:cd:ef:12:34:56" -d "Username=Username" -d "Password=password"


Example Result
{
  "SessionKey": "c0ffd3704d99c6731151f1c5b318878d1503d6d2b54e3069ae139193ac63d861"
}

Logout

HTTP Request
POST https://api.vensoft.de/stable/auth/logout/


HTTP Parameters
A valid SessionKey must be supplied.

Response
A simple object containing the result.

Example Call
curl "https://api.vensoft.de/stable/auth/logout/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "Success": true
}

Validate

HTTP Request
POST https://api.vensoft.de/stable/auth/validate/


HTTP Parameters
A valid SessionKey must be supplied. The anonymous SessionKey can be used for this call.

Response
A simple object containing the result as a success bool and in cas of success the UserId associated with this session.

Example Call
curl "https://api.vensoft.de/stable/auth/validate/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "Success": true,
  "UserId": 118586315118453611
}
TransferObject
Attributes
idunsigned int 64ID of the object
type_idunsigned int 64Object type ID
definitionjson objectKey/Value pairs of the attributes. Always includes "parent_id" and "owner".
permissionsarray of permissionArray of permission objects, containing the "name" of the permission as a string and the "permitted" attribute as a boolean.
attribute_permissionsarray of attribute permissionArray of attribute permission objects. Each attribute permission includes the "name" (string), "can_read" (boolean) and "can_update" (boolean).
Example
{
  "id": 125609740326667984,
  "type_id": 122981964696257802,
  "definition": {
    "imsi": "214074300078189",
    "iccid": "8934071100289374062",
    "owner": 112712829290677262,
    "msisdn": "345901000303208",
    "parent_id": 112728507255096337
  },
  "permissions": [
    { "name": "update", "permitted": true },
    { "name": "undelete", "permitted": true },
    { "name": "read", "permitted": true },
    { "name": "delete", "permitted": true },
    { "name": "set privilege", "permitted": true }
  ],
  "attribute_permissions": [
    { "name": "msisdn", "can_read": true, "can_update": true },
    { "name": "imsi", "can_read": true, "can_update": true },
    { "name": "iccid", "can_read": true, "can_update": true }
  ]
}
Filter
Attributes
orderobject (Can be null)
attributestringThe attribute to order by.
directionstringThe direction to order by. Can be either "ASC" or "DESC".
countobject (Can be null)
countintThe maximum number of items to return.
offsetintThe number of items to omit.
constraintsConditionList object (Can be null)
joinstringCan be "AND" or "OR".
conditionsArray of Condition
listsConditionListAdditional ConditionList objects can be encapsulated here.


Condition
Attributes
attributestringThe attribute to filter by.
typeintThe operator to use. The operator is encoded based on the following values:
  • 1: Equal
  • 2: Not equal
  • 3: Bigger than
  • 4: Lower than
  • 5: Is null
  • 6: Is not null
  • 7: In list (values should be comma separated)
  • 8: Between (the two values have to be separated by "|")
  • 9: Value is like (case insensitive regular expression match)
  • 10: Bigger than or equal
  • 11: Lower than or equal
valuestringThe value used to filter by.
Example
{
  "order": {
    "attribute": "msisdn",
    "direction": "ASC"
  },
  "count": {
    "count": 30,
    "offset": 0
  },
  "constraints": {
    "join": "AND",
    "conditions": [{
      "attribute": "msisdn",
      "type": 1,
      "value": "1234567"
    }, {
      "attribute": "ismi",
      "type": 9,
      "value": "234"
    }],
    "lists": []
  }
}

Translated to (Postgre-)SQL this would be the following expression:
SELECT ... WHERE (msisdn='1234567' AND 'imsi'~*'234') ORDER BY msisdn ASC NULLS LAST LIMIT 30 OFFSET 0;
ObjectDescription
Attributes
idunsigned int 64ID of the object type
namestringThe name used in most of the calls
recoverablebooleanDefines if an object is really dropped in the delete method, or only marked as deleted
managed_objectbooleanIf an object is unmanaged, it cannot hold privileges, the privileges are than defined by the direct parent
readable_attributesarray of stringArray of all attributes the specified user can read. This does not mean that any of the attributes is readable on every object, but at least on one.
writeable_attributesarray of stringArray of all attributes the specified user can update. This does not mean that any of the attributes is updateable on every object, but at least on one.
privilegesarray of stringArray of all privileges that are granted for that object type. This does not mean that every object of the specified type has all the privielges.
parent_object_typesarray of int 64Array of object type ids that can be a parent for the specified object type. Can be the object type itself.
Example
{
  "id": 112776158021420064,
  "name": "acl_lang",
  "recoverable": true,
  "managed_object": true,
  "readable_attributes": ["DecimalPoint", "FilesystemDate", "LongDate", "Name", "ShortCode", "ShortDate", "ShortTime", "ThousandSeparator"],
  "writeable_attributes": null,
  "privileges": ["create", "delete", "read", "set privilege", "undelete", "update"],
  "parent_object_types": [112687999665308673]
}
Report
Attributes
AggregationArray of objects (Can be null)
FunctionstringThe aggregation function to use. Can be either "SUM", "AVG" or "COUNT".
AttributestringThe attribute to aggregate.
GroupArray of objects (Can be null)
FunctionstringCan be null or an attribute type specific function, e.g. "DATE_TRUNC:DAY".
AttributestringThe attribute to group by.
OrientationstringCan be either "horizontal" or "vertical".


Example
{
  "Aggregation": [{
    "Function": "SUM",
    "Attribute": "Price"
  }, {
    "Function": "COUNT",
    "Attribute": "Price"
  }],
  "Group": [{
    "Function": null,
    "Attribute": "Choice",
    "Orientation": "vertical"
  }, {
    "Function": null,
    "Attribute": "SaleStatusId",
    "Orientation": "horizontal"
  }]
}
ReportResult
Attributes
AxisArray of objects (Can be null)
DimensionintThe dimension of the axis startint at 0.
AttributesArray of Attribute
DataArray of objects (Can be null)
CoordinatesArray of intCoordinates in all dimensions. For three dimensional reports the format is [0, 4, 2].
ValueanytypeThe value at the forementioned Coordinates.


Attribute
Attributes
KeystringThe attribute name.
ValueanytypeValue for this group, e.g. 1 for a product choice or "Coca Cola" for a product name
PrivilegesstringAlways an empty string.
Example
{
  "Axis": [{
    "Dimension": 0,
    "Attributes": [
    {
      "Key": "Choice",
      "Value": 1,
      "Privileges": ""
    },
    {
      "Key": "Choice",
      "Value": 2,
      "Privileges": ""
    },
    {
      "Key": "Choice",
      "Value": 3,
      "Privileges": ""
    },
    {
      "Key": "Choice",
      "Value": 4,
      "Privileges": ""
    }
    ]
  }, {
    "Dimension": 1,
    "Attributes": [
    {
      "Key": "SaleStatusId",
      "Value": 141024786821154052,
      "Privileges": ""
    }
    ]
  }, {
    "Dimension": 2,
    "Attributes": [
    {
      "Key": "Price",
      "Value": "SUM",
      "Privileges": ""
    },
    {
      "Key": "Price",
      "Value": "COUNT",
      "Privileges": ""
    }
    ]
  }],
  "Data": [
  {
    "Coordinates": [0, 0, 0],
    "Value": 2.5   },
  {
    "Coordinates": [0, 0, 1],
    "Value": 1   },
  {
    "Coordinates": [1, 0, 0],
    "Value": 2   },
  {
    "Coordinates": [1, 0, 1],
    "Value": 1   },
  {
    "Coordinates": [2, 0, 0],
    "Value": 2   },
  {
    "Coordinates": [2, 0, 1],
    "Value": 1   },
  {
    "Coordinates": [3, 0, 0],
    "Value": 2   },
  {
    "Coordinates": [3, 0, 1],
    "Value": 1   },
  {
    "Coordinates": [4, 0, 0],
    "Value": 2   },
  {
    "Coordinates": [4, 0, 1],
    "Value": 1   }
  ]
}
ACE
Attributes
trusteeunsigned int 64The trustee ID (user or user group) this ACE belongs to.
entityunsigned int 64The entity ID (any managed object) this ACE belongs to.
roleunsigned int 64The assigned role ID.
Example
{
  "trustee": 112718986981934095,
  "entity": 125133518824015550,
  "role": 112711190903260171
}

Get

The Get method retrieves a single object as a TransferObject. A valid SessionKey must be supplied.
HTTP Request
GET https://api.vensoft.de/stable/get/{ObjectTypeName}/{ObjectId}/


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
ObjectIdObject ID (unsigned int 64)

Response
A TransferObject is returned if the object is found and is accessible by the user.


Example Call
curl "https://api.vensoft.de/stable/get/machine/125752076205557483/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "id": 125752076205557483,
  "type_id": 122981964696257813,
  "definition": {
    "lat": 52.361158,
    "lon": 13.846135,
    "owner": 112712829290677262,
    "tour_id": 160656280187307311,
    "parent_id": 126441830899255055,
    "currency_id": 125073342834149021,
    "serial_number": "7",
    "machine_type_id": 125101559242557107,
    "tstamp_last_haccp": null,
    "tstamp_next_haccp": null,
    "tstamp_last_filling": null,
    "tstamp_next_filling": null,
    "tstamp_filling_critical": null
  },
  "permissions": [
    { "name": "read", "permitted": true },
    { "name": "delete", "permitted": true },
    { "name": "set privilege", "permitted": true },
    { "name": "update", "permitted": true },
    { "name": "undelete", "permitted": true }
  ],
  "attribute_permissions": [
    { "name": "tour_id", "can_read": true, "can_update": true },
    { "name": "lon", "can_read": true, "can_update": true },
    { "name": "machine_type_id", "can_read": true, "can_update": true },
    { "name": "currency_id", "can_read": true, "can_update": true },
    { "name": "serial_number", "can_read": true, "can_update": true },
    { "name": "tstamp_next_filling", "can_read": true, "can_update": true },
    { "name": "tstamp_next_haccp", "can_read": true, "can_update": true },
    { "name": "tstamp_last_haccp", "can_read": true, "can_update": true },
    { "name": "tstamp_filling_critical", "can_read": true, "can_update": true },
    { "name": "lat", "can_read": true, "can_update": true },
    { "name": "tstamp_last_filling", "can_read": true, "can_update": true }
  ]
}

Create

The create method creates a single object encoded as a TransferObject. A valid SessionKey must be supplied.
HTTP Request
POST https://api.vensoft.de/stable/create/{ObjectTypeName}/

HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
HTTP bodyJSON definition of the object to create.
The body of the HTTP POST call has to include a JSON definition of the object. If the attribute "parent_id" is omitted, a default parent is automatically chosen based on privileges, otherwise the API tries to create the object within the given parent.

Response
A TransferObject is returned if the object was successfully created and is accessible by the user.


Example Call
curl "https://api.vensoft.de/stable/create/sim/" -X POST -H "SessionKey: 12345678901234567890" -d '{"imsi": "214074300078189", "iccid": "8934071100289374062", "msisdn": "345901000303208", "parent_id": 112728507255096337}'


Example Result
{
  "id": 278162214848824644,
  "type_id": 122981964696257802,
  "definition": {
    "imsi": "214074300078189",
    "iccid": "8934071100289374062",
    "owner": 112712829290677262,
    "msisdn": "345901000303208",
    "parent_id": 112728507255096337
  },
  "permissions": [
    { "name": "read", "permitted": true },
    { "name": "delete", "permitted": true },
    { "name": "set privilege", "permitted": true },
    { "name": "update", "permitted": true },
    { "name": "undelete", "permitted": true }
  ],
  "attribute_permissions": [
    { "name": "msisdn", "can_read": true, "can_update": true },
    { "name": "imsi", "can_read": true, "can_update": true },
    { "name": "iccid", "can_read": true, "can_update": true }
  ]
}

Delete/Undelete

The Delete method deleted a single object or marks it as deleted (which is the default behaviour) so it can be recovered. The Undelete method on the other hand recovers a single object that was marked as deleted. A valid SessionKey must be supplied.


HTTP Request
GET https://api.vensoft.de/stable/delete/{ObjectTypeName}/{ObjectId}/
GET https://api.vensoft.de/stable/undelete/{ObjectTypeName}/{ObjectId}/


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
ObjectIdObject ID (unsigned int 64)

Response
A JSON object containing the key result which is either true or false.


Example Call
curl "https://api.vensoft.de/stable/delete/machine/125752076205557483/" -X POST -H "SessionKey: 12345678901234567890"
curl "https://api.vensoft.de/stable/undelete/machine/125752076205557483/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "result": true
}

List

The list method retrieves multiple objects in a data structure containing TransferObjects. A valid SessionKey must be supplied.
HTTP Request
GET https://api.vensoft.de/stable/list/{ObjectTypeName}/

If a filter, a specific order or a limit shall be supplied, they have to be encoded in a JSON Filter object and this has to be transmitted via HTTP POST like in the following example:
HTTP Request
POST https://api.vensoft.de/stable/list/{ObjectTypeName}/ -d 'filter={"count": {"count": 30,"offset": 0}}&return_privileges=true&return_attribute_privileges=false'


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
return_privileges Optional
Determines if privileges for each listed object should be returned.
Default value if omitted is true.
return_attribute_privileges Optional
Determines if privileges for each attribute of each listed object should be returned.
Default value if omitted is true.

Response
A data structure containing an array ofTransferObject is returned.


Example Call
curl "https://api.vensoft.de/stable/list/sim/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "filtered_record_count": 4,
  "limited_record_count": 4,
  "total_record_count": 4,
  "transfer_objects": [
  {
    "id": 125609740326667984,
    "type_id": 122981964696257802,
    "definition": {
      "imsi": "214074300078189",
      "iccid": "8934071100289374062",
      "owner": 112712829290677262,
      "msisdn": "345901000303208",
      "parent_id": 112728507255096337
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": [
      { "name": "msisdn", "can_read": true, "can_update": true },
      { "name": "imsi", "can_read": true, "can_update": true },
      { "name": "iccid", "can_read": true, "can_update": true }
    ]
  }, {
    "id": 262079543555130638,
    "type_id": 122981964696257802,
    "definition": {
      "imsi": "214074300078189",
      "iccid": "8934071100289374062",
      "owner": 112712829290677262,
      "msisdn": "345901000303208",
      "parent_id": 112728507255096337
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": [
      { "name": "msisdn", "can_read": true, "can_update": true },
      { "name": "imsi", "can_read": true, "can_update": true },
      { "name": "iccid", "can_read": true, "can_update": true }
    ]
  }, {
    "id": 262082079255168271,
    "type_id": 122981964696257802,
    "definition": {
      "imsi": "214074300078189",
      "iccid": "8934071100289374062",
      "owner": 112712829290677262,
      "msisdn": "345901000303208",
      "parent_id": 112728507255096337
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": [
      { "name": "msisdn", "can_read": true, "can_update": true },
      { "name": "imsi", "can_read": true, "can_update": true },
      { "name": "iccid", "can_read": true, "can_update": true }
      ]
  }, {
    "id": 262082196217529616,
    "type_id": 122981964696257802,
    "definition": {
      "imsi": "214074300078189",
      "iccid": "8934071100289374062",
      "owner": 112712829290677262,
      "msisdn": "345901000303208",
      "parent_id": 112728507255096337
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": [
      { "name": "msisdn", "can_read": true, "can_update": true },
      { "name": "imsi", "can_read": true, "can_update": true },
      { "name": "iccid", "can_read": true, "can_update": true }
    ]
  }]
}

DeleteMany

If many objects should be deleted and the ObjectIds of all of them are known, the DeleteMany method deletes multiple objects. A valid SessionKey must be supplied.
HTTP Request
POST https://api.vensoft.de/stable/deletemany/{ObjectTypeName}/ -d 'ids=[12345679012345, 543210987654321]'


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".

Response
A JSON array with the ObjectId as a key and a boolean result of the delete operation for this specific object.


Example Call
curl "https://api.vensoft.de/stable/deletemany/sim/" -X POST -H "SessionKey: 12345678901234567890" -d 'ids=[140999485865067647, 140999485865067648]'


Example Result
{
  "140999485865067647": true,
  "140999485865067648": true
}

GetContainer

This method can be used to obtain the Ids of all containers that offer a special privilege. Most often it is used to find all containers in which a specific object can be created. A valid SessionKey must be supplied.

HTTP Request
GET https://api.vensoft.de/stable/getcontainer/{ObjectTypeName}/{Privilege}/


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
PrivilegeName of the privilege, e.g. "create", "delete" or "set privilege".

Response
A data structure containing an array of unsigned int 64 is returned.


Example Call
curl "https://api.vensoft.de/stable/getcontainer/machine/create/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
[
  "112728507255096337",
  "125133518824015550",
  "125638697029732054",
  "168311186373215547",
  "168311578272204095"
]

GetMany

If many objects should be returned and the ObjectIds of all of them are known, the GetMany method retrieves multiple objects in a data structure containing TransferObjects. A valid SessionKey must be supplied.
HTTP Request
POST https://api.vensoft.de/stable/getmany/{ObjectTypeName}/ -d 'ids=[12345679012345, 543210987654321]'


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
return_privileges Optional
Determines if privileges for each listed object should be returned.
Default value if omitted is true.
return_attribute_privileges Optional
Determines if privileges for each attribute of each listed object should be returned.
Default value if omitted is true.

Response
A data structure containing an array ofTransferObject is returned.


Example Call
curl "https://api.vensoft.de/stable/getmany/sim/" -X POST -H "SessionKey: 12345678901234567890" -d 'ids=[125609740326667984, 262079543555130638]&return_privileges=true&return_attribute_privileges=true'


Example Result
{
  "filtered_record_count": null,
  "limited_record_count": null,
  "total_record_count": null,
  "transfer_objects": [
  {
    "id": 125609740326667984,
    "type_id": 122981964696257802,
    "definition": {
      "imsi": "214074300078189",
      "iccid": "8934071100289374062",
      "owner": 112712829290677262,
      "msisdn": "345901000303208",
      "parent_id": 112728507255096337
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": [
      { "name": "msisdn", "can_read": true, "can_update": true },
      { "name": "imsi", "can_read": true, "can_update": true },
      { "name": "iccid", "can_read": true, "can_update": true }
    ]
  }, {
    "id": 262079543555130638,
    "type_id": 122981964696257802,
    "definition": {
      "imsi": "214074300078189",
      "iccid": "8934071100289374062",
      "owner": 112712829290677262,
      "msisdn": "345901000303208",
      "parent_id": 112728507255096337
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": [
      { "name": "msisdn", "can_read": true, "can_update": true },
      { "name": "imsi", "can_read": true, "can_update": true },
      { "name": "iccid", "can_read": true, "can_update": true }
    ]
  }]
}

GetStructure

Objects like UserGroup or Container are organized in a tree structure by referencing each other in the "ParentId" field. To show such a tree structure, it is often sufficient to display the first two or three levels with full data and to load all the other data later on (if the user wishes so).
The GetStructure call can be used to obtain such a structure for a single ObjectType. A data structure containing TransferObjects is returned. A valid SessionKey must be supplied.

HTTP Request
GET https://api.vensoft.de/stable/getstructure/{ObjectTypeName}/


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".

Response
A data structure containing an array ofTransferObject is returned. Each object definition only consists of the attributes "id" and "parent_id".


Example Call
curl "https://api.vensoft.de/stable/getstructure/user_group/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "filtered_record_count": 4,
  "limited_record_count": 4,
  "total_record_count": 4,
  "transfer_objects": [
  {
    "id": 112718986981934095,
    "type_id": 112688519616398340,
    "definition": {
      "id": 112718986981934095,
      "parent_id": null
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": null
  }, {
    "id": 112719400649360400,
    "type_id": 112688519616398340,
    "definition": {
      "id": 112719400649360400,
      "parent_id": 112718986981934095
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": null
  }, {
    "id": 168320932811638127,
    "type_id": 112688519616398340,
    "definition": {
      "id": 168320932811638127,
      "parent_id": 112718986981934095
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": null
  }, {
    "id": 168354171068614124,
    "type_id": 112688519616398340,
    "definition": {
      "id": 168354171068614124,
      "parent_id": 183609477361042989
    },
    "permissions": [
      { "name": "update", "permitted": true },
      { "name": "undelete", "permitted": true },
      { "name": "read", "permitted": true },
      { "name": "delete", "permitted": true },
      { "name": "set privilege", "permitted": true }
    ],
    "attribute_permissions": null
  }]
}

UpdateMany

If many objects should be updated at once and the ObjectIds of all of them are known, the UpdateMany method manipulates multiple objects. This method only takes one object definition, thus making this method only useful for mass updates of connected fields or similar use cases. A valid SessionKey must be supplied.
HTTP Request
POST https://api.vensoft.de/stable/updatemany/{ObjectTypeName}/ -d 'ids=[{ObjectIds}]&definition={ObjectDefinition}'


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
ObjectIdsObject IDs (unsigned int 64).
ObjectDefinitionJSON definition of the attributes to update.

Response
A JSON array with the ObjectId as a key and a boolean result of the delete operation for this specific object.


Example Call
curl "https://api.vensoft.de/stable/updatemany/machine/" -X POST -H "SessionKey: 12345678901234567890" -d 'ids=[140999485865067653, 140999485865067654, 140999485865067700]&definition={"machine_type_id":"151356846445135"}'


Example Result
{
  "140999485865067653": true,
  "140999485865067654": true,
  "140999485865067700": true
}

Move

The Move method moves a single object to a new parent container object. The user needs to have the "update" privilege for the object to be moved and the "create" privilege at the new container element for objects of the given type. A valid SessionKey must be supplied.
HTTP Request
GET https://api.vensoft.de/stable/move/{ObjectTypeName}/{ObjectId}/{ParentId}/


HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
ObjectIdObject ID (unsigned int 64)
ParentIdID of the new parent container (unsigned int 64)

Response
A JSON object containing the key result which is either true or false.


Example Call
curl "https://api.vensoft.de/stable/move/machine/125752076205557483/125133518824015550/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "result": true
}

Update

The Update method sets all given attributes of a single object that has to encoded as the "Definition" part of a TransferObject. A valid SessionKey must be supplied.
HTTP Request
POST https://api.vensoft.de/stable/update/{ObjectTypeName}/{ObjectId}/

HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
ObjectIdObject ID (unsigned int 64)
HTTP bodyJSON definition of the object to create.
The body of the HTTP POST call has to include a JSON definition of the object. If the attribute "parent_id" is set, it will be discarded.If you want to change that, please refer to the "Move" Method instead.
You do not need to supply all attributes of the object. If you only want to change a single attribute value, you can supply just this part of the definition.
Response
A TransferObject is returned if the object was successfully updated and is accessible by the user.



Example Call
curl "https://api.vensoft.de/stable/update/sim/262079543555130638/" -X POST -H "SessionKey: 12345678901234567890" -d '{"imsi": "214074300078189", "iccid": "8934071100289374062"}'


Example Result
{
  "id": 262079543555130638,
  "type_id": 122981964696257802,
  "definition": {
    "imsi": "214074300078189",
    "iccid": "8934071100289374062",
    "owner": 112712829290677262,
    "msisdn": "345901000303208",
    "parent_id": 112728507255096337
  },
  "permissions": [
    { "name": "read", "permitted": true },
    { "name": "delete", "permitted": true },
    { "name": "set privilege", "permitted": true },
    { "name": "update", "permitted": true },
    { "name": "undelete", "permitted": true }
  ],
  "attribute_permissions": [
    { "name": "msisdn", "can_read": true, "can_update": true },
    { "name": "imsi", "can_read": true, "can_update": true },
    { "name": "iccid", "can_read": true, "can_update": true }
  ]
}

Describe

The Describe method returns all object types a user can access, including the attributes as an array of ObjectDescription. A valid SessionKey must be supplied.
HTTP Request
GET https://api.vensoft.de/stable/describe/

Response
A list of object descriptions is returned.


Example Call
curl "https://api.vensoft.de/stable/describe/" -X GET -H "SessionKey: 12345678901234567890"


Example Result
[
  {
    "id": 112776158021420064,
    "name": "acl_lang",
    "recoverable": true,
    "managed_object": true,
    "readable_attributes": ["DecimalPoint", "FilesystemDate", "LongDate", "Name", "ShortCode", "ShortDate", "ShortTime", "ThousandSeparator"],
    "writeable_attributes": null,
    "privileges": ["create", "delete", "read", "set privilege", "undelete", "update"],
    "parent_object_types": [112687999665308673]
  },
  {
    "id": 122981964696257813,
    "name": "vensoft_machine",
    "recoverable": true,
    "managed_object": true,
    "readable_attributes": ["CurrencyId", "Lat", "Lon"],
    "writeable_attributes": null,
    "privileges": ["create", "delete", "read", "set privilege", "undelete", "update"],
    "parent_object_types": [126435495931545352]
  }
]

Upload

The upload method is can only be used by the Ventool software and accepts bulk data in a format that is unique per data model. The exact bulk data format is both proprietary and confidential. A valid SessionKey and a DeviceToken must be supplied.
HTTP Request
POST https://api.vensoft.de/stable/upload/{ObjectTypeName}/

HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "user" or "machine".
HTTP bodyJSON definition of the bulk data.
The body of the HTTP POST call has to include a JSON definition of the object.

Response
A JSON object containing the key result which is either true or false.


Example Call
curl "https://api.vensoft.de/stable/upload/machine_product/" -X POST -H "DeviceToken: 00:ab:cd:ef:12:34:56" -H "SessionKey: 12345678901234567890" -d '{"id": 1, "name": "A green door", "price": 12.50, "tags": ["home", "green"]}'


Example Result
{
  "result": true
}

Introduction

The privilege system is role based. A role defines which privileges a user has for an object an also which attribute privileges a user has. Privileges are usually the following:
Privilege ID Explanation
read112691372632310789This privilege is needed for list, get and report operations
update112691389619241990This privilege is needed for update and move operations
create112691403183621127This privilege is needed for create operations
delete112691418098566152This privilege is needed for delete operations
undelete112691431151240201This privilege is needed for undelete operations
set privilege112691443776095242This privilege is needed for ACE set/delete and ACL set/delete operations

Some object types may have less privileges (for example a sale object can only have a "read" privilege) or more (the "tour" object has a "plan" privilege that allows certain roles to plan a tour).
Attribute privileges on the other hand are only "read" and "update".


Defining roles
  • ListRoleAttributes
  • ListRolePrivileges
  • SetRoleAttributes
  • SetRolePrivileges
  • DeleteRoleAttributes
  • DeleteRolePrivileges
Users and user groups
  • Inheritance
ACE
  • ListObjectAce
  • SetObjectAce
  • DeleteObjectAce

ACE

An ACE assigns a role to a trustee (user or user group) for a specific entity (or object). This role is inherited to all descendant objects.
ACEs can be listet ("get" method), set ("set" method) and deleted ("delete" method). No special privileges are required to list ACEs, since they only consist of IDs, but to set and delete them, the special "set privilege" privilege on the entity is required. A valid SessionKey is required nevertheless.

Get

HTTP Request
POST https://api.vensoft.de/stable/ace/get/


HTTP Parameters
Parameter Description
entity Optional
If an entity ID is supplied, only ACEs for this specific entity are listed.
trustee Optional
If a user ID is supplied, only ACEs for this user including all user groups the user is a member of, are listed.
If a user group ID is supplied, only ACEs for this user group and its predecessors are listed.

Response
A list of ACE objects.

Example Call
curl "https://api.vensoft.de/stable/ace/get/" -X POST -H "SessionKey: 1234567890" -d "entity=183694398704321835"


Example Result
[{
  "trustee": 112718986981934095,
  "entity": 125133518824015550,
  "role": 112711190903260171
}, {
  "trustee": 183694398704321835,
  "entity": 183609326257047075,
  "role": 112711742840112140
}]

Logout

HTTP Request
POST https://api.vensoft.de/stable/auth/logout/


HTTP Parameters
A valid SessionKey must be supplied.

Response
A simple object containing the result.

Example Call
curl "https://api.vensoft.de/stable/auth/logout/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "Success": true
}

Validate

HTTP Request
POST https://api.vensoft.de/stable/auth/validate/


HTTP Parameters
A valid SessionKey must be supplied. The anonymous SessionKey can be used for this call.

Response
A simple object containing the result as a success bool and in cas of success the UserId associated with this session.

Example Call
curl "https://api.vensoft.de/stable/auth/validate/" -X POST -H "SessionKey: 12345678901234567890"


Example Result
{
  "Success": true,
  "UserId": 118586315118453611
}

Report

This method is used to obtain aggregated and grouped data. The result and functionality can be compared with the Microsoft® Excel® pivot function. A valid SessionKey is required.
HTTP Request
POST https://api.vensoft.de/stable/report/{ObjectTypeName}/

HTTP Parameters
Parameter Description
ObjectTypeNameName of the object type, e.g. "sale" or "event".
HTTP bodyJSON definition of the report data.
The body of the HTTP POST call has to include a JSON definition of the Report and can include a Filter object.

Response
A JSON object containing the ReportResult.


Example Call
curl "https://api.vensoft.de/stable/report/sale/" -X POST -H "SessionKey: 12345678901234567890" -d 'report={"Aggregation":[{"Function":"SUM","Attribute":"Price"},{"Function":"COUNT","Attribute":"Price"}],"Group":[{"Function":null,"Attribute":"Choice","Orientation":"vertical"},{"Function":null,"Attribute":"SaleStatusId","Orientation":"horizontal"}]}&filter={"order":null,"count":null,"constraints":{"join":"AND","conditions":[{"attribute":"tstamp","type":8,"value":"2016-11-20T00:00:00+01:00|2016-11-22T23:59:59+01:00"},{"attribute":"parent_id","type":1,"value":421338385039230354},{"attribute":"sale_status_id","type":7,"value":"141024786821154052,141024786821154056"}],"lists":[]}}'


Example Result
{
  "Axis": [{
    "Dimension": 0,
    "Attributes": [{
      "Key": "Choice",
      "Value": 11,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 13,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 14,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 17,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 27,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 37,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 38,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 45,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 48,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 54,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 56,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 58,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 61,
      "Privileges": ""
    }, {
      "Key": "Choice",
      "Value": 63,
      "Privileges": ""
    }]
  }, {
    "Dimension": 1,
    "Attributes": [{
      "Key": "SaleStatusId",
      "Value": 141024786821154052,
      "Privileges": ""
    }]
  }, {
    "Dimension": 2,
    "Attributes": [{
      "Key": "Price",
      "Value": "SUM",
      "Privileges": ""
    }, {
      "Key": "Price",
      "Value": "COUNT",
      "Privileges": ""
    }]
  }],
  "Data": [{
    "Coordinates": [0, 0, 0],
    "Value": 2.5   }, {
    "Coordinates": [0, 0, 1],
    "Value": 1   }, {
    "Coordinates": [1, 0, 0],
    "Value": 2   }, {
    "Coordinates": [1, 0, 1],
    "Value": 1   }, {
    "Coordinates": [2, 0, 0],
    "Value": 2   }, {
    "Coordinates": [2, 0, 1],
    "Value": 1   }, {
    "Coordinates": [3, 0, 0],
    "Value": 2   }, {
    "Coordinates": [3, 0, 1],
    "Value": 1   }, {
    "Coordinates": [4, 0, 0],
    "Value": 2   }, {
    "Coordinates": [4, 0, 1],
    "Value": 1   }, {
    "Coordinates": [5, 0, 0],
    "Value": 3   }, {
    "Coordinates": [5, 0, 1],
    "Value": 2   }, {
    "Coordinates": [6, 0, 0],
    "Value": 2   }, {
    "Coordinates": [6, 0, 1],
    "Value": 2   }, {
    "Coordinates": [7, 0, 0],
    "Value": 4.5   }, {
    "Coordinates": [7, 0, 1],
    "Value": 3   }, {
    "Coordinates": [8, 0, 0],
    "Value": 1.5   }, {
    "Coordinates": [8, 0, 1],
    "Value": 1   }, {
    "Coordinates": [9, 0, 0],
    "Value": 3   }, {
    "Coordinates": [9, 0, 1],
    "Value": 3   }, {
    "Coordinates": [10, 0, 0],
    "Value": 3   }, {
    "Coordinates": [10, 0, 1],
    "Value": 2   }, {
    "Coordinates": [11, 0, 0],
    "Value": 1.8   }, {
    "Coordinates": [11, 0, 1],
    "Value": 1   }, {
    "Coordinates": [12, 0, 0],
    "Value": 1.5   }, {
    "Coordinates": [12, 0, 1],
    "Value": 1   }, {
    "Coordinates": [13, 0, 0],
    "Value": 1   }, {
    "Coordinates": [13, 0, 1],
    "Value": 1   }]
}

SOAP API calls with endpoint "http://soap.vensoft.de/Auth.wsdl" to render this page:
IsLoginValid (13,671 msecs):
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope" xmlns:ns1="http://soap.vensoft.de/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:enc="http://www.w3.org/2003/05/soap-encoding"><env:Body><ns1:IsLoginValid env:encodingStyle="http://www.w3.org/2003/05/soap-encoding"><SecurityToken xsi:type="xsd:string">1</SecurityToken></ns1:IsLoginValid></env:Body></env:Envelope>



loading...