Rest API от чайника для чайников

Последние изменения: 20.01.2021

Выберите уточнение:

Ключевые тезисы:

1. REST API работает только если при работе с ТСД используется сервер Mobile SMARTS. При прямом подключении ТСД к компьютеру через кабель/крэдл или при обмене с учетной системой через папку использовать REST API не получится.

2. Функционал REST API в локальном и глобальном ядре полностью идентичен, т.е. код процедур и функций практически полностью совпадает. Поэтому, если требуются доработки, их нужно делать синхронно в 3 местах – глобальное ядро, локальное ядро УФ, локальное ядро ОФ.

3. Обмен данными между 1С и Mobile SMARTS реализован черезHTTP-запросы из 1С в MS, все запрашиваемые данные передаются в качествепараметров запроса в формате JSON (либо в заголовках, либо в теле запроса), а сервер Mobile SMARTS возвращает ответ в виде: кода состояния и тела ответа в формате JSON.

4. Коды состояния бывают в диапазоне от 100 до 500 и выше, их можно разделить на следующие группы:

5. URI – уникальный идентификатор ресурса, используется при каждом запросе. Фактически, это путь до базы вида «http(s)://[имя сервера]:[порт базы Mobile SMARTS]/api/v1».

6. В обработке для реализации REST API используются прикладные объекты 1С такие как: 

7. В базе Mobile SMARTS может быть включена авторизация, тогда для выполнения HTTP-запросов необходимо будет каждый раз авторизовываться, есть 2 варианта авторизации:

8. Для выполнения всех запросов используется единый метод REST_API_ВыполнитьМетод(), который подготавливает запрос к выполнению, в него передаются URI, имя метода, параметры метода и отправляемые данные. Далее, из этого метода вызывается вспомогательный метод «REST_API_ВыполнитьHTTPЗапрос()», которые устанавливает соединение с сервером MS, сериализует данные для отправки в JSON, выполняет запрос, получает ответ от сервера MS и десериализует его из JSON.

9. Всего при обмене данными между 1С и Mobile SMARTS используются 5 видов HTTP-запросов: GET, POST, PATCH, PUT и DELETE.

   • GET – используется для получения со стороны севера определенного ресурса (настройку Mobile SMARTS, документ, список документов Mobile SMARTS, метаданные базы Mobile SMARTS). Если вы производите этот запрос, сервер ищет информацию и отправляет ее вам назад. По сути, он производит операцию чтения на сервере. Дефолтный тип запросов.
   • POST – нужен для создания определенного ресурса на сервере. Сервер создает в базе данных новую сущность и оповещает вас, был ли процесс создания успешным. По сути, это операции создания настройки Mobile SMARTS, документа Mobile SMARTS, выгрузки справочников Mobile SMARTS.
   • PUT и PATCH – используются для обновления определенной информации на сервере, например, статуса документа Mobile SMARTS. В таком случае сервер просто изменяет информацию существующих сущностей в базе данных и оповещает об успехе выполнения операции.
   • DELETE – как и следует из названия, удаляет указанную сущность из базы (удаление настройки Mobile SMARTS, документа Mobile SMARTS, очистка справочника Mobile SMARTS) или сигнализирует об ошибке, если такой сущности в базе не было.

Функции для обмена данными и HTTP-методы, которые выполняются в следующих функциях:

Примеры запросов и ответов, используемые при обмене между 1С и Mobile SMARTS:

REST_API_ПодключитьсяКБазеSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ПолучитьТокенSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/session?username=Логин&pa…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:

REST_API_ПолучитьОписаниеБазы

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/BaseInfo

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ПолучитьЗначениеНастройкиБазыSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/CustomSettings('ИмяИнтегр…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ЗаполнитьНастройкиSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/CustomSettings?$filter=name eq ‘ИспользоватьШаблоныВесовогоТовара’ or name eq ‘ПрефиксКодаВесовогоТовара’ or name eq ‘ДлинаКодаВесовогоТовара’ or name eq ‘ЧислоЗнаковПослеЗапятойВесТовара’ or name eq ‘ПрефиксВключенВКодВесовогоТовара’ or name eq ‘РазмерПорцииНоменклатуры’ or name eq ‘ВыгружатьНоменклатуруДокументаПередВыгрузкойДокумента’ or name eq ‘УстановитьПоискПоНаименованиюИАртикулу’ or name eq ‘ВыгружатьНоменклатуруСразу’ or name eq ‘ВыгружатьКонтрагентовСразу’

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ЗаписатьНастройкиSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/CustomSettings

Заголовки:   

Content-Type: application/json

Тело запроса:

	 {
"value": true,
"name": "РаботаБезАлкоголя"
}
HTTP-метод:
    POST
Код состояния: 
    200
Ответ сервера:   

REST_API_УдалитьНастройкиSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/CustomSettings('Настройки…

Заголовки:   

Content-Type: application/json

Тело запроса:

	 нет
HTTP-метод:
    DELETE
Код состояния: 
    204
Ответ сервера:
    нет

REST_API_ВыгрузитьТаблицуНаСерверSMARTS

Будут выполнены 3 запроса: начать выгрузку, выгрузка, завершить выгрузку (или прервать выгрузку, в случае ошибки), пример дан для выгрузки номенклатуры. В случае выгрузки ячеек или дополнительных таблиц будут изменяться только наименования методов (см. таблицу выше), все остальное выполняется по тому же алгоритму

Запрос 1 — Начать выгрузку

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Products/BeginUploadProducts

Заголовки:   

Content-Type: application/json

Тело запроса:

	 {
"lschema": [
"Product.Name",
"Product.Barcode",
"Product.ЭтоГруппа",
"Product.Marking",
"Product.Весовой",
"Product.Маркировка",
"Packing.Barcode",
"Packing.ИмяХарактеристики",
"Packing.Name",
"Packing.UnitsQuantity",
"Product.Алко",
"Packing.АлкоКод",
"Packing.АлкоОбъем",
"Packing.АлкоКрепость",
"Product.АлкоМарк",
"Packing.АлкоПроизводитель",
"Packing.АлкоПроизвИНН",
"Packing.АлкоПроизвКПП",
"Packing.ТНВЭД",
"Packing.Бренд",
"Packing.Верх",
"Packing.Вид",
"Packing.Импортер",
"Packing.Размер",
"Packing.ИНН",
"Packing.ИсходныйGTIN",
"Packing.Низ",
"Packing.Подкладка",
"Packing.Производитель",
"Packing.СтранаПроизводства",
"Packing.Цвет",
"Packing.price",
"Packing.qty",
"Product.ПоХарактеристикам",
"Product.ПоСериям",
"Product.ПоСН",
"Product.Id",
"Product.BasePackingId",
"Packing.ИдХарактеристики",
"Packing.Id",
"Packing.ИдЕдиницыИзмерения",
"Product.КлючХарактеристик",
"Product.КлючСерий",
"Packing.ИдСерии"
],
"rewriteProductsBook": true,
"useFullTextSearch": true
}
HTTP-метод:
    POST
Код состояния: 
    204
Ответ сервера:   
нет

Запрос 2 — Начать выгрузку

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Products/AddProductsToUpload

Заголовки:   

Content-Type: application/json

Тело запроса:

	 {
"flds": [
"Х-77890 Стинол Завод бытовой техники",
"000000094",
"false",
"Х-77890",
"false",
"",
"2000000058078",
"",
"шт",
"1",
"false",
"",
"0",
"0",
"false",
"",
"",
"",
"",
"Стинол",
"",
"",
"",
"",
"",
"2000000058078",
"",
"",
"Завод бытовой техники",
"",
"",
"0",
"8",
"false",
"false",
"false",
"cbcf4934-55bc-11d9-848a-00112f43529a",
"bd72d926-55bc-11d9-848a-00112f43529a",
"",
"bd72d926-55bc-11d9-848a-00112f43529a",
"bd72d926-55bc-11d9-848a-00112f43529a",
"",
"9c556d55-720f-11df-b436-0015e92f2802",
""
]
}
HTTP-метод:
    POST
Код состояния: 
    204
Ответ сервера:   
нет

Запрос 3 — Завершить выгрузку / прервать выгрузку

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Products/EndUploadProducts (для завершения выгрузки)

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Products/ResetUploadProducts (для прерывания выгрузки)

Заголовки:   

Content-Type: application/json

Тело запроса:

	 нет
HTTP-метод:
    POST
Код состояния: 
    204
Ответ сервера:   
нет

REST_API_ОчиститьТаблицуНаСервереSMARTS

Аналогично процессу выгрузки, только без запроса 2, т.е., фактически, не выгружаем в таблицу никаких данных:

REST_API_ПолучитьМетаданныеДокументовMS – состоит из 7 запросов

Запрос1 — Получение списка типов документов

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/DocTypes?$expand=tables

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

Запрос 2 — Получение метаданных и реквизитов шапки документа на примере документа «Агрегация» 

Строка запроса:    

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/DocTypes('Agregaciya&…

Заголовки:    

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния:
    200
Ответ сервера:    

Запрос 3 — Получение метаданных и реквизитов табличной части документа на примере документа «Агрегация»

Строка запроса:    

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/DocTypes('Agregaciya&…

Заголовки:    

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния:
    200
Ответ сервера:    

Запрос 4 — Получение списка доп.таблиц, которые не определены в метаданных документа, но существуют у самого экземпляра документа на примере документа «Агрегация»

Строка запроса:    

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/DocTypes('Agregaciya&…

Заголовки:    

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния:
    200
Ответ сервера:    

Запрос 5 — Получение списка дополнительных таблиц

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/TablesInfo

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

Запрос 6 -— Получение списка пользователей — «Users»

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Users

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

Запрос 7 — Получение списка устройств — «Devices»

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Devices

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ПолучитьСписокДокументовНаСервереSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs?$expand=declaredItems,curren…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ПолучитьДанныеДокументаНаСервереSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs/PrihodNaSklad('7e38b…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    GET
Код состояния: 
    200
Ответ сервера:   

REST_API_ЗаписатьДокументВБазуSMARTS

Запрос 1 — Выгрузка шапки документа

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs

Заголовки:   

Content-Type: application/json

Тело запроса:

	     {
"id": "7e38bff7-8faf-11ea-a40c-00155d03e00e",
"warehouseId": "1",
"ИдКонтрагента": "cbcf497b-55bc-11d9-848a-00112f43529a",
"ИдСклада1С": "03ce4b6f-3ff7-11e0-af05-0015e9b8c48d",
"ИмяСклада": "Продуктовая база",
"ИмяКонтрагента": "База "Продукты"",
"DistributeByBarcode": true,
"barcode": "167777389647035791856893807099027644430",
"РежимУпаковок": "БезУпаковок",
"Name": "Приобретение товаров и услуг ТД00-000026 от 06.05.2020 18:37:37",
"documentTypeName": "ПриходНаСклад",
"НастройкаБизнесПроцесса": "BPe8d6ec5a-7a78-41ba-8b01-820f78b31cdb",
"ИмяБП": "Приобретение товаров и услуг (проверка документа на ТСД)",
"КонтрольКолва": true
}
HTTP-метод:
    POST
Код состояния: 
    201
Ответ сервера:

Запрос 2 —Выгрузка табличных частей документа, например, declaredItems

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs('7e38bff7-8faf-11ea-…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     {
"value": [
{
"packingId": "bd72d8fb-55bc-11d9-848a-00112f43529a",
"productId": "e8a71fa5-55bc-11d9-848a-00112f43529a",
"ИдЕдиницыИзмерения": "bd72d8fb-55bc-11d9-848a-00112f43529a",
"Цена": 41,
"declaredQuantity": 5
}
]
}
HTTP-метод:
    POST
Код состояния: 
    200
Ответ сервера:
    нет

Запрос 3 — Принудительное сохранение документа, когда все строки уже загружены

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs('7e38bff7-8faf-11ea-…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    POST
Код состояния: 
    204
Ответ сервера:
    нет

REST_API_УдалитьДокументНаСервереSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs('7e38bff7-8faf-11ea-…

Заголовки:   

Content-Type: application/json

Тело запроса:

	     нет
HTTP-метод:
    DELETE
Код состояния: 
    204
Ответ сервера:   
    нет

REST_API_УстановитьСтатусДокументаНаСервереSMARTS

Строка запроса:   

http://10.0.0.29:10501/e1fc20aa-ff42-47df-9e5b-a94ba38b8935/api/v1/Docs('7e38bff7-8faf-11ea-…

Заголовки:   

Content-Type: application/json

Тело запроса:

	 {
"Status": "ОшибкаЗаписи"
}
HTTP-метод:
    PATCH
Код состояния: 
    204
Ответ сервера:   
    нет