Введение

Версия 1.11

Сервер StoreHouse 5 Web API 2 предоставляет возможность получать и передавать информацию на сервер StoreHouse5 посредством файлов формата JSON через протокол HTTP.

Сервер StoreHouse5 общается с внешним миром исключительно с помощью процедур, идентифицируемых по имени. Процедура в качестве параметров принимает датасеты (таблицы) и в ответ заполняет их запрошенной информацией. Дататсеты SH5 могут быть однострочными и многострочными.

Доступные операции:

• • Запросить настройки сервера и информацию о БД: /api/sh5info

  • Запросить наличие прав на выполнение процедуры: /api/sh5able

  • Изменить свой пароль: /api/sh5pass

  • Информация о лицензии: /api/sh5lic

  • Запросить список датасетов процедуры: /api/sh5struct

  • Выполнить процедуру: /api/sh5exec

  • Cоздать атрибутное поле: /api/sh5CreateAttr

  • Запросить значения перечислимого атрибута: /api/sh5enum

  • Работа с пользователями: /api/sh5user

  • Работа с ролями: /api/sh5role

По указанным путям надо выполнять POST-запросы с передачей в Content JSON-файла с параметрами запроса. Файлы JSON должны быть в кодировке UTF-8. Пример запроса:

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

• UserName (string)- имя пользователя StoreHouse5

• Password (string)- пароль пользователя StoreHouse5

• procName (string)- название процедуры StoreHouse5

UserName и Password являются обязательными во всех запросах. Параметр procName присутствует в запросах на /api/sh5struct и /api/sh5exec.

В результате выполнения запроса будет прислан ответный JSON-файл. Пример ответа:

{
 "errorCode": 1, 
 "errMessage": "Процедура XDivisions не найдена.", 
 "Version": "1.1", 
 "UserName": "Admin", "actionName": "XDivisions", "actionType": "Structure", 
 "errorInfo": { "moduleId": 1, "moduleName": "SDBCLI.DLL", "errorId": 194 }
}

• errorCode (number)- признак наличия ошибки (0/1).

• errMessage (string)- текст ошибки

• Version (string)- версия сервера SH5WAPI2

Эти три значения приcутствуют в любом ответе от сервера.

• UserName (string) - переданное в запросе имя пользователя

В случае успешного выполнения запроса errorCode будет равен 0. В случае ошибки значение errorCode будет равно 1, и будет присутствовать объект errorInfo с дополнительной информацией об ошибке:

• moduleId (number) - идентификатор модуля, из котрого поступила ошибка [0..5]

• moduleName (string) - название модуля, из котрого поступила ошибка

• errorId (number) - код ошибки, свой у каждого модуля

Возможные значения moduleId:

• 0 - BRISH.DLL, errorId всегда равен 0

• 1 - SDBCLI.DLL, наиболее частые значения errorId:

  • 150 - Неверно указано имя пользователя или пароль

  • 194 - Указанная процедура не существует

  • 2102 - нет связи с сервером SH5 через локальный протокол

  • 2205 - нет связи с сервером SH5 через TCP/IP

• 2 - DOMM.DLL

• 3 - MSDSET.DLL

• 4 - SHSRV64.DLL, коды ошибок: https://docs.rkeeper.ru/pages/viewpage.action?pageId=19612474

• 5 - SH5WAPI2, errorId всегда равен 1

GZIP

Начиная с версии 1.8.3 Если в запросе присутствует заголовок

Accept-Encoding: gzip

и размер ответа превышает 32kb, то ответ возвращается упакованным в gzip и с заголовком

Content-Encoding: gzip

Более того, с версии 1.11 ответы, превышающие 10 MB в обязательном порядке пакуются в gzip.

Запрос настроек сервера и информации о БД

Запросы посылаются по пути /api/sh5info

Чтобы узнать, с каким именно сервером StoreHouse5 происходит работа, надо послать запрос на этот адрес без какого-либо JSON. При этом допускается использование не только метода POST, но и GET. Благодаря этому выполнить его можно даже из браузера, что бывает удобно для быстрой проверки наличия сервера WebAPI.
Пример ответного JSON:

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

Или такой ответ:

