OMOBUS slave data

В данном проекте описываются механизмы интеграции и структуры входящих/исходящих потоков данных, передаваемых между сервером OMOBUS и источником данных, в качестве которого выступает ERP (Корпоративная информационная система - КИС) дистрибьютора.

Описание процедуры обмена данными через web-службу OMOBUS

Обмен данными между КИС дистрибьютора и системой OMOBUS осуществляется по протоколу HTTPS через специализированную web-службу OMOBUS в формате JSON. Адрес web-службы для обмена данными данных можно получить, обратившись в службу технической поддержки OMOBUS.

ВНИМАНИЕ! Обмен данными выполняется только в кодировке UTF-8 без BOM.

Описание web-службы загрузки справочных данных

Web-служба загрузки справочных данных (/data) принимает следующие команды:

• POST - загрузка справочных данных;
• GET - получение ранее загруженных справочных данных;
• DELETE — удаление ранее загруженных справочных данных.

Параметры запроса можно передавать либо в URI, либо в теле HTTP запроса. Параметры, указанные в теле HTTP запроса, имеют более высокий уровень приоритета. Необходимо указание двух параметров:

• tid (в URI) или X-Tid (в теле HTTP сообщения) - Token ID (можно получить, обратившись в службу технической поддержки OMOBUS);
• (опционально) ref (в URI) или X-Ref (в теле HTTP сообщения) - название одного или нескольких потоков справочных данных, перечисленных через запятую (см. описание потоков ниже); используется только для команд GET и DELETE.

Пример загрузки справочника warehouses (параметры передаются в теле HTTP запроса):

$ curl --verbose --request POST -H "Content-Type: application/json" -H "X-TID: 1" --data "@./warehouses.json" https://zdev.omobus.net/bridge/data

или то-же самое, но через параметры в URI:

$ curl --verbose --request POST -H "Content-Type: application/json" --data "@./warehouses.json" https://zdev.omobus.net/bridge/data?tid=1

Пример загрузки нескольких справочников за один запрос (параметры передаются в теле HTTP запроса):

$ curl --verbose --request POST -H "Content-Type: application/json" -H "X-TID: 1" --data "@./all.json" https://zdev.omobus.net/bridge/data

Пример получения данных ранее загруженных справочников warehouses и warech_stocks:

$ curl --verbose https://zdev.omobus.net/bridge/data?tid=1\&ref=warehouses,wareh_stocks

В случае успеха возвращается ответ с кодом 201 или 200. Данные принимаются только в кодировке UTF-8 без BOM.

Описание web-службы загрузки документов

Web-служба выгрузки сформированных на мобильных устройствах документов (/docs) принимает следующие команды:

• GET - получение документов или справочных данных, выгружаемых из системы OMOBUS.

Параметры запроса можно передавать либо в URI либо в теле HTTP запроса. Параметры указанные в теле HTTP имеют более высокий уровень приоритета. Необходимо указание следующих параметров:

• tid (в URI) или X-Tid (в теле HTTP сообщения) - Token ID (можно получить, обратившись в службу технической поддержки OMOBUS).
• (опционально) ref (в URI) или X-Ref (в теле HTTP сообщения) - Название одного или нескольких потоков документов и/или справочных данных, перечисленных через запятую (см. описание потоков ниже).
• (опционально) strip (в URI) или X-Strip (в теле HTTP сообщения) - Удалить пустые реквизиты из возвращаемого набора данных. Возможны значения: yes или no. По-умолчанию, если реквизит не задан, данные параметр принимает значение, равное yes.
• (опционально) ttd (в URI) или X-TTD (в теле HTTP сообщения) - Список состояний документов, перечисляемых через запятую, которые будут выключены в возвращаемый набор данных. Разрешено использование следующих значений: delivered — документ доставлен до точки обмена, accepted — получено подтверждение получения документа. По-умолчанию, в том случае, если данный параметр не определен, возвращаемый набор данных будет включать только документы с состоянием delivered.

Порядок работы КИС в ходе приема документов состоит из следующих последовательно выполняемых запросов:

1. GET - получить список всех необработанных на текущий момент времени документов. Под необработанными считаются все документы, по которым не передана в систему OMOBUS информация о том, что на их основании созданы документы в КИС дистрибьютора. Данная информация передается в потоке erp_docs. Пример запроса:

   $ curl --verbose https://zdev.omobus.net/bridge/docs?tid=1&ref=orders
   

2. Сохранить документ(-ы) в КИС дистрибьютора.

3. POST - загрузить в систему OMOBUS информацию о созданных в КИС дистрибьютора документах (erp_docs и erp_products). Пример запроса:

   $ curl --verbose --request POST -H "Content-Type: application/json" -H "X-TID: 1" --data "@./erp_docs2.json" https://zdev.omobus.net/bridge/data
   

Периодичность повтора загрузки документов рекомендуется установить в интервале от 5 до 45 мин.

ВНИМАНИЕ! Список загружаемых документов может содержать документы, которые уже были загружены в КИС дистрибьютора. Принимающая сторона должна корректно обрабатывать такие ситуации.

В случае успеха возвращается ответ с кодом 200. Данные возвращаются только в кодировке UTF-8 без BOM.

Примеры реализации протокола обмена

Реализация процедуры обмена данными для 1С:Предприятие 8.3 (8.3.21.1393), Конфигурация Управление торговлей, редакция 11 (11.4.6.207) ссылка.

Типы данных

Допустимо использование следующих типов данных:

• address_t = VARCHAR(256) - Строка длиной 256 символов.
• bool_t = INT2 - Целое число размером 1 или 2 байта (может принимать значение 0 или 1).
• code_t = VARCHAR(24) - Строка длиной 24 символа.
• currency_t = NUMERIC(18,4) - Число с дробной частью. В качестве десятичного разделителя используется точка. Разделитель групп разрядов не используется.
• date_t = VARCHAR(10) - Строка длиной 10 символов, содержащая дату в формате ISO:8601.
• datetime_t = VARCHAR(19) - Строка длиной 19 символов, содержащая дату и время в формате ISO:8601 с пробелом в качестве разделителя даты и времени.
• descr_t = VARCHAR(256) - Строка длиной 256 символов.
• ean13s_t = EAN13 ARRAY - Строковое представление штрихкодов в формате EAN13. В качестве разделителя между элементами выступает символ ‘,’.
• int32_t = INT4 - Целое число размером 4 байта.
• note_t = VARCHAR(1024) - Строка длиной 256 символов.
• numeric_t = NUMERIC(16,4) - Число с дробной частью. В качестве десятичного разделителя используется точка. Разделитель групп разрядов не используется.
• uid_t = VARCHAR(48) - Строка длиной 48 символов.
• uids_t = VARCHAR(48) ARRAY - Строковое представление массива элементов типа uid_t. В качестве разделителя между элементами выступает символ ‘,’.

Входящие (относительно сервера OMOBUS) потоки данных

В потоках необходимо передавать только актуальные данные. Также должна обеспечиваться уникальность (неповторяемость) записей по первичному ключу (строки первичного ключа помечены PK). Обязательные поля отмечены значением M.

Все данные во входящих потоках формируются в кодах дистрибьютора. Преобразование кодов дистрибьютора в коды производителя осуществляется автоматически на стороне сервера OMOBUS.

ВНИМАНИЕ! Названия потоков регистрозависимые.

Требования к наличию потков данных:

• [mandatory] - поток данных должен передаваться обязательно;
• [recommended] - поток данных рекомендуется передавать.

accounts [mandatory]

Параметры клиента. В данном потоке в обязательном порядке указываются все клиенты, с которыми работают сотрудники дистрибьютора, перечисленные в потоке users.

В том случае, если реквизит code не проставлен, код клиента выставляется автоматически на стороне сервера OMOBUS™.

Список возможных значений метода оплаты (реквизит payment_method_id, поток payment_methods) определяется на стороне OMOBUS. По согласованию с дистрибьютором, данный список может быть расширен.

