Introduction

Version 1.11

Server StoreHouse Pro Web API 2 enables the exchange of information with the StoreHouse Pro server using JSON files over the HTTP protocol.

The server StoreHouse Pro interacts with external systems exclusively by invoking procedures, each identified by a unique name. A procedure accepts datasets (tables) as parameters and fills them with the requested information in response. SH Pro datasets can be single-row or multi-row.

Available operations:

- Request server settings and database information: /api/sh5info
- Request permissions to execute a procedure: /api/sh5able
- Change own password: /api/sh5pass
- License information: /api/sh5lic
- Request list of procedure datasets: /api/sh5struct
- Execute procedure: /api/sh5exec
- Create attribute field: /api/sh5CreateAttr
- Request values of an enumerable attribute: /api/sh5enum
- Work with users: /api/sh5user
- Work with roles: /api/sh5role

POST requests with a JSON file containing request parameters must be sent to the specified paths. JSON files must be in UTF-8 encoding. Example request:

{ "UserName": "Admin", "Password": "12345", "procName": "XDivisions" }

UserName (string)- StoreHouse Pro username
Password (string)- StoreHouse Pro user password
procName (string)- name of the StoreHouse Pro procedure

UserName and Password are mandatory in all requests. The procName parameter is present in requests to /api/sh5struct and /api/sh5exec.

As a result of the request, a response JSON file will be sent. Example response:

{
 "errorCode": 1, 
 "errMessage": "Procedure XDivisions not found.", 
 "Version": "1.1", 
 "UserName": "Admin", "actionName": "XDivisions", "actionType": "Structure", 
 "errorInfo": { "moduleId": 1, "moduleName": "SDBCLI.DLL", "errorId": 194 }
}

errorCode (number)- error flag (0/1).
errMessage (string)- error text
Version (string)- version of SH5WAPI2 server

These three values are present in any response from the server.

UserName (string) - username passed in the request

If the request is successful, errorCode will be 0. In case of an error, errorCode will be 1, and the errorInfo object with additional error information will be present:

moduleId (number) - identifier of the module from which the error originated [0..5]
moduleName (string) - name of the module from which the error originated
errorId (number) - error code, unique for each module

Possible values of moduleId:

0 - BRISH.DLL, errorId is always 0
1 - SDBCLI.DLL, most common errorId values:
- 150 - Incorrect username or password
- 194 - Specified procedure does not exist
- 2102 - No connection to SH Pro server via local protocol
- 2205 - No connection to SH Pro server via TCP/IP
2 - DOMM.DLL
3 - MSDSET.DLL
4 - SHSRV64.DLL, error codes: https://docs.rkeeper.ru/pages/viewpage.action?pageId=19612474
5 - SH5WAPI2, errorId is always 1

GZIP

Starting from version 1.8.3, if the request contains the header

Accept-Encoding: gzip

and the response size exceeds 32kb, the response is returned packed in gzip with the header

Content-Encoding: gzip

Moreover, starting from version 1.11, responses exceeding 10 MB are required to be packed in gzip.

Request Server Settings and Database Information

Requests are sent to the path /api/sh5info

To find out which specific StoreHouse Pro server is being worked with, send a request to this address without any JSON. In this case, not only the POST method is allowed, but also GET. This makes it possible to execute the request even from a browser, which is convenient for a quick check of the WebAPI server's availability.
Example response JSON:

     { 
       "errorCode": 0, "errMessage": "OK", "Version": "0.5", "LinkType": 0, 
       "Server": "SDBSERV", "LinkDisp": "(local) SDBSERV"
     }

Or this response:

{
  "errorCode": 0, "errMessage": "OK", "Version": "0.5", "LinkType": 1, 
  "Host": "127.0.0.1", "Port": 7771, "LinkDisp": "(tcp/ip) 127.0.0.1:7771"
}

LinkType (number) - 0-local connection; 1-connection via TCP/IP.
Server (string) - present only for local connection - name of the SH Pro server
Host (string) - present only for TCP/IP - computer where the SH Pro server is running
Port (number) - present only for TCP/IP and if the port is non-standard
LinkDisp (string) - string with a textual description of connection parameters

If a POST request with embedded JSON specifying login and password is sent to the same path, the WebAPI server will connect to the StoreHouse Pro server and add database information to the response.

Request:

{ "UserName": "Admin", "Password": "12345" }

Response:

