Методичка по организации обмена данными при самостоятельной интеграции с 1С
Возможные средства интеграции
При установке на ПК любой конфигурации Mobile SMARTS вы можете воспользоваться одним из четырех вариантов организации обмена данными между учетной системой пользователя и сервером платформы Mobile SMARTS.
Рассмотрим отличия данных вариантов обмена и принципов их работы более подробно.
Обмен с базой данных «1С: Предприятия» и через собственную интеграцию на базе OLE/COM
Эти два варианта схожи по своей сути, т.к. для организации обмена данными между учетной системой пользователя и Mobile SMARTS применяются две специальные COM-компоненты. Установка и регистрация компонент выполняется автоматически при установке Mobile SMARTS из дистрибутива. В первом случае это COM-компонента, предназначена специально для работы с «1С:Предприятием» и некоторыми другими конфигурациями продуктов 1С (в зависимости от продукта). Во втором случае это неспециализированная универсальная компонента, которая может быть использована с любой учетной системой. Подробнее об этом можно узнать здесь.
В обоих случаях обращение к внешней системе происходит следующим образом:
Обмен через Excel/ CSV файлы
Помимо разнообразных вариантов интеграции с учётными системами, платформа Mobile SMARTS содержит в себе инструменты для интеграции на файлах CSV и Excel.
После установки платформы и развёртывания базы данных Mobile SMARTS становятся доступны следующие варианты обмена в формате CSV и Excel:
-
-
использование специального Excel/CSV коннектора.
В обоих случаях обмен происходит следующим образом:
- Создаются файлы-шаблоны, содержащие заголовки полей, по которым будут разбираться файлы, содержащие данные. Эти файлы должны иметь такой же формат, в котором предполагается обмен.
- В специальную папку обмена (по умолчанию «На терминал») помещаются файлы формата Excel или CSV, который содержат в себе номенклатуру, документы, таблицы и т. п. При этом структура этих файлов должна соответствовать созданным ранее шаблонам.
- Производится синхронизация с мобильным устройством или базой данных Mobile SMARTS (в зависимости от режима работы базы). При этом на устройство или сервер выгружается номенклатура и документы из папки «На терминал», а обратно загружаются обработанные документы.
- Обработанные документы при загрузке тоже разбираются по соответствующим файлам-шаблонам и конвертируются в формат Excel или CSV.
Подробнее о данном типе обмена можно узнать здесь.
Обмен данными через REST API
API (Application Programming Interface) — интерфейс для программирования приложений, позволяет удаленно обращаться к функциям приложения и выполнять какие-либо действия в нем. Чаще всего используется для получения данных для мобильных приложений, интернет порталов и интеграции с внешними системами (например, интернет-магазинами).
В качестве API в нашей системе используется REST API на основе протокола OData, в котором собраны наиболее популярные техники работы с данными через HTTP запросы (GET, POST, PUT, PATCH). Более подробную информацию по работе с OData (4.0) можно найти по ссылке.
Удобством использования REST является возможность проверки получаемых данных в обычном браузере, либо использованием стандартных приложений для выполнения HTTP запросов, например Advanced REST client (ARC).
В нашей системе также предусмотрена возможность просматривать структуру API и выполнять простые запросы, используя Swagger.
Подробнее о данном методе обмена вы можете узнать по ссылке.
Описание структуры документа и его основных переменных
В качестве примера будет рассматриваться документ «Приход на склад».
Документ «Приход на склад» используется в следующих бизнес-процессах:
- Приобретение товаров и услуг (проверка документа на ТСД)
- Приобретение товаров и услуг (на основании «Заказа поставщику»)
- Приходный ордер на товары (на основании «Заказа поставщику»)
- Приходный ордер на товары (на основании «Поступления товаров»)
- Приходный ордер на товары (проверка документа на ТСД)
Сам экземпляр документа «Приход на склад» физически представляет собой XML файл, хранящийся на сервере Mobile SMARTS, с данными в полях, определяемых конфигурацией сервера Mobile SMARTS для данного типа документа.
В разрезе обмена данными, в случае файлового обмена, данный документ представляет собой файл в формате XLS, CSV, XML и т. д., который загружается/выгружается из учетной системы и обратно через папки обмена, находящиеся по пути «…\XlsCsv» в корневой директории вашей базы. В общем случае для файлового обмена в XlsCsv предусмотрены следующие папки c указанным содержимым:
| Имя папки/ подпапки | Описание |
| На терминал | Содержит файлы Excel и CSV, предназначенные для отправки на терминал. |
| На терминал/Архив | Архив успешно конвертированных файлов Excel и CSV. Если файл «пропал», его можно найти здесь. |
| С терминала | Сюда складываются файлы с терминала после конвертации их в Excel или CSV по шаблон. |
| Templates | Папка с файлами шаблонов конвертации. Для «Магазин 15» или «Склад 15» готовые шаблоны добавляются в папку автоматически при установке. |
| Templates/Upload | Содержит шаблоны, по которым разбираются файлы для терминала. |
| Templates/Download | Содержит шаблоны, по которым формируются готовые файлы с терминала. Для получения докуме нтов в определенном виде нужно положить сюда файл шаблона с именем типа документа, для которого предназначен шаблон. |
В случае использования других вариантов обмена, например COM-коннектора, данные папки и шаблоны не используются, так как данные передаются непосредственно в учетную систему, а шаблоны обмена данными и участвующие в ней поля определены в обработке/конфигурации со стороны самой учетной системы.
Структура и содержание документа «Приход на склад»
В общем смысле любой документ Mobile SMARTS содержит две основные логические части — «шапку» и «табличную часть» документа.
Первая, так называемая «шапка документа», содержит поля с общей информацией о самом документе и правилах его обработки. С точки зрения конфигурации Mobile SMARTS и программирования в ней — это набор полей данных, принадлежащих объекту {Document} и доступных в конфигурации через сам объект {Document} (например {Document.Name} и т. п.).
Вторая, «табличная» часть документа, содержит данные о самих товарах — декларативную (плановую) часть {Document.DeclaredItems} и текущую (фактическую) часть {Document.CurrentItems}, которые с точки зрения конфигурации и программирования, являются коллекцией специального типа данных для описания товаров — DocumentItemCollection и тоже принадлежат конкретному документу. Также табличная часть может содержать дополнительные произвольные табличные данные типа RowCollection и/или вычисляемые поля — это могут быть таблицы характеристик, остатков или серий товара, вычислимые поля для отображения в списках и т. п.
Документ «Приход на склад» с точки зрения обмена данными
Обратите внимание, что при обмене данными между учётной системой и Mobile SMARTS используются далеко не все поля, которые существуют у данного типа документа в конфигурации Mobile SMARTS.
При этом в табличной части шапки документа типа «Приход на склад» при выгрузке из учетной системы присутствуют следующие поля документа:
| Название поля | Расшифровка | Тип данных |
{Name} | Название документа в учётной системе. | String |
{Barcode} | Номер/Штрихкод документа | String |
{ВыдаватьАвтоматически} | Автоматическое назначение документа | Boolean |
{ПоЯчейкам} | Работа по ячейкам | Boolean |
{ИсполняемыйНаСервере} | Коллективная работа с документом на сервере | Boolean |
{КонтрольКолва} | Контроль планового количества товара | Boolean |
{КонтрольЯчеек} | Контроль ячеек | Boolean |
{РежимУпаковок} | Режим упаковок («коробки», «палеты», «коробки или палеты») | String |
При выгрузке в обратном направлении (из Mobile SMARTS в учетную систему) набор полей шапки меняется.
| Название поля | Расшифровка | Тип данных |
{Name} | Название документа в учётной системе. | String |
{UserName} | Имя пользователя, завершившего документ | String |
{DeviceId} | Идентификационный номер устройства, на котором был завершён документ | String |
{DeviceIP} | IPv4/IPv6 адрес устройства на котором был завершён документ | String |
Количество существующих и используемых в конфигурации полей намного больше, чем участвующих в обмене с учетной системой. Они нужны для обеспечения работы внутренней логики конфигурации Mobile SMARTS и их набор от конфигурации к конфигурации разнится.
Во случае выгрузки из учетной системы на сервер 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 |
Также в конфигурации в документе «Приход на склад» присутствуют некоторые поля, не используемые при обмене, но необходимые для обеспечения работы внутренней логики конфигурации.