В реквизите wareh_ids определяется список ID складов (через ‘,’), с которых может осуществляться поставка продукции клиенту. Пустое значение означает, что поставка продукции осуществляется с любого склада дистрибутора.

В реквизите user_ids указывается список ID сотрудников (через ‘,’), которые работают с данным клиентом (ответственные сотрудники).

Для заблокированных клиентов (реквизит locked = 1) отключается возможность создания Заказа продукции.

account_prices

Персональные цены для клиента. Данный вид цен имеет наивысший приоритет по сравнению с ценами, заданными с помощью потоков group_prices и/или std_prices. Цена задается в базовой упаковке (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, шт.).

Область применения: С помощью данного потока, можно жестко привязать цены к конкретному клиенту. Как правило, данный вид цен целесообразно использовать в качестве уточняющей цены при определенных ценах, задаваемых в потоках group_prices и/или std_prices. Другими словами, каждый клиент может иметь свой список цен, для части или для всех продуктов, по одной на каждый продукт.

balances [recommended]

Балансы счетов клиентов (остатоки кредитного лимита).

blacklist

Заблокированные для заказа продукты. Указанные в данном потоке продукты будут показаны в документе Заказ продукции (при условии наличия цены), однако сотрудник не сможет их добавить в заказ.

debts [recommended]

Просроченная дебиторская задолженность (ПДЗ). Фактичесик ПДЗ это долг, не оплаченный во-время.

discount_promos

Скидочные промо-акции, используемые в документе Заказ продукции. В рамках данного потока должны передаваться только действующие в текущий момент скидочные промо-акции, и те, которые запланированы к действию в ближайшие 15 дней.

ВНИМАНИЕ! В случае возникновения коллизии, при которой на одну дату действует несколько скидочных промо-акций с пересекающимся набором продуктов из акционного ассортимента, выбор скидочной промо-акции будет происходить случайным образом.

Скидочная промо-акция действует в том случае, если в заказ добавлено минимально допустимое (реквизит items) количество продуктов из акционного ассортимента (реквизит prod_ids), при этом количество каждого добавленного продукта из акционного ассортимента должно быть не меньше значения, указанного в реквизите packs, а итоговая сумма документа (до применения скидки) не менее значения, указанного в реквизите amount.

В реквизитах items и packs разрешено указание только значений больше нуля.

Реквизит amount можно передавать пустым, в этом случае, скидочная промо-акция будет действовать на заказ любой суммы.

Реквизит applicability описывает область действия скидочной промо-акции. В случае указания пустого значения, скидочная промо-акция будет действовать на все продукты, указанные в реквизите covered_ids. В случае указания значения больше нуля, скидочная промо-акция будет действовать только на указанное количество продуктов из акционного ассортимента (реквизит prod_ids). Указание в реквизите applicability значений меньших или равных нулю не допускается.

В реквизите covered_ids содержится список продуктов, на которые будет действовать скидка. Пустое значение означает, что скидка будет действовать на любой продукт, добавленный в документ Заказ продукции.

Список доступного акционного ассортимента может динамически меняться в зависимости от доступности продуктов в конкретный момент времени.

В документе Заказ продукции скидочная промо-акция применяется по дате доставки продукции.

erp_docs [mandatory]

Документы, созданные в КИС на основании документов из OMOBUS. Необходимо выгружать документы, созданные на основании документов из OMOBUS, в течении последних 5 дней.

В реквизите status возможно указание следующих значений:

• 0 — введен в систему;
• 1 — проведен (закрыт);
• -1 — удален/отменен/аннулирован;
• 2 — отгружен клиенту;
• 3 — получен клиентом/доставлен клиенту.

erp_products [mandatory]

Детализация документов, созданных в КИС на основании документов из OMOBUS. Данный поток является детализацией потока erp_docs и должен содержать детализацию документов, перечисленных в erp_docs.

floating_prices

