Реализация REST API в обработке 1C

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

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 и выше, их можно разделить на следующие группы:

   • 200+: запрос успешен, в обработке используются:
   • 200 — запрос успешно выполнен;
   • 204 — запрос успешно выполнен, но ответ не содержит тела. Используется при выгрузке/очистке справочников Mobile SMARTS, удалении документа Mobile SMARTS, изменении статуса документа Mobile SMARTS.
   • 300+: запрос перенаправлен на другой маршрут;
   • 400+: ошибка на стороне клиента, в обработке используются:
   • 401 — не удалось авторизоваться на сервере Mobile SMARTS для выполнения запроса, например, из-за неверного логина/пароля или по причине того что истек срок действия токена, поэтому потребуется переавторизация.
   • 500+: ошибка на стороне сервера.

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

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

• HTTPСоединение — для установления соединения с сервером Mobile SMARTS перед отправкой запросов.
• HTTPЗапрос — для отправки запросов серверу Mobile SMARTS.
• HTTPОтвет — для получения ответов от сервера Mobile SMARTS.
• ЧтениеJSON и метод глобального контекста ПрочитатьJSON () — для преобразования ответа от сервера MS в структуру, массив, соответствие и т. д.
• ЗаписьJSON, ПараметрыЗаписиJSON и метод глобального контекста ЗаписатьJSON () — для формирования тела запроса из параметров в формат JSON.

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

   • BASIC авторизация — в этом случае при каждом HTTP-запросе нужно будет отправлять логин и пароль
   • Авторизация с использованием токена — при первом HTTP-запросе передаются логин и пароль, а сервер MS возвращается токен — уникальный идентификатор сессии (access token), который при последующих HTTP-запросах можно будет использовать вместо передачи логина и пароля. Срок действия токена (т.е. сессии) ограничен, поэтому для обновления токена при первом запросе сервер Mobile SMARTS дополнительно возвращает «токен обновления» (refresh token) — он нужен для получения нового токена после истечения срока действия текущего токена.

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
	 Ответ сервера:   
	     нет