====== Процесс синхронизации данных интернет-магазина с программой учета ======


===== Отправка данных на портал =====

JSON-данные передаются в теле запроса POST в REST API. Ключевым аспектом является указание заголовка Content-Type: application/json, который сообщает серверу, что данные имеют формат JSON.

В случае успешного выполнения запроса возвращается JSON объект. Убедитесь, что сервер принял данные, в противном случае выполнение запроса необходимо повторить.

Обновление данных является инкрементным и требует соблюдения хронологической последовательности и неразрывности.
Порядок действий:
- Запросить дату актуальности последней синхронизации API-методом [[sync_api#syncInfo|syncInfo]]
- Сформировать json-документ с выборкой по времени объектов, начиная с даты последней синхронизации по текущую
- Отправить запрос с сформированный JSON-документа с помощью API-метода

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

===== /api/v2/login =====

Запрос создает access токен, предназначенный для работы с API. Полученный токен необходимо отправлять в заголовке Authorization: token //accessToken//

=== Запрос ===
^Аргумент^Описание^
|username|Имя пользователя|
|key|API-ключ|

=== Ответ ===
^Аргумент^Описание^
|access_token|Токен доступа к API|

== Пример ==
<code javascript>
{
  username: "super"
  key: "7d61d77d61d77d61d77d61d77d61d7"
}
</code>




===== /api/v2/sync.info =====

Получает информацию о текущей очереди. Результат возвращается в формате JSON.

=== Запрос ===
^Аргумент^Описание^
|type|Тип синхронизируемого файла. product - основные данные товара, detail – описание товара и фото, price - цены и наличие, order - изменения заказов|

=== Ответ ===
^Аргумент^Описание^Тип^По-умолчанию^
|code|Код ответа|[[sync_api#коды_ответов|Код ответа]]| |
|status|Текстовое описание результата запроса|string| |
|queue|Длина текущей очереди|int| |
|date_last|Дата последней синхронизации сервера|datetime dd.mm.YYYY HH:mm:ss| |

== Пример ==
<code javascript>
{
  type: "product"
}
</code>



===== /api/v2/order.get =====
Получает json документ с данными заказов. Формат возвращаемых данных см. [[json_api#/api/v2/order.sync|/api/v2/order.sync]]
=== Запрос ===
^Аргумент^Описание^
|date_change|Время изменения заказа|
|limit|Необязательный. Количество элементов. Если указан, данные будут выводиться постранично с заданным количеством|
|start|Необязательный. Если указан аргумент //limit//, номер начального элемента. Обычно кратен значению //limit//|
== Пример ==
<code javascript>
{
  date_change: "2025-09-03T10:25:43+03:00"
}
</code>


===== /api/v2/reference.get =====
Получает json документ с данными заказов. Формат возвращаемых данных см. [[json_api#/api/v2/reference.sync|/api/v2/reference.sync]]
=== Запрос ===
^Аргумент^Описание^
|name|Имя справочника (country, fgroup, diseases, manufacturer, mnn, packing, tradename)|
|limit|Необязательный. Количество элементов. Если указан, данные будут выводиться постранично с заданным количеством|
|start|Необязательный. Если указан аргумент //limit//, номер начального элемента. Обычно кратен значению //limit//|
== Пример ==
<code javascript>
{
  name: "country"
}
</code>
===== /api/v2/user.get =====
Получает json документ с данными заказов. Формат возвращаемых данных см. [[json_api#/api/v2/user.sync|/api/v2/user.sync]]
=== Запрос ===
^Аргумент^Описание^
|date_change|Время изменения заказа|
|limit|Необязательный. Количество элементов. Если указан, данные будут выводиться постранично с заданным количеством|
|start|Необязательный. Если указан аргумент //limit//, номер начального элемента. Обычно кратен значению //limit//|
== Пример ==

<code javascript>
{
  date_change: "2025-09-03T10:25:43+03:00",
}
</code>



===== /api/v2/category.sync =====
Накопительная выгрузка изменений категорий за период
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|categories[]|Массив категорий|
|categories[] aid|id категории в программе учета|
|categories[] title|наименование категории|
|categories[] remove|необязательный атрибут. Пометка категории на удаление|
|categories[] aparent_id|id родительской категории в программе учета|

<code javascript>
{
 date_start: "2025-09-03T10:25:43+03:00",
 date_end: "2025-09-03T18:25:43+03:00",
 categories: [
  {
   aid: "10",
   aparent_id: "0",
   title: "Товары"
  },
  {
   aid: "11",
   aparent_id: "10",
   title: "Товар 1"
  },
  {
   aid: "12", 
   remove: 1,
   title: "Удаляемая категория"
 }
 ]
}
</code>

===== /api/v2/product.sync =====
Накопительная выгрузка изменений товаров за период
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|products[]|Массив товаров|
|products[] aid|id товара в программе учета|
|products[] aparent_id|id родительской категории в программе учета|
|products[] remove|необязательный атрибут. Пометка товара на удаление|
|products[] title|наименование товара|
|products[] barcode|Штрихкод товара|

<code javascript>
{
 date_start: "2025-09-03T10:25:43+03:00",
 date_end: "2025-09-03T18:25:43+03:00",
 products: [
   {
    aid: "10",
    aparent_id: "126", 
    title: "5-НОК табл по 50 мг №50 Сандоз",
    barcode: "7613421035662",
   },
   {
    aid: "376699",
    title: "Удаляемый товар",
    remove: "1"
   }
 ]
}
</code>
===== /api/v2/detail.sync =====
Накопительная выгрузка описания товаров за период
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|products[]|Массив товаров|
|products[] aid|id товара в программе учета|
|products[] vat|Ставка НДС|
|products[] prescript|рецептурный препарат 0 или 1|
|products[] veterinary|ветеринарный препарат 0 или 1|
|products[] flags[]|Флаги-метки товара текстовые короткие слова/словосочетания|
|products[] country_id|id страны из справочника //country//|
|products[] diseases_id[]|id заболеваний из справочника //diseases//|
|products[] fgroup_id[]|массив id фармакологических групп из справочника //fgroup//|
|products[] manufacturer_id|id производителя из справочника //manufacturer//|
|products[] mnn_id|id действующего вещества из справочника //mnn//|
|products[] packing_id|id упаковки из справочника /packing/|
|products[] tradename_id|id торгового наименования из справочника /tradename/|
|products[] analogs_id[]|id товаров-аналогов|
|products[] desc|Полное описание товара|
|products[] prescribe|Показания к применению|
|products[] dosing|Способ применения|
|products[] precaution|Противопоказания|
|products[] storeCnd|Условия хранения|
|products[] promo_desc|Промо описание товара|
|products[] images[]|Массив изображений товара|
|categories[]|Массив категорий|
|categories[] aid|id категории в программе учета|
|categories[] images[]|Массив изображений товара|

<code javascript>
{
  date_start: "2025-09-03T10:25:43+03:00",
  date_end: "2025-09-03T18:25:43+03:00",
  products: [
    {
      aid: "376647",
      vat: "VAT_10",
      prescript: 1,
      veterinary: 1,
      flags: ["Акция","Новинка"],
      country_id: "21", 
      diseases_id:[124,125],
      fgroup_id: ["0000001021","0000001022"],
      manufacturer_id: "278",
      mnn: "278",
      packing_id: "23",
      tradename_id: "785",
      analogs_id:[712,718],
      desc: "<...>Описание<...>",
      prescribe: "<...>Показания к применению<...>",
      dosing: "<...>Способ применения<...>",
      precaution: "<...>Противопоказания<...>",
      storeCnd: "<...>Условия хранения<...>",
      promo_desc: "Промоописание товара длинное может быть",
      images:["AP-0000-3766647.jpg", "AP-0000-3766647-1.jpg"]
    }
  ],
  categories: [
    {
      aid: "37",
      images: ["AP-0000-3766647.jpg", "AP-0000-3766647-1.jpg"]   
    }
  ]
}
</code>

===== /api/v2/price.sync =====
Накопительная выгрузка изменений цен и остатков за период. Изменения по товару, необходимо посылать всегда двумя лотами, один короткий срок годности, второй длительный, даже если изменения по одному из сроков годности.
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|lots[]|Массив лотов|
|lots[] aid|уникальный id лота(партии) в программе учета| не учитываются при синхронизации
|lots[] aproduct_id|уникальный id товара в программе учета GUID в 1c|
|lots[] expire|Срок годности партии|
|lots[] short|Короткий срок годности 0 или 1|
|lots[] prices[]|Массив цен|
|lots[] prices[] aid|id группы цен|
|lots[] prices[] value|цена|
|lots[] stocks[]|Массив складов. |
|lots[] stocks[] aid|id склада/магазина цен|
|lots[] stocks[] qty|количество на складе. Если товар закончился в период выгрузки - необходимо указать 0|

<code javascript>
{
 date_start: "2025-09-03T10:25:43+03:00",
 date_end: "2025-09-03T18:25:43+03:00",
 lots: [
  {
   aid: "572345",
   aproduct_id: "865",
   expire: "2023-09-30T00:00:00",
   short: 1,
   prices: [
    {
      aid: 0,
      value: 720,
    },
    {
      aid: 1,
      value: 720,
    },
    {
      aid: 2,
      value: 602.81,
    },
   ]
   stocks: [
    {
      aid: 834,
      qty: 9,
    }, 
    {
      aid: 838,
      qty: 8,
    },   
    {
      aid: 836,
      qty: 0,
    },   
   ]
  },
 ],
}
</code>



===== /api/v2/user.sync =====
Данные пользователей
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|users[]|массив пользователей|
|users[] aid|id пользователя в программе учета|
|users[] phone|Телефон|
|users[] email|E-mail|
|users[] card|Номер карты|
|users[] card_type|GUID типа карты|
|users[] firstname|Имя|
|users[] lastname|Фамилия|

<code javascript>
{
  date_start: "2025-09-03T10:25:43+03:00",
  date_end: "2025-09-03T18:25:43+03:00",
  users: [
    aid: "722552",
    email: "customer@gmail.com",
    phone: "79081234567",
    card: "0122222",
    card_type: "1",
    firstname: "Кирилл",
    lastname: "Сорокин",
  ]
}
</code>


===== /api/v2/order.sync =====
Накопительная выгрузка изменений по заказам за период

Идентификатор aid назначается программой и считается приоритетным после первого назначения. Если aid не указан приоритетным считается id заказа, присваиваемый сайтом. После двусторонней синхронизации заказ должен содержать оба идентификатора.

Пользователя c флагом registered установленным в 0 считать гостем. Данный пользователь не имеет постоянного идентификатора и не должен быть регистрирован в качестве контрагента.

|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|orders[]|массив заказов|
|orders[] aid|уникальный id заказа в программе учета|
|orders[] id|уникальный id заказа на сайте|
|orders[] number|номер заказа пользователя|
|orders[] status|id статуса заказа 1 Новый / Заказ создан Клиентом, 2 Заказ собирается / сборка в аптеке, перемещения в аптеку, 3 Заказ в аптеке / готов к выдаче клиенту, 4 Заказ отменен / отменен клиентом, 5 Заказ получен / выкуплен клиентом|
|orders[] source| Источник заказа: сайт 0, программа учета: 1|
|orders[] created|Дата создания заказа|
|orders[] changed|Дата последнего изменения заказа|
|orders[] user aid|уникальный id клиента в программе учета|
|orders[] user id|уникальный id клиента на сайте|
|orders[] user registered|клиент зарегистрирован либо гость|
|orders[] user card|номер карты клиента|
|orders[] user card_type|тип карты клиента|
|orders[] user firstname|имя клиента|
|orders[] user lastname|фамилия клиента|
|orders[] user phone|телефон клиента|
|orders[] user email|email клиента|
|orders[] shipping id|id типа доставки |
|orders[] shipping stock_aid|id пункта выдачи в программе учета|
|orders[] shipping type|тип доставки stock (самовывоз) или delivery (доставка)|
|orders[] shipping address|Адрес доставки|
|orders[] payment_id|id способа оплаты в программе учета|
|orders[] prices shipping|стоимость доставки|
|orders[] prices total|сумма заказа|
|orders[] prices coupon|сумма скидки по купону|
|orders[] prices balance|сумма внесенной оплаты по заказу|
|orders[] purchases[] aid|id товара в программе учета|
|orders[] purchases[] short|признак короткого срока годности|
|orders[] purchases[] expire|максимальный срок годности товара|
|orders[] purchases[] price|цена единицы товара|
|orders[] purchases[] qty|количество единиц товара|
|orders[] note|комментарий пользователя к заказу|

<code javascript>
{
  date_start: "2025-09-03T10:25:43+03:00",
  date_end: "2025-09-03T18:25:43+03:00",
  orders: [
    aid: "722552",
    id: 722,
    number: 206,
    status: 1,
    source: 0,
    created: "2021-09-30T10:05:00+03:00",
    changed: "2021-09-30T10:05:00+03:00",
    user: {
      aid: "435534",
      id: 456,
      registered: 0,
      card: "76760000000000086", 
      card_type: "2"
      firstname: "Кирилл",
      lastname: "Сорокин",
      phone: "79683500000",
      email: "info@web152.ru",
    },
    shipping: {
      stock_aid: "834",
      id: 30,
      type: "delivery",
      address: "603000 г. Нижний Новгород, Володарского"
    }
    payment_id: 1,
    prices: {
      shipping: "0",
      coupon: "-12.5",
      balance: "0",
      total: "257",
    },
    purchases: [
      {
        aid: "3790984",
        expire: "2021-09-30T10:05:00+03:00",
        short: 1,
        price: 1000,
        qty:1
      },
      {
        aid: "3790985",
        expire: "2021-09-30T10:05:00+03:00",
        short: 0,
        price: 459,
        qty:1
      },
    ]
    note: "Комментарий"
  ]
}
</code>

===== /api/v2/reference.sync =====
Справочные данные
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|books[]|Массив справочников|
|books[] name|Имя справочника|
|books[] references[]|Массив значений справочников|
|books[] references[] id|id значения справочника на сайте|
|books[] references[] aid|id значения справочника в программе учета|
|books[] references[] value|значение|

<code javascript>
{
  date_start: "2025-09-03T10:25:43+03:00",
  date_end: "2025-09-03T18:25:43+03:00",
  books: [
  {
    name: "vendor",
    references: [
      {
        id: "678",
        aid: "7959",
        value: "Плантэкстракт ГмбХ и Ко.КГ/Мадаус ГмбХ"
      },
      {
        id: "556",
        aid: "7960",
        value: "Рекитт Бенкизер Хелскэар/ЭсЭсЭл Мануфакт"
      }
    ]
  }
}
</code>

===== /api/v2/stock.sync =====
Справочные данные по складам.
|date_start|Дата начала среза данных|
|date_end|Дата окончания среза данных|
|cities[]|Описание городов|
|cities[] aid|id города в программе учета|
|cities[] title|Название города|
|cities[] stocks[]|Массив пункта выдачи|
|cities[] stocks[] aid|id пункта выдачи в программе учета|
|cities[] stocks[] title|Название пункта выдачи|
|cities[] stocks[] address|адрес пункта выдачи для отображения в товаре/заказе на сайте|
|cities[] stocks[] address_short|адрес пункта выдачи в сокращенном виде для СМС о заказе|
|cities[] stocks[] phone|телефон пункта выдачи|
|cities[] stocks[] lat|Географическая широта|
|cities[] stocks[] lon|Географическая долгота|
|cities[] stocks[] schedule_desc|режим работы пункта выдачи|
|cities[] stocks[] dropshipping|Признак удаленного склада (0 - нет, 1 - да)|

<code javascript>
{
  date_start: "2025-09-03T10:25:43+03:00",
  date_end: "2025-09-03T18:25:43+03:00",
  cities: [
  {
   aid: "52",
   title: "Нижний Новгород",
   stocks: [
    {
     aid: "830",
     title: ЕАптека Московское шоссе ост Березовская",
     address: "603079, г.Нижний Новгород, Московское шоссе, 179",
     address_short: "Н.Новгород,Московское ш.,179",
     phone: "78312155141",
     schedule_desc: "ПН-ПТ 8:00 – 20:00; СБ-ВС 9:00 – 20:00",
     lat: "56.296348",
     lon: "43.924713",
    },
    {
     aid: "831",
     title: "ЕАптека Терешковой",
     address: "603081, г.Нижний Новгород, ул. Терешковой, 6а",
     phone: "78312155140",
     lat: "56.296348",
     lon: "43.924713",
     schedule_desc: "ПН-ПТ 8:00 – 20:00; СБ-ВС 9:00 – 20:00",
    }
   ]
  },
 ]
}
</code>
===== Коды ответов =====
Любой отличный от 1 код ответа следует рассматривать как ошибку запроса.

^Код ответа^Расшифровка^
|1|Запрос успешно исполнен|
|10|Некорректный запрос|
|30|Не удалось разобрать JSON файл. Файл имеет некорректную структуру или был поврежден при загрузке|
|40|Дата текущей синхронизации указана некорректно|
|41|Дата последней синхронизации сервера не совпадает с датой последней синхронизации файла|