Периодические цены. Данный вид цен имеет наивысший приоритет по сравнению с ценами, заданными с помощью потоков account_prices, group_prices и/или std_prices. В рамках данного потока, должны передаваться только действующие в текущий момент периодические цены и цены, которые запланированы к действию в ближайшие 15 дней. Цена задается в базовой упаковке (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, шт.)

ВНИМАНИЕ! В случае возникновения коллизии, при которой на одну дату действует несколько акционных цен, выбор используемой цены происходит случайным образом.

В случае установки реквизита promo в 1, сотрудник информируется о том, что для данного продукта проводится акция с указанием периода ее проведения.

Область применения: С помощью данного потока можно определить цены периодического действия индивидуально для каждого клиента. При этом, необходимость использование данной цены определяется по дате доставки (что эквивалентно дате отгрузки) продукции, которая задается перед созданием документа «Заказ продукции». Данное правило можно проиллюстрировать следующим примером:

• в потоке floating_prices определена цена с 15 февраля по 20 февраля равная 10 руб.;
• обычная цена 15 руб.;
• если заказ делается 13 февраля на 13 февраля, показывается цена 15 руб.;
• если заказ делается 13 февраля на 15 февраля, показывается цена 10 руб.;
• если заказ делается 15 февраля на 21 февраля, показывается цена 15 руб.

group_prices [mandatory]

Групповые цены (ценовые условия). Привязка групповой цены к конкретной т/точке выполняется в потоке account_params. Приоритет цен, заданных с помощью данного потока выше чем у цен, задаваемых с помощью потока std_prices. Цена задается в базовой упаковке (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, шт.)

Область применения: Данный вид цен позволяет «привязывать» одни и те же групповые цены к разным т/точкам. Фактически, в потоке group_prices задается список «ценовых условий». Ссылка из account_params дает возможность разным клиентам иметь один и тот же набор ценовых условий. В пределе, каждый клиент может иметь свой набор ценовых условий, что эквивалентно механизму, описанному в потоке account_prices. Клиент не может иметь более 1 набора ценовых условий. Другими словами, каждый т/точка может иметь свой список цен для части или всех продуктов, по одной на каждый продукт. Один список цен может использоваться разными клиентами. Другими словами, все цены, имеющие одинаковый group_price_id, можно трактовать как отдельный прайс-лист. Ссылка же из account_params (для конкретного account_id) на такой group_price_id, реализует привязку клиента, с этим конкретным account_id, к прайс-листу, указанному group_price_id.

mutuals [recommended]

Итоги взаиморасчетов.

mutuals_history [recommended]

История взаиморасчетов. Данные передаются за 45 дней.

mutuals_history_products

Детализация документов истории взаиморасчётов. Данный поток связан с mutual_history и должен содержать данные только по тем документам, которые имеются в mutual_history.

order_params

Дополнительные параметры заказа (отображаются на устройствах в виде флагов с двумя возможными состояниями: Да или Нет).

permitted_returns

Продукция, разрешенная к возврату с помощью документа Возврат продукции. Данный поток обязателен для заполнения в том случае, если планируется формирование Возвратов продукции. Цена и ограничение на максимальное разрешенное к возврату количество задается в базовой упаковке (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, шт.).

В случае, если реквизит locked выставленв 1, продукт показывается при создании возврата, но выбрать его нельзя.

products [mandatory]

Продукты.

В том случае, если реквизит code не проставлен, код продукта выставляется автоматически на стороне сервера OMOBUS™.

В реквизите pack_name указывается название базовой упаковки (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, ‘шт’.). В случае, если этот реквизит не задан, будет использовано значение по-умолчанию ‘pcs’.

restrictions

Ограничения, накладываемые на значение количества продукта в документе Заказ продукции. Все ограничения задаются в базовой упаковке (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, шт.).

shipments

Предписанный календарь доставок продукции клиенту. В том случае, если данный поток не заполнен, календарь доставок формируется автоматически на десять календарных дней.

std_prices [mandatory]

Базовая цена. Используется в том случае, если не заданы групповые group_prices или персональные цены account_prices. Цена задается в базовой упаковке (минимально допустимая упаковка продукта с кратностью упаковки равной 1, как правило, шт.)

