Руководство по настройке обмена данными при самостоятельной интеграции с 1С
Варианты интеграции
При установке любой конфигурации Mobile SMARTS на компьютер доступны четыре способа организации обмена информацией между учетной системой пользователя и сервером платформы Mobile SMARTS.
Далее рассмотрим различия между этими вариантами и принципы их функционирования.
Обмен с базой данных «1С: Предприятия» и собственная интеграция через OLE/COM
Данные два метода во многом схожи, так как в обоих случаях для взаимодействия между учетной системой и Mobile SMARTS применяются специальные COM-компоненты. Их установка и регистрация происходит автоматически при инсталляции Mobile SMARTS из дистрибутива. В первом случае используется компонент, адаптированная специально для «1С:Предприятия» и некоторых других продуктов 1С (в зависимости от конкретной конфигурации). Во втором варианте применяется универсальная COM-компонента, которая может работать с любой учетной системой. Подробности доступны здесь.
В обоих случаях взаимодействие с внешней системой происходит следующим образом:
Обмен данными через файлы Excel/CSV
Кроме интеграции с учетными системами, платформа Mobile SMARTS включает инструменты для обмена данными посредством файлов CSV и Excel.
После установки платформы и настройки базы Mobile SMARTS становятся доступными следующие способы обмена через CSV и Excel:
-
утилиты для обмена Excel и CSV;
-
применение специального Excel/CSV коннектора.
Суть обмена в обоих случаях такова:
- Формируются файлы-шаблоны с заголовками полей, по которым производит ся разбор файлов с данными. Эти шаблоны должны соответствовать формату, который предполагается использовать.
- В папку обмена (по умолчанию «На терминал») помещаются файлы Excel или CSV с номенклатурой, документами, таблицами и прочим, при этом структура файлов должна совпадать с шаблонами.
- Выполняется синхронизация с мобильным устройством или базой Mobile SMARTS (зависит от режима работы базы). В процессе на устройство или сервер выгружается номенклатура и документы из папки «На терминал», а обратно загружаются обработанные документы.
- Обработанные документы при загрузке разбираются по шаблонам и конвертируются в Excel или CSV.
Дополнительную информацию об этом способе обмена можно получить здесь.
Обмен через REST API
API (Application Programming Interface) — программный интерфейс, позволяющий удаленно обращаться к функциям приложения и выполнять опре делённые операции. Наиболее часто применяется для получения данных мобильными приложениями, веб-порталами и интеграции с внешними сервисами (например, интернет-магазинами).
В нашей платформе используется REST API, основанный на протоколе OData, который охватывает основные методы работы с данными через HTTP-запросы (GET, POST, PUT, PATCH). Более подробная документация по OData (4.0) доступна по ссылке.
Преимущество REST API — возможность проверки данных напрямую в браузере или с помощью стандартных приложений для HTTP-запросов, таких как Advanced REST Client (ARC).
В системе предусмотрен инструмент для просмотра структуры API и выполнения простых запросов через Swagger.
Полную информацию о данном способе обмена можно найти по ссылке.
Структура документа и ключевые переменные
Для примера возьмем документ «Приход на склад».
Документ «Приход на склад» применяется в следующих процессах:
- Приемка товаров и услуг (контроль документа на ТСД)
- Приемка товаров и услуг на основе «Заказа поставщику»
- Приходный ордер на товары (по «Заказу поставщику»)
- Приходный ордер на товары (по «Поступлению товаров»)
- Приходный ордер на товары (контроль на ТСД)
Файл документа «Приход на склад» представляет собой XML-документ, хранящийся на сервере Mobile SMARTS с данными, определяемыми конфигурацией сервера для данного типа документа.
При файловом обмене документ представлен в виде XLS, CSV, XML и т. д., который загружается и выгружается между учетной системой и папками обмена, расположенными в директории «…\XlsCsv» базы Mobile SMARTS. Для обмена предусмотрены следующие папки с содержимым:
| Имя папки/ подпапки | Назначение |
| На терминал | Файлы Excel и CSV для отправки на терминал |
| На терминал/Архив | Архив успешно обработанных файлов Excel и CSV. Если файл исчез, ищите здесь |
| С терминала | Файлы, полученные с терминала и конвертированные в Excel или CSV по шаблону |
| Templates | Папка с шаблонами конвертации. Для «Магазин 15» и «Склад 15» шаблоны добавляются автоматически при установке |
| Templates/Upload | Шаблоны для разбора файлов, предназначенных для терминала |
| Templates/Download | Шаблоны для формирования файлов, выгружаемых с терминала. Для получения документов в нужном формате сюда помещается файл-шаблон с именем типа документа |
При использовании других способов обмена (например, COM-коннектор) данные папки и шаблоны не применяются, поскольку обмен происходит напрямую с учетной системой, а структура и поля определяются на стороне самой системы.
Структура документа «Приход на склад»
Документ Mobile SMARTS состоит из двух основных частей: шапки и табличной части.
Шапка документа содержит общую информацию и настройки обработки документа. В конфигурации Mobile SMARTS это поля объекта {Document} (например, {Document.Name}).
Табличная часть содержит информацию о товарах: плановую (декларативную) часть {Document.DeclaredItems} и фактическую {Document.CurrentItems} — обе являются коллекциями типа DocumentItemCollection, связанных с документом. Также табличная часть может включать дополнительные таблицы (RowCollection) и вычисляемые поля, например, для характеристик, остатков, серий и т.п.
Особенности д окумента «Приход на склад» при обмене данными
Важно понимать, что при обмене между учетной системой и Mobile SMARTS используется лишь часть полей, доступных в конфигурации данного документа.
В шапке документа «Приход на склад» при выгрузке из учетной системы применяются следующие поля:
| Поле | Описание | Тип |
{Name} | Название документа в учетной системе | String |
{Barcode} | Штрихкод или номер документа | String |
{ВыдаватьАвтоматически} | Автоматическое назначение документа | Boolean |
{ПоЯчейкам} | Работа по ячейкам | Boolean |
{ИсполняемыйНаСервере} | Коллективная работа на сервере | Boolean |
{КонтрольКолва} | Контроль планового количества | Boolean |
{КонтрольЯчеек} | Контроль ячеек | Boolean |
{РежимУпаковок} | Режим упаковок («коробки», «палеты» и т.п.) | String |
При выгрузке из Mobile SMARTS в учетную систему состав полей шапки меняется:
| Поле | Описание | Тип |
{Name} | Название документа | String |
{UserName} | Имя пользователя, завершившего документ | String |
{DeviceId} | Идентификатор устройства, на котором завершён документ | String |
{DeviceIP} | IP-адрес устройства (IPv4/IPv6) | String |
В конфигурации Mobile SMARTS существует гораздо больше полей, чем используется при обмене. Они нужны для внутренней логики и могут отличаться в разных конфигурациях.
При выгрузке из учетной системы на сервер используется таблица плановой товарной части документа {Document.DeclaredItems}. При выгрузке завершенного документа из Mobile SMARTS обратно — объединённые данные из плановой и фактической частей {Document.CombinedItems}.
Ниже представлен список полей документа «Приход на склад», которые участвуют в обмене (на примере конфигурации «Склад 15»):
| Поле | Описание | Тип |
{НомерСтрокиДокумента} | Номер строки | Int32 |
{ШК} | Штрихкод | String |
{Product.Marking} | Артикул | String |
{Product.Name} | Наименование | String |
{ИмяХарактеристики} | Имя характеристики | String |
{ИдХарактеристики} | Идентификатор характеристики | String |
{ИдСерии} | Идентификатор серии | String |
{ИдЕдиницыИзмерения} | Идентификатор единицы измерения | String |
{ИмяСерии} | Название серии | String |
{ИмяНеизвестного} | Описание | String |
{DeclaredQuantity} | Заявленное количество | Decimal |
{CurrentQuantity} | Фактическое количество | Decimal |
{ЦенаПриемки} | Цена приемки | Decimal |
{АлкоНаим} | Название алкогольного напитка | String |
{АлкоОбъем} | Объем | Decimal |
{АлкоКрепость} | Крепость | Decimal |
{Производитель} | Производитель | String |
{ПроизвИНН} | ИНН производителя | String |
{ПроизвКПП} | КПП производителя | String |
{АлкоКод} | Код алкогольного напитка | String |
{АлкоПДФ} | Поле для хранения PDF417 (синоним поля {Марка}) | - |
{АлкоСН} | Серийный номер алкогольного напитка | String |
{СН} | Серийный номер | String |
{ДатаРозлива} | Дата розлива | DateTime |
{АлкоЕстьВФормах} | Наличие в «формах А» (описание производителя/импортера и диапазона серийных номеров) | Boolean |
{КодФормыА} | Код формы А | String |
{МаркаИСМП} | Марка ИСМП («01» + GTIN + «21» + СН) | String |
{Марка} | Контрольная марка товара | String |
{ИдКоробки} | Штрихкод коробки | String |
{SSCC} | Штрихкод палеты | String |
{FirstStorageId} | Ячейка хранения | String |
{МаркаБлока} | Марка блока сигарет | String |
{МаркаСтандарт} | Стандартная марка с управляющими кодами | String |
{GS1Марка} | Марка в формате GS1 | String |
{ПолнаяМаркаHRI} | Марка в формате HRI | String |
{ПолнаяМаркаBase64} | Марка в формате Base64 | String |
Некоторые поля, присутствующие в конфигурации документа, не используются при обмене, но необходимы для внутренней логики Mobile SMARTS.