====== Описание формата обмена через HTTP-сервис ======
===== Теоретическая часть =====
При обращении к HTTP-сервису формируется URL, который выглядит следующим образом: \\
**http://host/base/hs/корневойURL/относительныйURL/?param1=xx¶rm2=yy** \\
* http://host/base – обычный URL, по которому выполняется доступ, например, к информационной базе с помощью веб-клиента. При наличии разделителей, не поддерживается указание значений разделителей с помощью параметра Z командной строки запуска клиентского приложения. //base// - имя базы данных при публикации на Web-сервере.\\
* hs – признак того, что выполняется обращение к HTTP-сервису (в отличие от ws, который определяет доступ к Web-сервису).\\
* корневойURL – имя ресурса, которое определяет группу ресурсов, связанных общим смыслом. Задается в свойстве объекта HTTP-сервис.\\
* относительныйURL – определяет ресурс, к которому будет выполняться обращение. Относительный URL, указанный в запросе, будет использован для определения конкретного ресурса, к которому выполнялось обращение. Правило сопоставления задается в объекте Шаблон URL.\\
* p1=x&p2=y - список параметров запроса.\\
===== Документы =====
Конфигурация "Торговое предприятие 5.2" (Далее "ТП5") позволяет получить ограниченный доступ к определенному списку документов. Документы представляются в JSON формате. Список возвращаемых полей и табличных частей описан для каждого документа индивидуально. Для чтения/создания доступны следующие типы документов :\\
* Планирование изменения розничных цен (Чтение)
* Перемещение (Чтение)
* Приходная накладная (Чтение)
* Приходная накладная реализации (Чтение)
* Акт о переоценке (Запись)
* Акт разногласия (Запись)
* Выгрузка из ТСД (Запись)
* Корректировка перемещения (Запись)
* Потребность склада (Запись)
==== Описание HTTP запросов ====
* http://host/base – обычный URL, по которому выполняется доступ, например, к информационной базе с помощью веб-клиента. При наличии разделителей, не поддерживается указание значений разделителей с помощью параметра Z командной строки запуска клиентского приложения. **base** - имя базы данных при публикации на Web-сервере.\\
* hs – признак того, что выполняется обращение к HTTP-сервису (в отличие от ws, который определяет доступ к Web-сервису).\\
* корневойURL – имя ресурса, которое определяет группу ресурсов, связанных общим смыслом. Задается в свойстве объекта HTTP-сервис.\\
* относительныйURL – определяет ресурс, к которому будет выполняться обращение. Относительный URL, указанный в запросе, будет использован для определения конкретного ресурса, к которому выполнялось обращение. Правило сопоставления задается в объекте Шаблон URL.\\
* p1=x&p2=y - список параметров запроса.\\
=== Описание запроса поиска SEARCH ===
Тип запроса - GET \\
URL запроса - //http://host/base/hs/sc5/documents/add?pos=N&doctype={chprices|mgoods|goods|rsgoods}&type={gtin|uid|num|inum}&sdata=some_string// \\
Результат - JSON. Поля JSON - data, errcode, errmsg. \\
data - содержит полученную информацию. Документ или массив документов, найденных в базе данных.\\
errcode - код ошибки. 0 - нет ошибок, возвращен документ. 1..n - ошибка при выполнении операции поиска, либо ошибка в запросе. -n..-1 - не ошибка. -1 - возвращен массив документов. \\
errmsg - описание ошибки, сообщение системы.\\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/search?doctype=chprices&pos=1&type=gtin&sdata=PIRC%201dwln9AeWU:1C{Fl6<`Hm
Пример корректного ответа JSON:
{"data": {
"uid": "48f5427a-1fd5-11e5-9149-0019d1af8e62",
"gtin": "PIRC 1dwln9AeWU:1C{Fl6<`Hm",
"num": "\u041c\u041f0000000000001",
"date": "2015-07-01T12:40:36+03:00",
"comment": "",
"store": "\u041c\u041f00002",
"items": [
{
"code": 12,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"oldprice": 20,
"price": 22
},
{
"code": 13,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"oldprice": 20,
"price": 23
}
]
},
"errcode": 0,
"errmsg": ""}
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/search?debug&doctype=chprices&pos=1&type=num&sdata=%D0%9C%D0%9F0000000000001
Пример корректного ответа JSON, с несколькими документами, удовлетворяющими параметрам поиска. В параметре "urlparam" выводятся строка параметров "url" для точного получения документа:
{
"data": [
{
"uid": "48f5427a-1fd5-11e5-9149-0019d1af8e62",
"gtin": "PIRC 1dwln9AeWU:1C{Fl6<`Hm",
"num": "\u041c\u041f0000000000001",
"date": "2015-07-01T12:40:36+03:00",
"comment": "",
"desc": "\u041c\u041f0000000000001(01.07.2015)",
"urlparam": "pos=1&doctype=chprices&type=uid&sdata=48f5427a-1fd5-11e5-9149-0019d1af8e62"
},
{
"uid": "4354f341-20cb-11e5-9149-0019d1af8e62",
"gtin": "PIRC 1dwln9AeWU:1C{Fl6<`Hm",
"num": "\u041c\u041f0000000000001",
"date": "2014-07-02T18:01:41+03:00",
"comment": "",
"desc": "\u041c\u041f0000000000001(02.07.2014)",
"urlparam": "pos=1&doctype=chprices&type=uid&sdata=4354f341-20cb-11e5-9149-0019d1af8e62"
}
],
"errcode": -1,
"errmsg": "\u041d\u0430\u0439\u0434\u0435\u043d\u043e \u043d\u0435\u0441\u043a\u043e\u043b\u044c\u043a\u043e \u0434\u043e\u043a\u0443\u043c\u0435\u043d\u0442\u043e\u0432!"}
=== Описание запроса добавления ADD ===
Тип запроса - POST \\
//http://host/base/hs/sc5/documents/add?pos=N&doctype={chpreport|disreport|dctdoc|mcdoc|sreq}// \\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/add?debug&doctype=chpreport&pos=1
Тело запроса POST:
{
"odoctype": "chprices",
"ouid": "48f5427a-1fd5-11e5-9149-0019d1af8e62",
"uid": "48f5555a-1fd5-11e5-9149-0019d1af8e62",
"comment": "ТЕСТОВЫЙ ДОКУМЕНТ",
"nsec": 1,
"items": [
{
"code": 12,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"oldprice": 20,
"price": 22
},
{
"code": 13,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"oldprice": 20,
"price": 23
}
]
}
Пример корректного ответа JSON:
{
"data": null,
"errcode": 0,
"errmsg": ""
}
=== Корректировка перемещения ===
Тип запроса - POST \\
//http://host/base/hs/sc5/documents/add?pos=N&doctype=mcdoc // \\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/add?doctype=mcdoc&pos=1
Тело запроса POST:
{
"odoctype": "mgoods",
"ouid": "2ac1326f-a7d0-11dc-aed3-0011d8d4ad08",
"uid": "48f5555a-1fd5-11e5-9149-0019d1af8e62",
"comment": "ТЕСТОВЫЙ ДОКУМЕНТ",
"nsec": 1,
"items":[
{
"code": 13,
"attribute": 0,
"price": 20,
"realq": 30
},
{
"code": 12,
"attribute": 0,
"price": 20,
"realq": 30
},
{
"code": 11,
"attribute": 0,
"price": 20,
"realq": 30
}
]
}
Пример корректного ответа JSON:
{
"data": null,
"errcode": 0,
"errmsg": ""
}
=== Акт разногласия ===
Тип запроса - POST \\
//http://host/base/hs/sc5/documents/add?pos=N&doctype=disreport // \\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/add?doctype=disreport&pos=1
Тело запроса POST:
{
"odoctype": "rgoods",
"ouid": "8c7bd876-a72a-11dc-aed3-0011d8d4ad08",
"uid": "48f5430a-1fd5-11e5-9149-0019d1af8e62",
"comment": "ТЕСТОВЫЙ ДОКУМЕНТ",
"nsec": 1,
"items": [
{
"code": 21,
"attribute": 0,
"price": 200,
"realq": 3
},
{
"code": 20,
"attribute": 0,
"price": 210,
"realq": 5
},
{
"code": 16,
"attribute": 0,
"price": 190,
"realq": 9
},
{
"code": 15,
"attribute": 0,
"price": 230,
"realq": 3
}
]
}
Пример корректного ответа JSON:
{
"data": null,
"errcode": 0,
"errmsg": ""
}
==== Планирование изменения розничных цен ====
Примеры URL :\\
http://host/base/hs/documetns/chprices/?gtin=4792156004600 \\
http://host/base/hs/documetns/chprices/?uuid=6F9619FF-8B86-D011-B42D-00CF4FC964FF \\
http://host/base/hs/documetns/chprices/?number=12345 \\
* **documents** - Корневой URL
* **chprices** - Относительный URL
* Список параметров:
* **uuid** - уникальный идентификатор документа в формате XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX, где X - шестнадцатеричное число.
* **number** – номер документа.
* **gtin** – внутренний штрихкод документа.
При указании нескольких параметров (uuid, gtin, number) поиск документа будет осуществлен до первого удовлетворяющего условию документа по приоритету - uuid, gtin, number. \\
Результат выполнения команды - Строка JSON.
==== Потребность склада ====
Примеры URL :\\
http://host/base/hs/sc5/documents/add?pos=1&doctype=sreq
Тип запроса - POST \\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/add?pos=1&doctype=sreq
Тело запроса POST:
{
"uid": "48f5555a-1fd5-11e5-9149-0019d1af8e62",
"comment": "ТЕСТОВЫЙ ДОКУМЕНТ",
"nsec": "1",
"items":[
{
"code": 13,
"attribute": 0,
"unit": 1,
"q": 40
},
{
"code": 12,
"attribute": 0,
"unit": 1,
"q": 40
},
{
"code": 11,
"attribute": 0,
"unit": 1,
"q": 40
}
]
}
Пример корректного ответа JSON:
{
"data": null,
"errcode": 0,
"errmsg": ""
}
==== Приходная накладная ====
Примеры URL :\\
http://localhost/www/hs/sc5/documents/search?pos=1&type=gtin&sdata=P om}uTdb1ubJj2b?rrJn<
Тип запроса - GET \\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/search?pos=1&type=gtin&sdata=P%20om%7DuTdb1ubJj2b%3FrrJn<
Пример корректного ответа JSON:
{
"data": {
"desc": "МП0000000005 (15.01.2013)",
"gtin": "P om}uTdb1ubJj2b?rrJn<",
"storeto": "МП00002",
"doctype": "mgoods",
"comment": "",
"ouid": "8c7bd878-a72a-11dc-aed3-0011d8d4ad08",
"num": "МП0000000005 ",
"date": "2013-01-15T16:02:07+03:00",
"uid": "2ac1326f-a7d0-11dc-aed3-0011d8d4ad08",
"items": [
{
"code": 13,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"price": 20,
"q": 40
},
{
"code": 12,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"price": 20,
"q": 40
},
{
"code": 11,
"attribute": 0,
"unit": 1,
"coefficient": 1,
"price": 20,
"q": 40
}
],
"storefrom": "МП00001"
},
"errcode": 0,
"errmsg": "",
"debug": ""
}
==== Выгрузка из ТСД ====
Примеры URL :\\
http://host/base/hs/sc5/documents/add?pos=1&doctype=dctdoc
Тип запроса - POST \\
Пример корректного запроса:
http://localhost/www/hs/sc5/documents/add?pos=1&doctype=dctdoc
Тело запроса POST:
{
"uid": "48f5555a-1fd5-11e5-9149-0019d1af8e62",
"comment": "ТЕСТОВЫЙ ДОКУМЕНТ",
"nsec": 1,
"purpose": "ТЕКСТ НАЗНАЧЕНИЕ ДО 75 СИМВОЛОВ",
"items":[
{
"code": 13,
"attribute": 0,
"unit": 1,
"price": 20,
"rprice": 20,
"q": 40
},
{
"code": 12,
"attribute": 0,
"unit": 1,
"price": 20,
"rprice": 20,
"q": 40
},
{
"code": 11,
"attribute": 0,
"unit": 1,
"price": 20,
"rprice": 20,
"q": 40
}
]
}
Пример корректного ответа JSON:
{
"data": null,
"errcode": 0,
"errmsg": ""
}
===== Справочники =====
Конфигурация "Торговое предприятие 5.2" (Далее "ТП5") позволяет получить ограниченный доступ к определенному списку справочников. Справочники представляются в JSON формате. Список возвращаемых полей и табличных частей описан для каждого документа индивидуально. Для чтения доступны следующие типы справочников :\\
* Номенклатура (Чтение)
=== Описание запроса поиска SEARCH ===
Тип запроса - GET \\
URL запроса - //http://host/base/hs/sc5/catalogs/search?pos=N&cattype={goods}&type={gtin|uid|code}&sdata=some_string// \\
Результат - JSON. Поля JSON - data, errcode, errmsg. \\
data - содержит полученную информацию. Документ или массив документов, найденных в базе данных.\\
errcode - код ошибки. 0 - нет ошибок, возвращен документ. 1..n - ошибка при выполнении операции поиска, либо ошибка в запросе. -n..-1 - не ошибка. -1 - возвращен массив документов. \\
errmsg - описание ошибки, сообщение системы.\\
Пример корректного запроса:
http://localhost/www/hs/sc5/catalogs/search?cattype=goods&pos=1&type=gtin&sdata=2100100000110
Пример корректного ответа JSON:
{
"data": {
"gtin": "2100100000110",
"name": "Газ. вода 7UP 0,5 л.",
"desc": "[43]Газ. вода 7UP 0,5 л.",
"uid": "c829e16a-9d8a-11dc-aed3-0011d8d4ad08",
"spr": "43;2100100000110;Газ. вода 7UP 0,5 л.;Газ. вода 7UP 0,5 л.;18.90;31.000;0;0;;0;201;;0;1;0;;1;;0;;;;0;0",
"code": 43
},
"errcode": 0,
"errmsg": ""
}
===== Отчеты =====
=== Запрос всех доступных отчетов ===
URL запроса
http://host/base/hs/sc5/reports/reports/get?pos={1..N - int}&userid={1..N - int}&version={1.0 - str}//
Пример:
http://host/base/hs/sc5/reports/reports/get?pos=2&userid=2&version=1.0//
Корректный ответ содержит все доступные пользователю отчеты и url для построения отчета.
{"data": [
{
"repid": "43ce8df3-6212-4b7f-9a42-ef5357fa4e06",
"params": [
{
"name": "Период",
"name_en": "period",
"req": false,
"type": "Дата",
"val": null,
"desc": "Период",
"kcamp": "Равно"
}
],
"desc": "ТоварныйОтчет",
"urlparam": "pos=2&userid=2&repid=43ce8df3-6212-4b7f-9a42-ef5357fa4e06&p1=period&p1_kcamp=$p1_kcamp&p1_val=$p1_val"
},
{
"repid": "0e398f35-4c72-4823-997a-86192c52fb9e",
"params": [
{
"name": "НачалоПериода",
"name_en": "speriod",
"req": false,
"type": "Дата",
"val": null,
"desc": "Начало периода",
"kcamp": "Равно"
},
{
"name": "КонецПериода",
"name_en": "fperiod",
"req": false,
"type": "Дата",
"val": null,
"desc": "Конец периода",
"kcamp": "Равно"
}
],
"desc": "РеестрДокументов",
"urlparam": "pos=2&userid=2&repid=0e398f35-4c72-4823-997a-86192c52fb9e&p1=speriod&p1_kcamp=$p1_kcamp&p1_val=$p1_val&p2=fperiod&p2_kcamp=$p2_kcamp&p2_val=$p2_val"
},
{
"repid": "ee2e5827-11d0-4225-bf4e-65ad4836a393",
"params": [
{
"name": "НачалоПериода",
"name_en": "speriod",
"req": false,
"type": "Дата",
"val": null,
"desc": "Начало периода",
"kcamp": "Равно"
},
{
"name": "КонецПериода",
"name_en": "fperiod",
"req": false,
"type": "Дата",
"val": null,
"desc": "Конец периода",
"kcamp": "Равно"
}
],
"desc": "СопроводительныйРеестрДокументов",
"urlparam": "pos=2&userid=2&repid=ee2e5827-11d0-4225-bf4e-65ad4836a393&p1=speriod&p1_kcamp=$p1_kcamp&p1_val=$p1_val&p2=fperiod&p2_kcamp=$p2_kcamp&p2_val=$p2_val"
},
{
"repid": "a8ac523b-4970-4767-b0f4-a71cfc8422e0",
"params": [
{
"name": "ПараметрыДанных.Период",
"name_en": "Period",
"req": false,
"type": "СтандартныйПериод",
"val": null,
"desc": "Период",
"kcamp": "Равно"
},
{
"name": "Отбор.ККМ",
"name_en": "KKM",
"req": false,
"type": "Строка",
"val": null,
"desc": "ККМ",
"kcamp": "Равно,НеРавно,ВИерархии,НеВИерархии,Заполнено,НеЗаполнено"
}
],
"desc": "ДанныеZОтчетов(Предопределённый отчет конфигурации)",
"urlparam": "pos=2&userid=2&repid=a8ac523b-4970-4767-b0f4-a71cfc8422e0&p1=Period&p1_kcamp=$p1_kcamp&p1_val=$p1_val&p2=KKM&p2_kcamp=$p2_kcamp&p2_val=$p2_val"
}
],
"errcode": 0,
"errmsg": "",
"debug": "" }
=== Запрос отчета ===
URL запроса
http://host/base/hs/sc5/reports/get?pos={1..N - int}&userid={1..N - int}&version={1.0 - str}&repid={UID - str}&p1={ParamName - str}&p1_kcamp={Key comparison - str}&p1_val={Value - str}&p2...//
Пример:
http://localhost/loc/hs/sc5/reports/get?pos=2&userid=2&repid=03f3351c-1dff-436b-976d-5d8ee169d702&p1=Period&p1_kcamp=Равно&p1_val=2015-09-01T12:09:44+03:00&p2=Nomenklatura&p2_kcamp=Равно&p2_val=11//
Корректный ответ содержит готовый отчет для отображения в строке - Base64(ZIP(MXL)). т.е. для получения файла отчета необходимо полученную строку сохранить Base64Значение -> ZIP архив -> MXL файл.
{
"data": {
"data": "UEsDBBQAAAAIAG6MI0fFTWjTHgMAAOwHAAAOAHkAdjhfNzgzQ18xNC5teGxTRGQA\r\noAAAAAAIACBOg+5jZGBpEGFgYFBhgAAHIGZkAjNZFYCEApDNyArhiwKJI1VHJoZF\r\nf\/yttzEsCaSOiSGBgQUsLcHwn1EeQy8DgwhEnBEiLsQAEdvPKAwX44bqX8kghKJf\r\nEcgGAFVUDQAHr1roVa9a6FWvWuhVjVU7b9RAEA4dipT\/YBnR7UYz6\/V6Nx1CdDxa\r\nWj\/uJCQq2sjSkRQIRQIKJFJAQkFPCDkR3ZHLX1j\/Ev4Cs+vX3TmB83N2PK9vHusn\r\nz54\/fPR46+7WHbr\/zK\/3NUOm2c72fngvZGFIK2SetN\/tr+rIzgJ7bRdBdWh\/24Wd\r\nV2\/smb2yl9W7TURKZxiFZomoSTJOL8nAvaD03oCNY5EUudYci8hwCVnEszzLeGF0\r\npgyM0kJpRtLu8oqO2vQNTBBAaFy5IBRxfDBQ7myXnt1\/ipbirPPwieBcVxM7rd7a\r\nKQG7smfV+4BeC8LrGDM7J9ZBdUhCZ6Gz6cyK2z1GPqj2kxx4PCVzZMqZJ7OT6miv\r\ns4r\/UJqS0iVFdbEXAO6C2RWAcacp\/+P0pDqwP+yimmzi7BuVd0LxnQX2KwV67rIR\r\nhC5XH+yJI07pM0VCPTEjCEcuXSR74XIW0hHY451t++XmFK7Z\/Oyaiu4ZLe1Hr3Lp\r\neu7c2XOYp152GuD9AO18l8y3AGKKeYAZemzAZMnUSmLiAdZbohxkaah5Ur2mpJKG\r\ni76TT1b8qYHWsZf\/aRcDD8kygJpk0Bz8hkd7uDHQHXyGagQiM5JDEmVcJlnB0ygC\r\nbogZR1CksZG+dXXnJRVJjokSXCeZ5hIlTag0gsNIFBAVmRmPdTN0DhrNs86KIudR\r\nrCSXJpU8QxQ8GyUmi7N0bHTuc2DckPR6MBoLI6ThhdRIbnLNTZqnFJlKUUmTqzz2\r\neugyhsIlE306kYZKEETBnIAb48SPGdTJi1iz52C9JWDpzUC3EQ2ftBcS4ZukqVL4\r\nlLZHSmdZF6Jf6tWlWV0irK1xZd3U2Dvi2F+bFLZsMLRnvZWh32yUZLIGExOjpXxO\r\nOhobWsfaUOljY7yJ+nQJiujEujxKROsf6\/YwAMlATXRbv4S4oxGg5+ueRlT9ryIq\r\n693SzYmiyurWcgKwhjeSLHzw6kX60v+3GuNez60aIbmBWiNZt4r\/BXBsy9Iyop7h\r\nK6oTRd0t17goTIIiFp5dm6VOglYCfGDYVqpFxtZD9Dp9UdsREcsBCd38TZZ5cdtQ\r\nUP4FUEsBAhQAFAAAAAgAbowjR8VNaNMeAwAA7AcAAA4AEQAAAAAAAAAgALaBAAAA\r\nAHY4Xzc4M0NfMTQubXhsU0QEAKAAAABVVAUAB69a6FVQSwUGAAAAAAEAAQBNAAAA\r\nwwMAAAAA"
},
"errcode": 0,
"errmsg": "",
"debug": ""
}
Корректный ответ на НЕ корректный запрос
{
"data": null,
"errcode": 3,
"errmsg": "Отчет не найден или не доступен для пользователя! '03f3351c-1daa-436b-976d-5d8ee169d702'",
"debug": ""
}