Требования Tec.Delivery к репрезентативу данных (REST API) учетной системы для получения данных SCU

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

Общая идея

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

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

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

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

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

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

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. Поля

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

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

• Добавление

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

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

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

• Удаление

  Если ранее товар был создан в Tec.Delivery и его нет текущем ответе от 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: