Обмен данными
Общие положения¶
Обмен данными между Порталом маркетингового союза и внешними учётными системами осуществляется с помощью файлов.
Файлы передаются либо предоставляемым маркетинговым союзом почтовым клиентом, либо выкладываются на FTP-сервер.
Данные о товародвижении и маркетинговые инициативы передаются в терминах и кодах справочников товаров внешних учётных систем. Таблицы соответствия справочников внешних учётных систем со справочниками Портала находятся на Портале. Сопоставление справочника товаров происходит в три этапа:
-
Первый этап - при приёме данных автоматически по заранее созданным таблицам соответствия, далее по ЗШК и кодам поставщиков: ФК Пульс, Протек, СИА.
-
Второй этап - вручную сотрудниками маркетингового союза с помощью специального ПО.
-
Третий этап - верификация созданных соответствий с помощью специального ПО и ручное удаление неверных соответствий сотрудниками маркетингового союза.
Примечание
Обновление привязок кодов товаров во внешних учётных системах с кодами Портала в данных о товародвижении (партиях) происходит при приёме данных. После смены таблицы соответствий в настройках Портала для аптеки надо получить данные - сделать первичную выгрузку.
Чем отличается товар от номенклатуры¶
Номенклатура - наименьшая единица справочника товаров, с детализацией до конкретного предприятия-производителя и страны производства.
Товар – группировка номенклатур.
Примеры номенклатур:
- Аспирин-C табл. шип. стрип № 10 Bayer Bitterfeld GmbH ГЕРМАНИЯ
- Аспирин-C табл. шип. стрип № 10 Bayer AG ГЕРМАНИЯ
- Аспирин-C табл. шип. стрип № 10 Kern Pharma S.L. ИСПАНИЯ
Пример товара:
- Аспирин-C табл. шип. стрип № 10 импортные.
В учётной системе товародвижение может вестись в терминах номенклатур или в терминах товаров. Поскольку маркетинговые контракты заключаются с конкретными производителями, на Портале учёт ведётся в номенклатурах.
Как следствие, данные о товародвижении необходимо детализировать до номенклатуры. Передавать код номенклатуры обязательно - без него реализовать сопоставление миллионов партий товародвижения "на лету" невозможно. Если в аптеке справочник товаров не детализирован до номенклатуры, в качестве кода номенклатуры должна выгружаться "сцепка полей" код товара, код производителя. Если какое-то из этих полей не имеет кода – допускается использовать в качестве кода хэш наименования, при этом общая длина поля при этом не должна превышать 100 байт.
Допустимо также в качестве кода номенклатуры использовать ЗШК, об этом надо договориться на стадии получения первых файлов.
Примечание
Если, несмотря на это требование, вы присылаете нам не детализированный до номенклатуры ("схлопнутый") справочник товаров, то мы сами его "развернём", сцепив код товара с кодом производителя через символ $. Поэтому в отправляемых вам инициативах вы получите "свой" код товара, сцепленный с "вашим" кодом производителя.
Получение данных от систем товарного учёта (СТУ)¶
Общие сведения¶
Данные об остатках и движениях каждой партии товара имеют вид оборотной ведомости за каждый день.
Например, по партии №1 были движения:
- 01.01 – приход 3 шт.
- 01.01 – расход 1 шт.
- 10.01 – расход 1 шт.
- 20.01 – расход 1 шт.
В этом случае в файле должны быть:
- Партия №1 (в теге
<batch>) - данные о всех ее движениях (в теге
<distribution>) -
данные об остатках (в теге
<remnant>):- 01.01 – входящий 0, исходящий 2
- 10.01 – входящий 2, исходящий 1
- 20.01 – входящий 1, исходящий 0
Необходимо соблюсти основной принцип учета: [входящий остаток] + [приход] – [расход] = [исходящий остаток].
Отрицательные остатки недопустимы.
Данные о товародвижении одной аптеки передаются в одном файле, предпочтительное имя файла ГГГГММДДЧЧММСС_clientid_bat.xml, где client_id - код клиента (предоставляется маркетинговым союзом). Допускается в имени файла после _bat и перед точкой добавить символы, например, цифры, для того, чтобы дать возможность формировать файлы из нескольких процессов одновременно.
Разделителем между целой и дробной частями чисел является точка.
При выгрузке файла на FTP-сервер допускается сжатие файла по алгоритму ZIP. В этом случае в качестве расширения архива указывается .zip.
Если в качестве механизма доставки файла используется FTP-сервер, то файлы выкладываются на FTP-сервер в папку ESCAPE_IN и для устранения использования недогруженного файла применяется алгоритм переименования расширения: в FTP-каталог выгружается файл с именем формата ГГГГММДДЧЧММСС_clientid_bat, но с расширением .tmp (вместо .xml или .zip), которое по окончании выгрузки файла меняется на расширение .xml или .zip.
Загрузившиеся в базу данных Портала файлы хранятся в архиве 7 дней, потом удаляются.
Не загрузившиеся файлы помечаются как ошибочные и хранятся один месяц.
Последовательность действий по организации процесса получения данных от СТУ на Портал маркетингового союза¶
-
Вы формируете и даёте нам два файла: первичная выгрузка и регулярная выгрузка, удовлетворяющие спецификации. На этом этапе мы обмениваемся файлами, пользуясь "обычными" средствам коммуникации - e-mail, Скайп и тому подобные. Как правило, приходится сделать несколько итераций, пока ваши файлы начнут соответствовать спецификации.
-
Мы создаём на тестовом Портале тестовую аптеку для вас и присваиваем ей clientID, прописываем его в ваш файл первичной выгрузки и загружаем в систему.
-
После удачной загрузки формируем оборотную ведомость и передаём вам для сравнения с оборотной ведомостью, полученной непосредственно в СТУ.
-
Добиваемся отсутствия расхождения цифр в оборотной ведомости на тестовом Портале и СТУ.
-
Повторяем операции п.п. 2-4 с файлом регулярной выгрузки.
-
Мы регистрируем clientID для вашей реальной аптеки и отдаём вам его вместе логином и паролем почты, которые позволят вам настроить почтовый клиент маркетингового союза. Либо предоставляем вам логин и пароль на FTP-сервер маркетингового союза.
-
Вы отправляете файлы штатным образом и мы проверяем работу всей цепочки "формирование файлов и их выгрузка в СТУ → отправка файлов на Портал → появление данных на Портале".
-
Мы контролируем получение данных и сообщаем вам, если что-то не так.
Спецификация файлов с данными о товародвижении¶
Файлы с товародвижением бывают двух видов:
Первичная выгрузка - данные по аптеке выгружаются впервые.
Первичная выгрузка используется для учёта остатков, которые были в аптеке на начало стартового периода передачи данных из этой аптеки, а также для замены неверных остатков. Например, если аптека начинает выгружать данные начиная с 07.01, и в партии №1 на начало 07.01 был остаток 2, то его надо указать, чтобы не нарушить основной принцип [входящий остаток] + [приход] – [расход] = [исходящий остаток].
Поэтому в этом случае в файле первичной выгрузки по партии №1 должны быть:
- данные по собственно партии №1 (в теге
<batch>) -
данные о движениях партии за период с 07.01 (в теге
<distribution>):- 07.01 – приход 2 шт. (виртуальный приход – внедрение - на величину входящего остатка)
- 10.01 – расход 1 шт.
- 20.01 – расход 1 шт.
-
данные об остатках (в теге
<remnant>):- 07.01 – входящий 0, исходящий 2
- 10.01 – входящий 2, исходящий 1
- 20.01 – входящий 1, исходящий 0
При этом если партия №2 появилась 07.01 или позже, то по ней никаких виртуальных движений не создается, так как на начало 07.01 по этой партии остаток был 0). Соответственно:
- в файле самый ранний входящий остаток по каждой из партий должен быть равен 0
- в файле не может быть записей о движениях/остатках ранее стартовой даты первички.
-
период дат выгрузки в файле не указывается.
Примечание
Перед загрузкой данных из файла первичной выгрузки в базе данных Портала удаляются все партии, движения и остатки по этой аптеке.
Состав данных и требования к файлу¶
-
Период дат от 01.01.2021 по текущую.
-
Данные по всем имеющимся остаткам товаров, которые больше нуля на дату начала периода плюс движение и остатки, соответствующие движению (входящий/исходящий остаток за каждый день движения), за весь период. По партии в аптеке за одну дату указывается только одна запись об остатках, независимо от количества движений в этот день.
-
Входящий остаток на дату начала периода должен быть равен нулю. На величину реального входящего остатка на дату начала периода, если он больше нуля, нужно сформировать "виртуальную" строку документа типа "Ввод остатков" (тип документа 9). Рекомендуется в качестве значения distribution_id указать значение map_batch_id из таблицы партий товара. В качестве doc_number можно указать "Первичная выгрузка". doc_date при этом равна дате остатка (время 00:00:00).
Примечание
Значения distribution_id и map_batch_id уникальны в пределах всего товародвижения аптеки. Если в файле содержатся данные от нескольких аптек, требуется обеспечить уникальность или сформировать несколько файлов для каждой аптеки.
Внимание!
Значение distribution_id - это уникальный идентфикатор движения, map_batch_id - уникальный идентификатор партии. Эти иденификаторы изменены быть не могут.
-
В заголовках файлов даты начала и окончания периода не указываются.
-
Должна быть возможность выполнения повторно первичной выгрузки вручную с указанием начальной даты периода. Конечной датой всегда является "текущая" дата.
Регулярная выгрузка¶
Первичная выгрузка состоялась, данные из аптек должны выгружать регулярно.
Регулярная выгрузка отличается от первичной:
-
Период дат - "конец интервала - текущая дата, а начало интервала - минус 93 дня, но не ранее наименьшей даты движения в первичной выгрузке, плюс 1 день" (связано с возможным редактированием движения и остатков в предыдущих днях в рамках бухгалтерской отчётности).
-
Перед загрузкой регулярной выгрузки удаляются движения и остатки только за указанный в файле (атрибуты datestart и dateend) период дат.
Примечание
Соответствия номенклатур внешней СТУ номенклатурам портала (таблицы соответствий) в данных о товародвижении не изменяются! Если возникла необходимость поменять таблицу соответствий для аптеки - для её "применения" необходима первичная выгрузка.
-
В файле не должно быть записей о движениях и остатках вне указанного периода дат.
- Стартовая дата регулярной выгрузки должна быть больше стартовой даты первичной выгрузки – иначе при удалении движений/остатков удалятся и виртуальные приходы (внедрения), созданные первичной выгрузкой, и их остатки.
Например, если указан период с 08.01.2019, то в файле по партии №1 должно быть:
- данные по собственно партии №1 (в теге
<batch>) -
данные о движениях партии за период с 08.01.2019 (в теге
<distribution>):- 10.01.2019 – расход 1 шт.
- 20.01.2019 – расход 1 шт.
-
данные об остатках (в теге
<remnant>):- 10.01.2019 – входящий 2, исходящий 1
- 20.01.2019 – входящий 1, исходящий 0
Состав данных и требования к файлу¶
-
Период дат - "конец интервала - текущая дата, а начало интервала - минус 93 дня, но не ранее наименьшей даты движения в первичной выгрузке, плюс 1 день" - чтобы получить отредактированные "задним числом" данные.
-
Если в учётной системе нет данных за все предыдущие 93 дня - выгружаются за дни, что есть, с соответствующим указанием периода в заголовке файла.
-
Данные по движениям и соответствующим им остаткам (входящий и исходящий остаток за каждый день движения) должны быть только за указанный в заголовке период. Если в теле файла содержатся данные вне указанных в заголовке файла дат - файл считается ошибочным и не грузится.
-
Файл формируется и отправляется на Портал ежедневно.
-
Желательна возможность ручного формирования файла с выбором произвольной начальной даты периода (при этом конечной датой всегда является "текущая" дата) с обязательным указанием в заголовках файлов даты начала и окончания периода.
Логика загрузки регулярной выгрузки на Портал
-
Если в файле с данными даты периода не указаны, этот файл классифицируется как первичный и по этой аптеке удаляются все ранее загруженные данные.
-
Если в файле с данными даты периода указаны, файл классифицируется как регулярный, все ранее загруженные движения и остатки за указанный период удаляются, партии при этом не удаляются, и выполняется загрузка данных из файлов.
-
При отсутствии первичной выгрузки регулярная загружаться не будет, файл будет классифицирован как ошибочный.
Отличия версий спецификации¶
-
3-я версия: в партию добавлен признак комиссионного товара.
-
4-я версия: в партию добавлен массив nomenclature_codes и перенесёно в него значение
<map_nomenclature_code>(<map_nomenclature_code>из партии удалён). -
5-я версия: в товародвижение добавлены данные о кассире и признак перепродажи.
-
6-я версия: в товародвижение добавлены данные о фискальных признаках чека.
Описание файла с данными о товародвижении аптеки из учётной системы (6-я, актуальная версия)¶
Заголовок файла¶
<?xml version="1.0" encoding="UTF-8"?>
<map-actions client_id=Код_клиента> - код клиента предоставляется союзом.
<data_version>6</data_version> - версия формата данных. Инкрементируется при внесении изменений в формат данных.
Партия товара¶
<action type="batches" datestart="2017-04-01T00:00:00" dateend="2017-04-01T23:59:59" map_pharmacy_ids="1,10"> - datestart и dateend - даты периода выгрузки в формате ДатаВремя(2017-04-01T23:59:59). Для первичной выгрузки эти параметры не указываются. map_pharmacy_ids - список кодов аптек в справочнике подразделений учётной системы (через запятую), по которым содержит данные конкретный файл.
<batches>
<batch>
| Имя тега | Описание | Комментарий |
|---|---|---|
map_batch_id |
Идентификатор партии в учётной системе | Строка(100) |
map_pharmacy_id |
Код аптеки в справочнике подразделений учётной системы (подразделение-владелец базы) | Строка(100) |
map_pharmacy_name |
Наименование аптеки | Строка(500) |
nomenclature_id |
Код номенклатуры в справочнике ФармЭталон, используется только в ПО "М-Аптека плюс" | Строка(100) |
map_nomenclature_name |
Полное наименование номенклатуры в учётной системе | Строка(500) |
map_product_code |
Всегда пусто | Строка(100) |
map_product_name |
Всегда пусто | Строка(500) |
producer_id |
Код производителя номенклатуры в справочнике ФармЭталон (может не быть) | Строка(100) |
map_producer_code |
Код производителя номенклатуры в учётной системе (может не быть) | Строка(100) |
map_producer_name |
Полное наименование производителя в учётной системе (только если producer_id="", может не быть) | Строка(500) |
producer_country_id |
Код ФармЭталона страны производителя (может не быть) | Строка(100) |
map_producer_country_code |
Код страны производителя в учётной системе (может не быть) | Строка(100) |
map_producer_country_name |
Полное наименование страны производителя в учётной системе (только если producer_country_id="", может не быть) | Строка(500) |
map_supplier_code |
Код поставщика в учётной системе | Строка(100) |
map_supplier_tin |
ИНН поставщика в учетной системе | Строка(100) |
supplier_name |
Наименование поставщика | Строка(500) |
batch_doc_date |
Дата документа поставщика (местная). Время всегда 0 часов | ДатаВремя(2017-04-01T00:00:00) |
batch_doc_number |
№ документа поставщика | Строка(100) |
purchase_price_nds |
Цена закупочная с НДС | Число(10,2) |
purchase_nds |
%НДС закупочный | Целое число |
retail_price_nds |
Цена розничная с НДС | Число(10,2) |
retail_nds |
%НДС розничный | Целое число |
barcode |
Заводской штрих-код | Целое число |
sign_comission |
Признак комиссионного товара | Целое число, 0 - балансовый, 1 - комиссионный |
nomenclature_codes |
Массив кодов номенклатуры в разных справочниках... Указываются только не пустые коды | структура (описание см. ниже) |
internet_zakaz |
Признак оприходования товара от оператора дистанционной торговли (оприходование "не своего товара") | Указывается наименование конкретного оператора в виде доменного имени в нижнем регистре apteka.ru – товар Аптека.ру, zdravcity.ru – товар Здравсити, eapteka.ru – товар Еаптека (допускается указать internet.sale для любого из трёх перечисленных). |
</batch>
</batches>
</action>
Структура поля nomenclature_codes¶
<nomenclature_codes>
<code owner="Владелец_справочника_1">Код_в_справочнике</code>
...
<code owner="Владелец_справочника_N">Код_в_справочнике</code>
</nomenclature_codes>
Примечание
Если у номенклатуры несколько ЗШК, для их перечисления можно использовать <code owner> - указывать в качестве его значений barcode. Но при обработке будет использован только один, последний.
Значения атрибута owner ("Владелец_справочника")¶
-
map - учетная система, из которой выгружаются данные - ОБЯЗАТЕЛЬНОЕ!
-
puls - прайс-лист поставщика "Пульс".
-
sia - прайс-лист поставщика "СИА".
-
protek - прайс-лист поставщика "Протек".
-
rosta - прайс-лист поставщика "Роста".
Добавление иных владельцев справочника возможно по договоренности с маркетинговым союзом и не приводит к изменению версии данных.
Тип данных поля "Код_в_справочнике": Строка(100)
Пример заполнения:
<nomenclature_codes>
<code owner="map">100:20:135</code>
<code owner="puls">1025</code>
</nomenclature_codes>
Партия - неделимый идентификатор товара, отражающий полный набор свойств этого товара, как наименование, ЗШК, МНН, производитель и тому подобные, так и серия, поставщик, цены и тому подобные. Допускается дублирование значений этих свойств - может быть несколько партий товара с абсолютно одинаковыми значениями всех свойств. Не допускается у одной и той же партии одномоментно разные значения одних и тех же свойств. Один из примеров партии - строка приходного документа.
Коды номенклатур в прайс-листах поставщиков нужны в том случае, когда нет единого справочника - мы будем выполнять автопривязку товаров к нашим номенклатурам по данным, указанным в этих полях.
В качестве значения поля "Код номенклатуры в учетной системе" <code owner="map"> указывается код товара с детализацией до производителя и страны. То есть если в системе учёта код товара не отражает конкретного производителя и страну - при выгрузке данных в этом поле нужно указывать "сцепку" полей "код товара"_"код производителя"_"код страны".
Товародвижение Аптек¶
<action type="distributions" datestart="2017-04-01T00:00:00" dateend="2017-04-01T23:59:59" map_pharmacy_ids="1,10"> // datestart и dateend - даты периода выгрузки в формате ДатаВремя(2017-04-01T23:59:59). Для первичной выгрузки эти параметры не указываются. map_pharmacy_ids - список кодов аптек в справочнике подразделений учётной системы через запятую, по которым выполнена выгрузка.
<distributions>
<distribution>
| Имя тега | Описание | Комментарий |
|---|---|---|
map_pharmacy_id |
Код аптеки в справочнике подразделений учётной системы | Строка(100) |
distribution_id |
Уникальный № записи о движении в учётной системе | Строка(100) |
batch_id |
Идентификатор партии в учётной системе | Строка(100) |
doc_date |
Дата и время операции (местные в аптеке) | ДатаВремя (2017-04-01T23:59:59) |
doc_type |
Тип документа. Значения: 1- мелкооптовый отпуск; 2 – продажа через ККМ; 3 – приход товара от поставщика (закупка), 4 – возврат от покупателя, 5 – возврат поставщику, 6 – межскладская передача приход, 7 – межскладская передача расход, 8 – Списание, 9 – Ввод остатков. | Целое число |
doc_number |
№ документа. Для документов типа 1,3 - номер внешней накладной, для типа 2 – № Z-отчёта, для остальных - внутренний № | Строка(100) |
pos_number |
№ кассового аппарата (только для документов типа 2) | Строка(100) |
check_number |
№ чека (только для документов типа 2). Если известен № чека из кассы – указываем его, иначе указываем внутренний № чека. | Целое число |
check_unique_number |
Уникальный идентификатор чека (только для документов типа 2) | Строка(100) |
quantity |
Количество товара | Число(15,6) |
purchase_sum_nds |
Сумма в ценах закупочных с НДС | Число(10,2) |
retail_sum_nds |
Сумма в ценах розничных с НДС | Число(10,2) |
discount_sum |
Сумма всех скидок по строке. retail_sum_nds - discount_sum должно равняться сумме оплаты | Число(10,2) |
cashier_id |
Уникальный идентификатор продавца/кассира. Основные требования: в сети аптек идентификатор одного продавца должен быть един во всех аптеках и два разных продавца не могут иметь одинаковый идентификатор. | Строка(100) |
cashier_full_name |
Фамилия Имя Отчество продавца/кассира (в указанной последовательности) | Строка(100) |
cashier_tin |
ИНН продавца/кассира (необходим для модуля Расчёт зарплаты первостольника) | Строка(12) |
resale_sign |
Признак перепродажи, то есть продажи товара другим аптечным учреждениям или закупки товара у других аптечных учреждений. Имеет смысл для документов типа 1 и 3. | Целое число: 1 - перепродажа, 0 - нет |
fn_doc_number |
№ фискального документа | Строка(50) |
fn_doc_sign |
фискальный признак документа | Строка(50) |
fn_number |
№ фискального накопителя | Строка(50) |
fn_doc_date |
дата/время фискального документа | ДатаВремя (2017-04-01T23:59:59) |
internet_zakaz |
Признак движения товара от оператора дистанционной торговли либо забронированного с помощью агрегатора/справочной службы | Наименование оператора в виде доменного имени в нижнем регистре, apteka.ru – товар Аптека.ру, zdravcity.ru – товар Здравсити, eapteka.ru – товар Еаптека (допускается указать internet.sale для любого из трёх перечисленных). |
</distribution>
</distributions>
</action>
Остатки Аптек¶
<action type="remnants" datestart="2017-04-01T00:00:00" dateend="2017-04-01T23:59:59" map_pharmacy_ids="1,10"> - datestart и dateend - даты периода выгрузки в формате ДатаВремя(2017-04-01T23:59:59). Для первичной выгрузки эти параметры не указываются. map_pharmacy_ids - список кодов аптек в справочнике подразделений учётной системы (через запятую), по которым выполнена выгрузка.
<remnants>
<remnant>
| Имя тега | Описание | Комментарий |
|---|---|---|
map_pharmacy_id |
Код аптеки в справочнике подразделений учётной системы | Строка(100) |
batch_id |
Идентификатор партии в учётной системе | Строка(100) |
date |
Дата остатка (местная для аптеки). Время всегда 00:00:00 | ДатаВремя (2017-04-01T00:00:00) |
opening_balance |
Входящий остаток (количество) | Число(15,6) |
closing_balance |
Исходящий остаток (количество) | Число(15,6) |
input_purchasing_price_balance |
Входящий остаток в закупочных ценах с НДС | Число(10,2) |
output_purchasing_price_balance |
Исходящий остаток в закупочных ценах с НДС | Число(10,2) |
input_retail_price_balance |
Входящий остаток в розничных ценах с НДС | Число(10,2) |
output_retail_price_balance |
Исходящий остаток в розничных ценах с НДС | Число(10,2) |
</remnant>
</remnants>
</action>
</map-actions>
Скачать пример файла первичной выгрузки.
Скачать пример файла регулярной выгрузки.
Получение данных от Торговых площадок (ТП)¶
Обмен данными между Порталом маркетингового союза и ТП осуществляется с помощью файлов.
Файлы выкладываются на FTP-сервер в папку ESCAPE_IN.
Загрузившиеся в базу данных Портала файлы хранятся в архиве 7 дней, потом удаляются.
Не загрузившиеся файлы помечаются как ошибочные и хранятся один месяц.
Спецификация файлов с данными о закупках и заказах¶
Обязательные поля выделены звёздочкой (*).
Первая строка файла не импортируется, в ней желательно указать имена полей.
| *Клиент | *ИНН | *Аптека (адрес) | *Код аптеки (адреса) | *Код товара | *Наименование товара | Код производителя | Производитель товара | ЗШК | Код поставщика | Наименование поставщика (дистрибьютора) | *ИНН поставщика | *Тип документа (1 - заказ, 2-приходная накладная) | Номер документа | *Дата документа | *Кол-во | % НДС | Цена с НДС | Сумма с НДС | Код товара Протек | Код товара Пульс | Код товара СИА | Код товара Роста |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
CLIENT |
CL_INN |
CL_ADDRESS |
ADDRESS_ID |
GOOD_ID |
GOOD |
MAN_ID |
MANUF |
BARCODE |
SUP_ID |
SUPPLIER |
SUPP_INN |
DOC_TYPE |
ORDER_NUM |
ORDER_DATE |
QUANTITY |
NDS |
PRICE_NDS |
SUMM_NDS |
GOOD_CODE_PR |
GOOD_CODE_PU |
GOOD_CODE_SIA |
GOOD_CODE_ROSTA |
| ИП Аптека 01 | 123456789012 | г. Пример 01, ул. Пример 02, д.123 | 35689 | 256984 | АЛФЛУТОП р-р д/ин. (амп.) 10 мг/мл - 1мл N10 | 2569 | BIOTECHNOS SA | 125 | Авеста-Фармацевтика | 7709548382 | 2 | 20180201 | 2 | 1264.33 | 1264.33 | |||||||
| ИП Аптека 02 | 234567890123 | г. Пример 03, ул. Пример 04, д.456 | 38002 | 318710 | АСПИРИН КАРДИО табл. п.о. 0.3 N20 | 1574 | BAYER AG | 23 | Катрен | 5408130693 | 2 | 20180201 | 3 | 63.07 | 189.21 |
- Поля, "Код аптеки", "Код товара", "Код производителя", "Код поставщика" - коды в информационной системе Торговой площадки (не поставщика).
- Поля "Код товара Протек", "Код товара Пульс", "Код товара СИА" - коды товаров поставщиков.
- Формат файла - .CSV, кодировка Windows-1251, разделитель - знак табуляции (char 9).
- Имя файла: YYYYMMDD_Npp.csv (год, месяц, день, Npp - порядковый № выгрузки в течение дня).
- Дата в полях файла представляется в формате YYYYMMDD (год, месяц, день).
- В числовых полях не должно быть служебных символов ("пробелов").
-
Разделитель целой и дробной части в числовых - точка.
Примечание
При загрузке данных в БД в файле ищется строка с наиболее ранней датой и все данные, начиная с этой даты для конкретной аптеки заменяются на данные из файла. Если в полученном файле будут отсутствовать данные, которые были в предыдущем файле, но будут строки с датами, более ранними чем в предыдущем файле - часть данных будет утрачена.
Последовательность действий по организации процесса получения данных от ТП на Портал маркетингового союза¶
- Мы создадим на сервере FTP нужные каталоги для вас и выдадим логины/пароли.
- Вы выгрузите в указанный FTP-каталог в папку ESCAPE_IN файл с первичной выгрузкой (данные за период с 01.01.2017 г.) с именем формата YYYYMMDD_Npp (год, месяц, день, Npp - порядковый № выгрузки в течение дня), но с расширением .tmp (вместо .CSV).
- Допускается сжатие файла по алгоритму .zip. В этом случае в качестве расширения архива указывается .zip (внутри архива файл .CSV). По окончании выгрузки его надо переименовывать в файл с расширением .CSV (вместо .tmp).
- Все Регулярные выгрузки (данные за 14 предыдущих дней) вы выкладываете ежедневно с 20:00 до 08:00.
- Все файлы (и .csv, и .zip) должны выгружаться с расширением .tmp. По окончании выгрузки их надо переименовывать в файл с расширением .CSV либо .zip (вместо .tmp).
Получение данных об остатках и ценах без товародвижения¶
Данные предназначены для справочной службы маркетингового союза.
Обмен данными между Порталом маркетингового союза и аптеками осуществляется с помощью файлов.
Файлы выкладываются на FTP-сервер маркетингового союза.
Спецификация файлов с данными об остатках¶
Поскольку СТУ используют партионный учет и хранят остатки в разрезе партий, остатки необходимо передавать с детализацией до партии.
Остатки должны выгружаться в файл с постоянным именем stock_NNN.xml, NNN – код аптеки.
На стороне аптеки должно быть два режима выгрузки: полные остатки, и изменившиеся с момента предыдущей выгрузки (выгружаются остатки только по тем партиям, по которым было движение).
Пакет с полными остатками желательно выгружать раз в сутки, изменения - не реже раза в час. Структура файла одинакова как для полных остатков, так и для изменений.
Заголовок:
- Дата/время выгрузки STOCK_TIME ("21.03.2010 10:59:33").
- Признак, что это полные остатки ALL_STOCK (1 или 0).
Позиция товарных остатков:
- IID – Код партии товара.
- MED_ID – Код товара в справочнике аптеки.
- MED_NAME – Название товара.
- VENDOR_NAME – Фирма–производитель.
- COUNTRY_NAME – Страна.
- KIND_NAME – (Всегда пусто).
- VENDORBARCODE – Штрих-код производителя.
- RPRICE – Цена розничная с НДС.
- DPRICE – (Всегда пусто).
- QTTY – Количество в шт.
- PREPAY_ENABLE – (Всегда пусто).
- INTER_ID – (Всегда пусто).
- INTER_NAME – (Всегда пусто).
- PHARM_ID – (Всегда пусто).
- PHARM_NAME – (Всегда пусто).
- TK_ID – (Всегда пусто).
- TK_NAME –(Всегда пусто).
- TKR_ID – (Всегда пусто).
- TKR_NAME – (Всегда пусто).
- IS_NARC – (Всегда пусто).
- ANALOG_ID – (Всегда пусто).
- VALID_DATE – Срок годности.
Скачать пример файла.
Последовательность действий по организации процесса получения данных об остатках¶
-
Менеджер маркетингового союза должен создать аптеку (в 1С) и установить для неё признак "Остатки".
-
После обмена данными 1С с порталом аптека появится в справочнике аптек на портале с указанием директории на FTP-сервере для выгрузки остатков (доступно для просмотра в карточке аптеки, строка Адрес FTP остатков). Логин для доступа к директории - ID аптеки на портале, пароль по умолчанию galaxy, при необходимости его можно поменять в режиме редактирования строки Адрес FTP остатков аптеки.
-
Информацию о директории, логин и пароль необходимо передать техническому персоналу, облуживающему учётную систему аптеки для настройки выгрузки.
Отправка файлов с параметрами маркетинговых инициатив¶
Файлы с информацией о маркетинговых инициативах отправляются тем же способом, что и получаются данные о товародвижении - почтовый клиент или FTP-сервер маркетингового союза. Файлы имеют единую спецификацию для всех типов внешних учётных систем.
Формирование имени файла¶
Текущие дата и время в формате yyyyMMddHHmmss (год, месяц, день, час, минуты, секунды); код клиента (clentID); идентификатор выгружаемой инициативы; тип инициативы.
Пример
Например, 20180426135530_292_1164_DISCOUNTCOMPENSATION.xml - файл, сформированный 26 апреля 2018 года в 13:55:30 для клиента с clientID = 292 и инициативой, имеющей ID = 1164 и тип "Компенсация скидки".
ClentID и идентификатор выгружаемой инициативы применяются исключительно для обеспечения уникальности имени файла, не следует их использовать при обработке, вся необходимая информация - в теле файла.
Схема и документация¶
Пример отправляемого файла с инициативой (скачать)¶
Описание нескольких специфичных xml-поддеревьев¶
Заголовок файла:
<?xml version="1.0" encoding="UTF-8"?>
<fe-actions client_id=Код_клиента>
<data_version>6</data_version> - инкрементировать при обратно несовместимых изменениях.
Маркетинговые инициативы¶
<action type="marketing_actions">
<marketing_actions>
<marketing_action>
| Имя тега | Описание | Комментарий |
|---|---|---|
marketing_action_id |
Идентификатор инициативы | Строка(100) |
marketing_action_name |
Наименование инициативы | Строка(500) |
marketing_action_type |
Тип инициативы | Строка(500) |
date_start |
Дата начала | Дата |
date_end |
Дата окончания - если дата не задана (инициатива бессрочная), тег date_end будет пропущен. | Дата |
state |
Состояние (0 - действующая, 1 - закрыта) | Целое число |
products |
Список промотоваров | Структура описана ниже |
suppliers |
Список поставщиков (список поставщиков, у которых необходимо закупать промотовары для начисления бонусов, если список пуст - все поставщики являются разрешёнными) | Структура описана ниже |
map_pharmacy_ids |
Список кодов подразделений, для которых предназначена инициатива | Структура описана ниже |
marketing_action_data |
Параметры инициативы (см. примечание). | Структура описана ниже |
</marketing_action>
</marketing_actions>
</action>
</fe-actions>
Список промотоваров в инициативе¶
<products>
<product>
<product_id>Идентификатор промотовара</product_id> - строка(100)
<product_name>Наименование промотовара</product_name> - строка(500)
<description>Описание промотовара (на текущий момент указывается наименование контракта)</description>
<suppliers>
<supplier>
<tin>ИНН поставщика</tin>
<id>ID поставщика на портале</id>
<name>Наименование поставщика на портале</name>
<map_code>Код поставщика в учетной системе</map_code>
</supplier>
</suppliers>
<product_data>Параметры_инициативы</product_data> (см. примечание).
<nomenclatures>
<nomenclature>
<nomenclature_id>Код номенклатуры портала</nomenclature_id> - строка(100)
<nomenclature_name>Наименование номенклатуры портала</nomenclature_name> - строка(500)
<map_nomenclature_code>Код номенклатуры в учётной системе аптеки</map_nomenclature_code> - строка(100)
<map_producer_code>Код производителя в учётной системе аптеки</map_producer_code> - строка(100)
<map_producer_country_code>Код страны в учётной системе аптеки</ map_producer_country_code> - строка(100)
<nomenclature_barcodes>Заводской штрих-код</nomenclature_barcodes> - строка(500) - может быть список через запятую
</nomenclature>
</nomenclatures>
</product>
</products>
Примечание
Параметры инициативы, разные для разных типов инициатив. Тип данных: для каждого типа инициатив свое xml-дерево. Значения могут быть указаны как для инициативы в целом, так и для каждого из промотоваров в отдельности (зависит от типа инициативы).
Список кодов подразделений¶
<map_pharmacy_ids>
<map_pharmacy_id>Код аптеки в учётной системе</map_pharmacy_id>
</map_pharmacy_ids>
API для передачи маркетинговых инициатив в программное обеспечение аптеки¶
API имеет единую точку входа для группы аптек и предназначен для использования аптечным ПО с централизованной базой данных.
Для идентификации аптеки из входящего запроса используется код Почтового идентификатора и Код подразделения.
Для организации доступа по API надо обратиться в службу технической поддержки портала Созвездие, которая создаст пользователя с правами Региональный менеджер и передаст вам токен, созданный для этого пользователя. Токен используется для авторизации запроса по API. К этому пользователю службой технической поддержки портала должны быть прикреплены аптеки, для которых запрашиваются инициативы.
В ответ на запрос по адресу https://portal.esc.ru/ws/initiative-api-service/marketing-actions/<почтовый идентификатор>/<код_подразделения> выдаются действующие в данный момент инициативы типов Обязательная матрица, Рекомендованный товар, УСТМ, Товар дня, Дополнительный бонус за продажу, Компенсация скидки, Закупка месяц и Закупка квартал, а также Закупка УСТМ Пульс мес, Закупка УСТМ Пульс квартал, Матрица+.
API актуальные инициативы (ссылка откроется в новом окне).
Обмен данными с Пульсом¶
Пульс реализовал API для передачи данных. Подробное описание API находится в файле swagger.yaml (щёлкните правой клавишей мыши и выберите "Сохранить ссылку как").
-
По аптекам, ПО которых заказ у Пульса ТП, данные пересчитываются каждый день.
Примечание
Пересчёт данных выполняется ночью.