{
  "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-подключение локальное; 1-подключение через TCP/IP.

• Server (string)- присутствует только для локального подключения - имя сервера SH5

• Host (string) - присутствует только для TCP/IP - компьютер, где запущен сервер SH5

• Port (number) - присутствует только для TCP/IP и если порт не стандартный

• LinkDisp (string)- строка с текстовым описанием параметров подключения

Если по этому же пути выполнить POST-запрос с вложенным JSON с указанием логина и пароля, то сервер WebAPI подключится к серверу StoreHouse и добавит в ответ информацию о БД.

Запрос:

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

Ответ:

{
 "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) - уникальный идентификатор БД

• Size (string) - текущий размер файла БД

• Version (string) - версия БД

Запросить наличие прав на выполнение процедур

Запрос посылается по пути /api/sh5able
Пример запроса:

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

• procList (массив) - список процедур StoreHouse5

Пример ответа:

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

• allow (массив) - наличие у пользователя права на выполнение соответствующей процедуры

Изменить пароль

Запрос посылается по пути /api/sh5pass
Пример запроса:

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

• newValue (string) - новый пароль

Пример ответа:

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

Информация о лицензии

Запрос посылается по пути /api/sh5lic
Пример запроса:

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

Пример ответа:

	{ 
	 "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 (массив) - список лицензий, имеющихся в БД StoreHouse5

Каждая лицензия содержит следующую информацию:

• type (number) - SoftCode лицензии

• count (number) - кол-во лицензий этого вида

• expDate (string) - строк действия лицензии

• objectId (number) - идентификатор объекта

• key (string) - идентификатор виртуального ключа

Запрос списка датасетов процедуры

Запрос посылается по пути /api/sh5struct

JSON запроса содержит только три параметра: UserName, Password, procName. Пример запроса:

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

Ответ содержит элементы:

• UserName (string) - переданное имя пользователя

• actionName (string) - название процедуры StoreHouse5

• actionType (string) - «Structure»- запрошенная операция

• shTable (массив) - список объектов «структура таблицы»

массив элементов «структура таблицы».

Объект «структура таблицы» содержит следующие элементы:

• head (String) - идентификатор таблицы

• SingleRow (Bool) - однострочный датасет (true) или многострочный (false)

• fields (массив) - список объектов «поле таблицы»

Объект «поле таблицы» содержит следующие элементы:

• path (String) - оригинальное имя поля

• type (String) - тип поля

• size (String) - размер поля

• alt (String) - необязательный, альтернативное имя поля

Пример успешного ответа:

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

Выполнение процедуры

Запрос посылается по пути /api/sh5exec. Передача данных в процедуру осуществляется через параметр «Input». Либо, для совместимости со старой версией, через параметр «dsParams». Второй метод устарел и в будущем может быть исключён.

Параметр «Input» (массив) содержит список объектов «таблица с данными».

Параметр «dsParams» (объект) содержит объекты «поле с данными», при этом допускаются только альтернативные названия полей .

Ответ содержит массив элементов «таблица с данными».

Типы «tShortDate» и «tLongDate» должны передаваться в формате «yyyy-mm-dd». И если в ответе есть такие типы данных, то они будут именно в этом формате.

Тип «tGuid» должен передаваться в формате «{XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX}».

Типы «tBinary» и «tBtData» передаются в HEX формате. Например, если требуется поместить двухбайтное целое (WORD) равное 2687 в такое поле: «7F0A». А если строку «William Shakespeare» с указанием байта длины перед ней: «1357696c6c69616d205368616b65737065617265»

Объект «таблица с данными» содержит следующие элементы:

• head (String) - идентификатор таблицы

• original - массив оригинальных названий полей (string)

• fields - массив альтернативных названий полей (string)

• values - массив, содержащий массивы значений полей.

• status - необязательный, массив статусов записей (string)

Пример запроса с параметром «Input»:

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

Некоторые процедуры для модификации/удаления записи в таблице требуют передачи её статуса. В этом случае в объект «таблица с данными» надо добавлять массив «status», в котором перечислить нужные статусы для каждой записи. Возможные варианты: «Insert», «Modify», «Delete». По умолчанию все записи получают статус «Insert».

Пример запроса со статусами записей:

{
 "UserName": "Admin", "Password": "", "procName": "ModCountries", 
 "Input": 
 [
  {"head": "231", 
   "original": [ "1", "2", "3" ], 
   "values": 
   [
    [ 1, null, 8 ], 
    [ "643", "UTO", "NET" ], 
    [ "Россия", "Утопия", "Нетландия" ]
   ], 
   "status": [ "Modify", "Insert", "Delete" ]
  }
 ]
}

Объект «поле с данными» - это массив, содержащий значения поля для всех записей таблицы. Пример запроса с параметром «dsParams»:

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

Создать атрибутное поле

Добавлено в версии 1.8

Запрос посылается по пути /api/sh5CreateAttr

Пример запроса:

{ "UserName": "Admin", "Password": "12345", "bob": "aTable_Attrs",
  "ident": "UserComment", "caption": "Комментарий пользователя", 
  "type": "tStrP" }

• bob (string) - Идентификатор контейнера (SdbMan: Обслуживание - Статистика - Поля бин.объектов)

• ident (string) - Идентификатор создаваемого поля

• caption (string) - Заголовок создаваемого поля

• type (string) - Тип поля. Поддерживаются только такие: («tInt32», «tInt64», «tDouble», «tLongDate», «tStrP» )

Пример ответа:

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

Запросить значения перечислимого атрибута

Добавлено в версии 1.10

Запрос посылается по пути /api/sh5enum

Пример запроса:

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

• head (String) - идентификатор таблицы

• path (String) - имя поля атрибута перечислимого типа

Пример ответа:

{ 
 "errorCode": 0, "errMessage": "OK", "Version": "1.10", "UserName": "Admin",
 "actionType": "enum", "head": "111", "path": "6\\Otvets",
 "idents": [0, 1, 2, 5],
 "values": ["Вася", "Лена", "Ира", "Евгений Петрович"]
}

• ident - список целочисленных идентификаторов

values - список текстовых значений

Работа с пользователями

добавлено в версии 1.12

Запрос посылается по пути /api/sh5user. Необходимое действие указывается в параметре «actionName». Передача входных данных осуществляется через параметр «Input». Параметр «Input» (массив) содержит список объектов «таблица с данными» (см. /api/sh5exec).

Создать нового пользователя

Запрос:

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

В однострочной таблице «User» передаются параметры:

• Name - логин создаваемого пользователя

• Psw - пароль для создаваемого пользователя

Поменять пароль пользователя

Запрос:

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

Удалить пользователя

Запрос:

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

Список системных привилегий (номера бит)

• 0 - право создавать пользователя

• 1 - право читать список пользователей

• 2 - право читать информацию о правах пользователя

• 3 - право изменять пароль любого пользователя

• 4 - право изменять пароль самому себе

• 5 - право удалять пользователя

• 6 - право создавать/модифицировать роль

• 7 - право читать список ролей

• 8 - право читать информацию о правах роли

• 9 - право назначать роли пользователям

• 10 - право удалять роль

• 11 - право изменять системный словарь,

• 12 - право получать статистику по серверу

• 13 - право делать проверку файла БД

• 14 - право делать проверку файла БД с исправлением ошибок

• 15 - право делать резервное копирование

• 16 - право восстанавливать БД из архива (при загруженном файле БД)

• 17 - право создавать новую БД (при загруженном файле БД)

• 18 - право читать и изменять размер файла БД

• 19 - право читать список соединений

• 20 - право завершать чужие соединения

Получить список пользователей

Запрос:

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

Пример ответа:

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

Описание полей таблицы:

• Name (tStrP) Имя пользователя

• Type (tUint8) Тип аутентификации (0 - sdbserv; 1 - Windows(enabled); 2 - Windows(disabled))

• WinError (tUint32) Win32Error при типе аутентификации НЕ sdbserv (значение 0 значит ОК)

• SysPrivs (tUint32) Битовая маска системных привилегий

• SysGrant (tUint32) Маска прав на назначение другим пользователям системных привилегий

• Rid (tUint16) Уникальный идентификатор пользователя

Изменить права пользователя

Запрос:

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

Поля таблицы User:

• SysPrivs (tUint32) Битовая маска системных привилегий

• SysGrant (tUint32) Маска прав на назначение другим пользователям системных привилегий

• RoleMask (tUint32) Маска идентификаторов ролей

• RoleGrant (tUint32) Маска идентификаторов грант опций для ролей

Поля таблицы Procedures:

• Name (tStrZ) имя процедуры

• Flags (tUint8):

0 - запретить процедуру для пользователя; 1 - разрешить процедуру для пользователя; 3 - разрешить процедуру для пользователя и выдать грант-опцию.

Получить права пользователя

Запрос:

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

Пример ответа:

 
{
 "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": 
   [
    ["Контролёр", "Аудитор", "Бухгалтер", "Все права", "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 ]
   ]
  }
 ]
}

Список процедур в этом примере сильно сокращён, фактически их более 600.

Работа с ролями

добавлено в версии 1.12

Запрос посылается по пути /api/sh5role. Необходимое действие указывается в параметре «actionName». Передача входных данных осуществляется через параметр «Input». Параметр «Input» (массив) содержит список объектов «таблица с данными» (см. /api/sh5exec).

Получить список ролей

Запрос:

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

Пример ответа:

 
{
 "errorCode": 0, "errMessage": "OK", "Version": "1.12", "UserName": "Admin", 
 "shTable": 
 [
  {
   "head": "Role", 
   "original": 
   [
    "Name", "Type", "WinError", "SysPrivs", "Rid"
   ], 
   "values": 
   [
    ["Контролёр", "Аудитор", "Бухгалтер", "Все права", "PUBLIC" ], 
    [0, 0, 0, 0, 0], 
    [0, 0, 0, 0, 0], 
    [0, 0, 0, 0, 0], 
    [4, 3, 2, 1, 0]
   ]
  }
 ]
}

Описание полей таблицы:

• Name (tStrP) Имя роли

• Type (tUint8) Тип аутентификации (0 - sdbserv; 1 - Windows(enabled); 2 - Windows(disabled))

• WinError (tUint32) Win32Error при типе аутентификации НЕ sdbserv (значение 0 значит ОК)

• SysPrivs (tUint32) Битовая маска системных привилегий

• Rid (tUint16) Уникальный идентификатор роли

Создать новую роль

Запрос:

 
{"UserName": "Admin", "Password": "", "actionName": "Create", 
 "Input": 
 [
  { "head": "Role", 
    "original": [ "Name" ], 
    "values": [ [ "Смотритель" ] ] 
  }
 ]
}

Удалить роль

Запрос:

{"UserName": "Admin", "Password": "", "actionName": "Delete", 
 "Input": 
 [
  { "head": "Role", 
    "original": [ "Name" ], 
    "values": [ [ "Смотритель" ] ] 
  }
 ]
}

Изменить права роли

Запрос:

{
 "UserName": "Admin", "Password": "", "actionName": "SetPrivs", 
 "Input": 
 [
  { "head": "Role", 
    "original": ["Name", "SysPrivs"], 
    "values":  [ ["Бухгалтер" ], [ 16 ]]
   },
   { "head": "Procedures", 
     "original": ["Name", "Flags" ], 
     "values": 
   [ 
    [ "ModEInv1", "MissEMarks", "ModEInv0", "EMarkPresent", 
      "EInv1", "EInv0", "DelEInv", "EInvents" 
    ],
    [  1, 0, 1, 1, 1, 1, 0, 1 ]
   ]
   }
 ]
}

Поля таблицы Role:

• Name (tStrP) Имя роли

• SysPrivs (tUint32) Битовая маска системных привилегий

Поля таблицы Procedures:

• Name (tStrZ) имя процедуры

• Flags (tUint8):

0 - запретить процедуру для роли; 1 - разрешить процедуру для роли;

Получить права роли

Запрос:

{"UserName": "Admin", "Password": "", "actionName": "Read", 
 "Input": 
 [
  { "head": "Role", 
    "original": [ "Name" ], 
    "values": [ [ "Бухгалтер" ] ] 
  }
 ]
}

Пример ответа:

{
 "errorCode": 0, "errMessage": "OK", "Version": "1.12", "UserName": "Admin", 
 "shTable": 
 [
  {
   "head": "Role", 
   "original": ["Name", "SysPrivs"], 
   "values": [ ["Бухгалтер"], [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
    ]
   ]
  }
 ]
}

Список процедур в этом примере сильно сокращён, фактически их более 600.