{
 "errorCode": 0, "errMessage": "OK", "Version": "0.5", "UserName": "Admin", 
 "LinkType": 0, "Server": "SRV1", "LinkDisp": "(local) SRV1", 
 "DB": 
 {
  "Ident": "3BDCC5D0", "Size": "300MB", "Version": "5.27"
 }
}

Ident (string) - unique database identifier
Size (string) - current database file size
Version (string) - database version

Request Permissions to Execute Procedures

Request is sent to the path /api/sh5able
Example request:

{
  "UserName": "Admin", "Password": "12345",
  "procList": ["Divisions", "Goods", "XYZ", "Departs", "BGoodsCategories"]
}

procList (array) - list of StoreHouse Pro procedures

Example response:

	{ 
	 "errorCode": 0, "errMessage": "OK", "Version": "1.1", "UserName": "Admin",
	 "procList": ["Divisions", "Goods", "XYZ", "Departs", "BGoodsCategories"],
	 "allow": [true, true, false, true, true]
	}

allow (array) - indicates whether the user has permission to execute the corresponding procedure

Change Password

Request is sent to the path /api/sh5pass
Example request:

{ "UserName": "Admin", "Password": "12345", "newValue": "ABCxyz123" }

newValue (string) - new password

Example response:

	{ 
	 "errorCode": 0, "errMessage": "OK", "Version": "1.2", "UserName": "Admin"
	}

License Information

Request is sent to the path /api/sh5lic
Example request:

{"UserName": "Admin","Password": "12345"}

Example response:

	{ 
	 "errorCode": 0, "errMessage": "OK", "Version": "1.4", "UserName": "Admin",
	 "license":
	 [
		{ "type": 56, "count": 1, "expDate": "2019-02-13",
        "objectId": 199990044, "key": "E800921A" 
		},
		{ "type": 58, "count": 3, "expDate": "2019-01-27", 
		"objectId": 199990044, "key": "E800921A" 
		},
		{ "type": 260, "count": 1, "expDate": "2019-03-22", 
		"objectId": 199990044, "key": "E800921A" 
		}
	 ]	
	}

license (array) - list of licenses available in the StoreHouse Pro database

Each license contains the following information:

type (number) - SoftCode of the license
count (number) - number of licenses of this type
expDate (string) - license expiration date
objectId (number) - object identifier
key (string) - virtual key identifier

Request List of Procedure Datasets

Request is sent to the path /api/sh5struct

The request JSON contains only three parameters: UserName, Password, procName. Example request:

{ "UserName": "Admin", "Password": "12345", "procName": "Divisions" }

The response contains elements:

UserName (string) - passed username
actionName (string) - name of the StoreHouse Pro procedure
actionType (string) - "Structure" - requested operation
shTable (array) - list of "table structure" objects

array of "table structure" elements.

The "table structure" object contains the following elements:

head (String) - table identifier
SingleRow (Bool) - single-row dataset (true) or multi-row (false)
fields (array) - list of "table field" objects

The "table field" object contains the following elements:

path (String) - original field name
type (String) - field type
size (String) - field size
alt (String) - optional, alternative field name

Example of a successful response:

{ 
 "errorCode": 0, "errMessage": "OK", "Version": "1.1", "UserName": "Admin",
 "actionName": "Divisions", "actionType": "Structure", 
 "shTable": 
 [
  {
   "head": "103", "SingleRow": false, 
   "fields": 
   [
    {     "path": "1", "type": "tUint32", "size": 4, "alt": "Rid"    }, 
    {     "path": "4", "type": "tGuid", "size": 16, "alt": "Guid"    }, 
    {     "path": "3", "type": "tStrZ", "size": 255, "alt": "Name"    }, 
    {     "path": "7\\$Qush", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\$PDocNum", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\$IDocNum", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\$GDocNum", "type": "tStrP", "size": 0    }, 
    {     "path": "7\\Chef", "type": "tStrP", "size": 0    }
   ]
  }, 
  {
   "head": "103#1", "SingleRow": true,
    "fields": 
   [
    {     "path": "239", "type": "tUint32", "size": 4, "alt": "MaxCount"    }, 
    {     "path": "240", "type": "tUint32", "size": 4    }
   ]
  }
 ]
}

Procedure Execution

Request is sent to the path /api/sh5exec. Data is passed to the procedure via the "Input" parameter. Alternatively, for compatibility with the old version, via the "dsParams" parameter. The second method is deprecated and may be removed in the future.

The "Input" parameter (array) contains a list of "data table" objects.

The "dsParams" parameter (object) contains "data field" objects, in this case only alternative field names are allowed.

The response contains an array of "data table" elements.

The "tShortDate" and "tLongDate" types must be passed in the format "yyyy-mm-dd". If the response contains such data types, they will be in exactly this format.

The "tGuid" must be passed in the format «{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}».

The tBinary and tBtData types are passed in HEX format. For example, if it is necessary to place a two-byte integer (WORD) with the value 2687 into such a field, it should be represented as “7F0A”. If the string “William Shakespeare” is used with a length byte specified before it, the value should be “1357696c6c69616d205368616b65737065617265”.

The "data table" object contains the following elements:

head (String) - table identifier
original - array of original field names (string)
fields - array of alternative field names (string)
values - array containing arrays of field values.
status - optional, array of record statuses (string)

Example request with the "Input" parameter:

{
 "UserName": "Admin", "Password": "", "procName": "GDoc0", 
 "Input": 
 [
  { "head": "111", "original": [ "1" ], "values": [ [ 3 ] ] }
 ]
}

Some procedures for modifying/deleting a record in a table require passing its status. In this case, the "status" array must be added to the "data table" object, listing the required statuses for each record. Possible options: "Insert", "Modify", "Delete". By default, all records receive the status "Insert".

Example request with record statuses:

{
 "UserName": "Admin", "Password": "", "procName": "ModCountries", 
 "Input": 
 [
  {"head": "231", 
   "original": [ "1", "2", "3" ], 
   "values": 
   [
    [ 1, null, 8 ], 
    [ "643", "UTO", "NET" ], 
    [ "Russia", "Utopia", "Netland" ]
   ], 
   "status": [ "Modify", "Insert", "Delete" ]
  }
 ]
}

The "data field" object is an array containing the field values for all records in the table. Example request with the "dsParams" parameter:

{ 
 "UserName": "Admin","Password": "",
 "procName":"CntrSpecs",
 "dsParams":
 { "contractorRid":["2"] }
}

Create an Attribute Field

Added in version 1.8

Request is sent to the path /api/sh5CreateAttr

Example request:

{ "UserName": "Admin", "Password": "12345", "bob": "aTable_Attrs",
  "ident": "UserComment", "caption": "User comment", 
  "type": "tStrP" }

bob (string) - Container identifier (SdbMan: Maintenance - Statistics - Binary object fields)
ident (string) - Identifier of the field being created
caption (string) - Caption of the field being created
type (string) - Field type. Only the following are supported: ("tInt32", "tInt64", "tDouble", "tLongDate", "tStrP")

Example response:

   { "errorCode": 0, "errMessage": "OK", "Version": "1.8", "UserName": "Admin"	}

Request Values of an Enumerable Attribute

Added in version 1.10

Request is sent to the path /api/sh5enum

Example request:

{"UserName": "Admin", "Password": "12345", "head": "111", "path": "6\\Otvets"}

head (String) - table identifier
path (String) - name of the enumerable attribute field

Example response:

{ 
 "errorCode": 0, "errMessage": "OK", "Version": "1.10", "UserName": "Admin",
 "actionType": "enum", "head": "111", "path": "6\\Otvets",
 "idents": [0, 1, 2, 5],
 "values": ["Vasya", "Lena", "Ira", "Evgeni Petrovich"]
}

ident - list of integer identifiers
values - list of text values

Work with Users

added in version 1.12

Request is sent to the path /api/sh5user. The required action is specified in the parameter "actionName". Input data is passed via the "Input" parameter. The "Input" parameter (array) contains a list of "data table" objects (see /api/sh5exec).

Create a New User

Request:

{"UserName": "Admin", "Password": "", "actionName": "Create", 
 "Input": 
 [
  { "head": "User", 
    "original": [ "Name", "Psw" ], 
    "values": [ [ "n.romanoff" ], [ "secret" ] ] 
  }
 ]
}

The following parameters are passed in the single-row table "User":

Name - login of the user being created
Psw - password for the user being created

Change User Password

Request:

{"UserName": "Admin", "Password": "", "actionName": "SetPsw", 
 "Input": 
 [
  { "head": "User", 
    "original": [ "Name", "Psw" ], 
    "values": [ [ "n.romanoff" ], [ "secretNew" ] ] 
  }
 ]
}

Delete User

Request:

{"UserName": "Admin", "Password": "", "actionName": "Delete", 
 "Input": 
 [
  { "head": "User", 
    "original": [ "Name" ], 
    "values": [ [ "n.romanoff" ] ] 
  }
 ]
}

List of System Privileges (bit numbers)

0 - right to create a user
1 - right to read the list of users
2 - right to read user rights information
3 - right to change any user's password
4 - right to change own password
5 - right to delete a user

6 - right to create/modify a role
7 - right to read the list of roles
8 - right to read role rights information
9 - right to assign roles to users
10 - right to delete a role

11 - right to modify the system dictionary,
12 - right to receive server statistics
13 - right to check the database file
14 - right to check and correct errors in the database file
15 - right to perform backup
16 - right to restore the database from an archive (with the database file loaded)
17 - right to create a new database (with the database file loaded)
18 - right to read and change the database file size
19 - right to read the list of connections
20 - right to terminate other users' connections

Get List of Users

Request:

  {"UserName": "Admin", "Password": "", "actionName": "List"}

Example response:

{
 "errorCode": 0, "errMessage": "OK", "Version": "1.12", "UserName": "Admin", 
 "shTable": 
 [
  {
   "head": "User", 
   "original": 
   ["Name", "Type", "WinError", "SysPrivs", "SysGrant", "Rid"], 
   "values": 
   [
    ["Petrov", "n.romanoff", "elena", "Ivanov", "Admin"], 
    [0, 0, 0, 0, 0], 
    [0, 0, 0, 0, 0], 
    [0, 0, 0, 0, 4294967295], 
    [0, 0, 0, 0, 4294967295], 
    [2, 3, 4, 1, 0]
   ]
  }
 ]
}

Description of table fields:

Name (tStrP) Username
Type (tUint8) Authentication type (0 - sdbserv; 1 - Windows(enabled); 2 - Windows(disabled))
WinError (tUint32) Win32Error for authentication type NOT sdbserv (value 0 means OK)
SysPrivs (tUint32) Bitmask of system privileges
SysGrant (tUint32) Mask of rights to assign system privileges to other users
Rid (tUint16) Unique user identifier

Modify User Rights

Request:

{
 "UserName": "Admin", "Password": "", "actionName": "SetPrivs", 
 "Input": 
 [
  { "head": "User", 
    "original": ["Name", "SysPrivs", "SysGrant", "RoleMask", "RoleGrant"], 
    "values":  [ ["n.romanoff" ], [ 255 ], [ 2 ], [ 13 ], [ 0 ] ]
   },
   { "head": "Procedures", 
     "original": ["Name", "Flags" ], 
     "values": 
   [ 
   [ "ModEInv1", "MissEMarks", "ModEInv0", "EMarkPresent", 
     "EInv1", "EInv0", "DelEInv", "EInvents" ],
   [  1, 3, 1, 1, 
      1, 1, 0, 3 ]
   ]
   }
 ]
}

Fields of the User table:

SysPrivs (tUint32) Bitmask of system privileges
SysGrant (tUint32) Mask of rights to assign system privileges to other users
RoleMask (tUint32) Mask of role identifiers
RoleGrant (tUint32) Mask of role grant option identifiers

Fields of the Procedures table:

Name (tStrZ) procedure name
Flags (tUint8):

0 - prohibit the procedure for the user; 1 - allow the procedure for the user; 3 - allow the procedure for the user and grant the grant option.

Get User Rights

Request:

{"UserName": "Admin", "Password": "", "actionName": "Read", 
 "Input": 
 [
  { "head": "User", 
    "original": [ "Name" ], 
    "values": [ [ "n.romanoff" ] ] 
  }
 ]
}

Example response:

 
{
 "errorCode": 0, "errMessage": "OK", "Version": "1.12", "UserName": "Admin", 
 "shTable": 
 [
  {
   "head": "User", 
   "original": 
   ["Name", "SysPrivs", "SysGrant", "RoleMask", "RoleGrant" ], 
   "values": [["n.romanoff"], [33170], [0], [13], [0]]
  }, 
  {
   "head": "Roles",
   "original": 
   ["Name", "Type", "WinError", "SysPrivs", "Rid" ], 
   "values": 
   [
    ["Controller", "Auditor", "Accountant", "Full Rights", "PUBLIC"], 
    [ 0, 0, 0, 0, 0 ], 
    [ 0, 0, 0, 0, 0 ], 
    [ 0, 0, 0, 0, 0 ], 
    [ 4, 3, 2, 1, 0 ]
   ]
  }, 
  {
   "head": "Procedures", 
   "original": 
   ["Name", "RoleMask", "Flags"], 
   "values": 
   [
    ["DeleteGDocsRDoc", "CreateGDocsByRDocList", "ModPlanCorrs", 
     "SetRDocStatus", "PlanCorrs", "UDefContractors", "UpdUContractor", 
     "RplUContractor", "DelUContractor", "UContractor", "UContractors" ], 
    [ 0, 0, 2, 2, 2, 2, 0, 2, 0, 2, 0 ],
    [ 0, 0, 1, 0, 1, 1, 0, 1, 0, 0, 0 ]
   ]
  }
 ]
}

The list of procedures in this example is greatly reduced; in reality, there are over 600.

Work with Roles

added in version 1.12

Request is sent to the path /api/sh5role. The required action is specified in the parameter "actionName". Input data is passed via the "Input" parameter. The "Input" parameter (array) contains a list of "data table" objects (see /api/sh5exec).

Get List of Roles

Request:

 
{"UserName": "Admin", "Password": "", "actionName": "List"}

Example response:

 
{
 "errorCode": 0, "errMessage": "OK", "Version": "1.12", "UserName": "Admin", 
 "shTable": 
 [
  {
   "head": "Role", 
   "original": 
   [
    "Name", "Type", "WinError", "SysPrivs", "Rid"
   ], 
   "values": 
   [
    ["Controller", "Auditor", "Accountant", "Full Rights", "PUBLIC" ], 
    [0, 0, 0, 0, 0], 
    [0, 0, 0, 0, 0], 
    [0, 0, 0, 0, 0], 
    [4, 3, 2, 1, 0]
   ]
  }
 ]
}

Description of table fields:

Name (tStrP) Role name
Type (tUint8) Authentication type (0 - sdbserv; 1 - Windows(enabled); 2 - Windows(disabled))
WinError (tUint32) Win32Error for authentication type NOT sdbserv (value 0 means OK)
SysPrivs (tUint32) Bitmask of system privileges
Rid (tUint16) Unique role identifier

Create a New Role

Request:

 
{"UserName": "Admin", "Password": "", "actionName": "Create", 
 "Input": 
 [
  { "head": "Role", 
    "original": [ "Name" ], 
    "values": [ [ "Supervisor" ] ] 
  }
 ]
}

Удалить роль

Запрос:

{"UserName": "Admin", "Password": "", "actionName": "Delete", 
 "Input": 
 [
  { "head": "Role", 
    "original": [ "Name" ], 
    "values": [ [ "Supervisor" ] ] 
  }
 ]
}

Modify Role Rights

Request:

{
 "UserName": "Admin", "Password": "", "actionName": "SetPrivs", 
 "Input": 
 [
  { "head": "Role", 
    "original": ["Name", "SysPrivs"], 
    "values":  [ ["Accountant" ], [ 16 ]]
   },
   { "head": "Procedures", 
     "original": ["Name", "Flags" ], 
     "values": 
   [ 
    [ "ModEInv1", "MissEMarks", "ModEInv0", "EMarkPresent", 
      "EInv1", "EInv0", "DelEInv", "EInvents" 
    ],
    [  1, 0, 1, 1, 1, 1, 0, 1 ]
   ]
   }
 ]
}

Fields of the Role table:

Name (tStrP) Role name
SysPrivs (tUint32) Bitmask of system privileges

Fields of the Procedures table:

Name (tStrZ) procedure name
Flags (tUint8):

0 - prohibit the procedure for the role; 1 - allow the procedure for the role;

Get Role Rights

Request:

{"UserName": "Admin", "Password": "", "actionName": "Read", 
 "Input": 
 [
  { "head": "Role", 
    "original": [ "Name" ], 
    "values": [ [ "Accountant" ] ] 
  }
 ]
}

Example response:

{
 "errorCode": 0, "errMessage": "OK", "Version": "1.12", "UserName": "Admin", 
 "shTable": 
 [
  {
   "head": "Role", 
   "original": ["Name", "SysPrivs"], 
   "values": [ ["Accountant"], [4112]]
  }, 
  {
   "head": "Procedures", 
   "original": 
   [ "Name", "Flags" ], 
   "values": 
   [
    [
     "ModDivBuyPlan", "DivBuyPlan", "DelGDoc9", "UpdGDoc9", "InsGDoc9", 
     "GDoc9", "CurrRates", "ModCurrencies", "Currencies"
    ], 
    [
      0, 0, 1, 1, 1, 1, 1, 1, 1
    ]
   ]
  }
 ]
}

The list of procedures in this example is significantly reduced; in practice, there are more than 600 of them.