Область применения: Данный вариант цены можно оценивать как цены по-умолчанию, которые используются в том случае, если не заданы персонализированные цены следующих уровней (с помощью потоков group_prices и/или account_prices).

symlinks [mandatory]

Таблица соответствия кодов производителя соответствующим кодам дистрибьютора.

Для обеспечения передачи в Заказе/Возврате продукции кодов сотрудников из КИС дистрибьютора, необходимо сформировать связку кодов сотрудников (реквизит obj_code = user) в системе OMOBUS и КИС дистрибьютора. Для управления даннои связкой, например, в «Карточке Сотрудника», можно обеспечить наличие текстового поля размером до 48 символов, в котором операторы могут в дальнейшем вводить № маршрута или уникальный идентификатор сотрудника в OMOBUS. Указанные реквизиты (dev_login, user_id) можно получить командой /docs?ref=users&tid=TokenID или через web-console OMOBUS.

Во всех остальных случаях, symlinks заполняется только если таблица соответствия кодов формируется и поддерживается на стороне дистрибьютора.

Реквизит obj_code может принимать одно из следующих значений: product, account, user.

users [mandatory]

Сотрудники. В данном потоке возвращаются только сотрудники, которые работают с OMOBUS в рамках текущего проекта.

wareh_stocks [mandatory]

Оперативные остатки продукции на складе (актуальные остатки на момент формирования потока). Остатки задаются в базовой упаковке (минимально допустимая упаковка продукта, как правило, шт.).

warehouses [mandatory]

Склады.

Исходящие (относительно сервера OMOBUS) потоки данных

Данные в потоке передаются за 5 последних календарных дней (если о порядке передачи данных в потоке не указана дополнительная информация) с момента их внесения в систему, или с момента последнего их изменения на сервере OMOBUS. Поэтому, принимающая сторона должна обеспечить гарантированный прием данных минимум 1 раз в 4 дня. В противном случае, часть данных будет утеряна. В свою очередь, сервер OMOBUS обновляет весь массив данных на общем ресурсе с шагом 150 секунд (через каждые 150 секунд после предыдущей выгрузки + время, затрачиваемое на подготовку данных).

Дата и время, если не сделано специального уточнения, представляют собой локальные дату и время фактической фиксации данных на устройстве (терминале сбора данных).

delivery_types

Типы доставки продукции.

order_types

Виды заказов.

orders

Документ Заказ продукции.

Значения, передаваемые в реквизите doc_no, уникальны только в рамках одной инсталляции приложения на одном мобильном устройстве. Уникальный номер заказа хранится в реквизите doc_id.

Поле user_id может содержать идентификатор пользователя в нотации производителя в том случае, если в OMOBUS не загружена таблица сваимосвязи между идентификаторами сотрудников в системе дистрибьютора и производителя (см. поток symlinks).

Поле dev_login содержит код устройства, на котором сформированы данные, в нотации OMOBUS.

Поле pack содержит размерность упаковки относительно базовой упаковки, которая определяется в штуках. Размерность базовой упаковки всегда равна 1.

Поле ttd может слдержать одно из следующих значений: delivered — документ доставлен до точки обмена, accepted — получено подтверждение получения документа.

payment_methods

Типы оплаты.

reclamation_types

Причины возврата продукции.

reclamations

Документ Возврат продукции.

Поле user_id может содержать идентификатор пользователя в нотации производителя в том случае, если в OMOBUS не загружена таблица сваимосвязи между идентификаторами сотрудников в системе дистрибьютора и производителя (см. поток symlinks).

Поле dev_login содержит код устройства, на котором сформированы данные, в нотации OMOBUS.

Поле ttd может слдержать одно из следующих значений: delivered — документ доставлен до точки обмена, accepted — получено подтверждение получения документа.

COPYRIGHT

Разрешено распространение и использование исходного кода с модификациями или без модификаций, с учетом ограничений, указанных в файле COPYRIGHT.