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

Общая идея

Плагин синхронизации получает данные от репрезентатива данных (далее API) учетной системы (например 1с).

1. Общие требования к endpoint API

1.1 Поддерживаемые методы

  • GET /api/v1/get получение товаров и категорий
  • GET /api/v1/balance Опционально получение остатков товаров

Параметры передаются в query string.

URL методов приведен как пример и может быть изменен на любой валидный URL разработчиком API.

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

Подробная инструкция по установке и настройке утилиты доступна в разделе «Утилита синхронизации 1С → онстор».

2. Получение товаров и категорий

Пример запроса:

/api/v1/get?type=product&modified_since=2026-02-01T00:00:00Z&limit=100&offset=0

Допустимые параметры (фильтры и пагинация):

  • type — category / product
  • modified_since указывает API возвращать записи, у которых время изменения карточки товара больше или равно указанному значению
  • limit параметр пагинации, определяющий количество записей в одном батче
  • offset параметр пагинации, определяющий смещение в выборке

3. Поля

Каждый объект должен содержать следующие поля:

Поле Тип Обязательное Описание
id string Да Уникальный и стабильный идентификатор
type string Да Тип сущности: category или product
parent string Да Идентификатор родительской сущности (0 или null для корневой категории)
name string Да Наименование товара или категории
modified_at string Да Время последнего изменения товара или категории
description string Нет Описание товара
bulk bool Нет false — штучный товар, true — весовой товар
price number Нет Стоимость товара
discount number Нет Размер скидки
store_balance number Нет Остаток товара
image_url string Нет URL-ссылка на изображение товара
image_hash string / number Нет Хэш изображения или другое значение для отслеживания его изменений
Требования:
  • ID должен быть уникальным и не изменяться со временем
  • Связь parent должна быть валидной
  • URL изображения должен быть публично доступен без авторизации и редиректов
  • Поле modified_at должно обновляться при любом изменении товара или категории
  • Значения price, discount и store_balance должны передаваться в корректном числовом формате

4. Логика добавления, изменения и удаления товаров

  • Добавление

    Плагин добавляет все переданные товары, id которых не найдено в онстор

  • Изменение данных

    Плагин изменяет все данные товаров, у которых было изменено значнеие поля `modified_at`,

  • Удаление

    Если ранее товар был создан в онстор и его нет текущем ответе от API, плагин помечат такой товар как заблокирвоанный и он не отображается на витрине.

  • Если товар новый → создается в онстор
  • Если изменился modified_at → товар обновляется
  • Если изменился image_hash → обновляется только изображение
  • Если товар исчез из API → товар скрывается (помечается заблокированным)

5. Изменение изображений

Актуальность изображения товара контролируется полем image_hash. Рекомендуется использовать в качестве значения хэш изображения, однако допускаются и другие способы контроля изменений, например дата обновления изображения или любая другая версия изображения.

Поле image_hash обрабатывается независимо от modified_at. То есть для обновления изображения достаточно изменить значение image_hash — в таком случае остальные данные товара остануться без изменений.

6. Структура ответа и пагинация (обязательная)

Ответ API обязательно должен быть валидным JSON-объектом, содержащим:

  • data — массив с данными товаров или категорий
  • total — общее количество записей, соответствующих установленным фильтрам, без учета пагинации

API должно поддерживать пагинацию и принимать параметры запроса limit и offset.

Пример ответа:

{
  "data": [
     {
      "id": "b01a1a32-8ba2-11e6-9cf3-10bf484d6226",
      "parent": "551b4ed9-c385-11e6-9cd7-10bf484d6226",
      "type": "product",
      "bulk": false,
      "name": "Рис длинный пропаренный 800г Гудвилл",
      "price": 145,
      "store_balance": 16,
      "modified_at": "2026-02-13T13:24:04",
      "description": "…",
      "image_url": "https://…/images/b01a1a32-8ba2-11e6-9cf3-10bf484d6226.jpg",
      "image_hash": "f9a15f0d6ebf943aea177f597cb96689c2d5c44d"
    },...
    ],
  "total": 15420
}

6. Синхронизация остатков (необязательный метод)

Если магазину требуется частая синхронизация остатков (например, при большом количестве продаж в режиме супермаркета), рекомендуется реализовать отдельный упрощённый метод для получения только данных по остаткам.

Пример запроса:

/api/v1/balance?modified_since=2026-02-01T00:00:00Z&limit=100&offset=0

Допустимые параметры:

  • modified_since — указывает API возвращать записи, у которых время изменения остатка больше или равно указанному значению
  • limit — параметр пагинации, определяющий количество записей в одном батче
  • offset — параметр пагинации, определяющий смещение в выборке

Ответ

{
  "data": [
     {
      "id": "b01a1a32-8ba2-11e6-9cf3-10bf484d6226",
      "store_balance": 16,
    },...
    ],
  "total": 15420
}

7. Иерархическая структура (parent → child)

Модель каталога товаров древовидная. Глубина вложенности на меене 2 и не более 3:

  • 1 — категория
  • 2 — подкатегория / товар
  • 3 — товар

8. HTTP API 1С для онстор

Практическая реализация репрезентатива данных 1С