Обмен данными
Общие положения
Обмен данными между Стратегия Фарма (СФ) и внешними учётными системами осуществляется с помощью файлов.
Файлы выкладываются на FTP-сервер.
Данные о товародвижении передаются в терминах и кодах справочников товаров внешних учётных систем.
Чем отличается товар от номенклатуры
Номенклатура - наименьшая единица справочника товаров, с детализацией до конкретного предприятия-производителя и страны производства.
Товар – группировка номенклатур.
Примеры номенклатур:
- Аспирин-C табл. шип. стрип № 10 Bayer Bitterfeld GmbH ГЕРМАНИЯ
- Аспирин-C табл. шип. стрип № 10 Bayer AG ГЕРМАНИЯ
- Аспирин-C табл. шип. стрип № 10 Kern Pharma S.L. ИСПАНИЯ
Пример товара:
- Аспирин-C табл. шип. стрип № 10 импортные.
В учётной системе товародвижение может вестись в терминах номенклатур или в терминах товаров. Поскольку маркетинговые контракты заключаются с конкретными производителями, данные о товародвижении необходимо детализировать до номенклатуры. Передавать код номенклатуры обязательно - без него реализовать сопоставление партий товародвижения "на лету" невозможно. Если в аптеке справочник товаров не детализирован до номенклатуры, в качестве кода номенклатуры должна выгружаться "сцепка полей" [“код товара”_”код производителя”].
Получение данных от систем товарного учёта (СТУ)
Общие сведения
Данные об остатках и движениях каждой партии товара имеют вид оборотной ведомости за каждый день.
Например, по партии №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 - код клиента(юр. лица).
Разделителем между целой и дробной частями чисел является точка.
Последовательность действий по организации процесса получения данных от СТУ
- Вы формируете и даёте нам два файла: первичная выгрузка и регулярная выгрузка, удовлетворяющие спецификации. Как правило, приходится сделать несколько итераций, пока ваши файлы начнут соответствовать спецификации.
- После удачной загрузки формируем оборотную ведомость и передаём вам для сравнения с оборотной ведомостью, полученной непосредственно в СТУ.
- Добиваемся отсутствия расхождения цифр.
Спецификация файлов с данными о товародвижении
Файлы с товародвижением бывают двух видов:
- Первичная выгрузка
- Регулярные выгрузки
Первичная выгрузка - данные по аптеке выгружаются впервые.
Первичная выгрузка используется для учёта остатков, которые были в аптеке на начало стартового периода передачи данных из этой аптеки, а также для замены неверных остатков. Например, если аптека начинает выгружать данные начиная с 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
- в файле не может быть записей о движениях/остатках ранее стартовой даты первички.
- период дат выгрузки в файле не указывается.
Состав данных и требования к файлу
- Данные по всем имеющимся остаткам товаров, которые больш нуля на дату начала периода плюс движение и остатки, соответствующие движению (входящий/исходящий остаток за каждый день движения), за весь период. По партии в аптеке за одну дату указывается только одна запись об остатках, независимо от количества движений в этот день.
- Входящий остаток на дату начала периода должен быть равен нулю. На величину реального входящего остатка на дату начала периода, если он больше нуля, нужно сформировать "виртуальную" строку документа типа "Ввод остатков" (тип документа 9). Рекомендуется в качестве значения distribution_id указать значение map_batch_id из таблицы партий товара. В качестве doc_number можно указать "Первичная выгрузка". doc_date при этом равна дате остатка (время 00:00:00).
- Значения 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 ш.
- данные об остатках (в теге <emnant>):
- 10.01.2019 – входящий 2, исходящий 1
- 20.01.2019 – входящий 1, исходящий 0
Состав данных и требования к файлу
- Период дат - "конец интервала - текущая дата, а начало интервала - минус 93 дня, но не ранее наименьшей даты движения в первичной выгрузке, плюс 1 день" - чтобы получить отредактированные "задним числом" данные.
- Если в учётной системе нет данных за все предыдущие 93 дня - выгружаются за дни, что есть, с соответствующим указанием периода в заголовке файла.
- Данные по движениям и соответствующим им остаткам (входящий и исходящий остаток за каждый день движения) должны быть только за указанный в заголовке период. Если в теле файла содержатся данные вне указанных в заголовке файла дат - файл считается ошибочным и не грузится.
- Файл формируется и отправляется ежедневно
- Желательна возможность ручного формирования файла с выбором произвольной начальной даты периода (при этом конечной датой всегда является "текущая" дата) с обязательным указанием в заголовках файлов даты начала и окончания периода.
Логика обработки регулярной выгрузки
- Если в файле с данными даты периода не указаны, этот файл классифицируется как первичный и по этой аптеке удаляются все ранее загруженные данные.
- Если в файле с данными даты периода указаны, файл классифицируется как регулярный, все ранее загруженные движения и остатки за указанный период удаляютя, партии при этом не удаляются, и выполняется загрузка данных из файлов.
- При отсутствии первичной выгрузки регулярная загружаться не будет, файл будет классифицирован как ошибочный.
Описание файла с данными о товародвижении аптеки из учётной системы (версия 1)
Заголовок файла
<?xml version="1.0" encoding="UTF-8"?>
<map-actions client_id=Код_клиента>
<data_version>1</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>
| Имя тега | Описание | Комментарий |
|---|---|---|
| ap_batch_id | Идентификатор партии в учётной системе | Строка(100) |
| map_pharmacy_id | Код аптеки в справочнике подразделений учётной системы (подразделение-владелец базы) | Строка(100) |
| map_pharmacy_name | Наименование аптеки | Строка(500) |
| map_nomenclature_id | Код номенклатуры в справочнике | Строка(100) |
| map_nomenclature_name | Полное наименование номенклатуры в учётной системе | Строка(500) |
| map_producer_id | Код производителя номенклатуры | Строка(100) |
| map_producer_name | Полное наименование производителя в учётной системе. | Строка(500) |
| map_producer_country_id | Код страны производителя (может не быть) | Строка(100) |
| map_producer_country_name | Полное наименование страны производителя в учётной системе (может не быть) | Строка(500) |
| map_supplier_code | Код поставщика в учётной системе | Строка(100) |
| map_supplier_tin | ИНН поставщика в учетной системе | Строка(100) |
| 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 – товар Еаптека и т. д. ВАЖНО! Если заказ не выкуплен и продажа происходит с остатка аптеки, признак интернет заказа все равно устанавливается. |
</batch>
</batches>
</action>
Структура поля nomenclature_codes
<nomenclature_codes>
<code owner="Владелец_справочника_1">Код_в_справочнике</code>
...
<code owner="Владелец_справочника_N">Код_в_справочнике</code>
</nomenclature_codes>
Значения атрибута owner ("Владелец_справочника")
- map - учетная система, из которой выгружаются данные - ОБЯЗАТЕЛЬНОЕ!
- puls - прайс-лист поставщика "Пульс".
- katren - прайс-лист поставщика "Катрен.
- protek - прайс-лист поставщика "Протек".
- barcode - ЗШК номенклатуры.
- gtin - GTIN номенклатуры
Добавление иных владельцев справочника возможно по договоренности.
Тип данных поля "Код_в_справочнике": Строка(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) |
| check_line_unique_number | Номер строки чека | Целое число |
| quantity | Количество товара | Число(15,6) |
| purchase_sum_nds | Сумма в ценах закупочных с НДС | Число(10,2) |
| retail_sum_nds | Сумма в ценах розничных с НДС | Число(10,2) |
| discount_sum | Сумма всех скидок по строке. retail_sum_nds - discount_sum должно равняться сумме оплаты | Число(10,2) |
| resale_sign | Признак перепродажи, то есть продажи товара другим аптечным учреждениям или закупки товара у других аптечных учреждений. | Имеет смысл для документов типа 1 и 3. Целое число: 1 - перепродажа, 0 - нет |
| ofd_operator_code | Код оператора фискальных данных | Строка(50) |
| 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 – товар Еаптека |
<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>