Товары

Публичный API товаров читает актуальное состояние только из PostgreSQL и требует Bearer token активного пользователя API.

Один товар

GET /api/v2/products/:stockNumber
Authorization: Bearer <token>

Публичный идентификатор товара - строковый stockNumber. PostgreSQL id и UMI id не входят в ответ.

Базовый ответ не содержит описание, полный набор фотографий, характеристики, SEO, фасетные значения, разделы, склады и конфигуратор:

{
  "status": true,
  "data": {
    "id": "6119904",
    "stockNumber": "6119904",
    "name": "eBOX670-891-FL-DC-Flexible IO",
    "fullName": "Промышленный компьютер eBOX670-891-FL-DC-Flexible IO",
    "url": {
      "full": "https://nnz-ipc.ru/catalogue/ipc/embedded_pc/compact/ebox670-891-fl-dc-flexible_io/",
      "host": "nnz-ipc.ru",
      "path": "/catalogue/ipc/embedded_pc/compact/ebox670-891-fl-dc-flexible_io/",
      "slug": "ebox670-891-fl-dc-flexible_io"
    },
    "vendor": {
      "id": "axiomtek",
      "name": "Axiomtek"
    },
    "media": {
      "preview": "https://nnz-ipc.ru/images/preview.jpg"
    },
    "pricing": {
      "currency": "USD",
      "onRequest": false,
      "retail": {
        "value": 1401.17,
        "onRequest": false
      },
      "personal": {
        "level": "Дилер",
        "value": 888.16,
        "onRequest": false
      },
      "sale": {
        "active": true,
        "value": 888.16,
        "onRequest": false,
        "discountFromRetail": {
          "value": 513.01,
          "percent": 36.61
        }
      }
    },
    "availability": {
      "inStock": 1,
      "shipping": 0
    },
    "primarySectionId": "178225",
    "contentUpdatedAt": "2026-07-10T10:00:00.000Z",
    "commercialUpdatedAt": "2026-07-10T11:00:00.000Z"
  },
  "error": {},
  "message": ""
}

Цены и права

• Исходная валюта всех цен - USD; API не выполняет конвертацию в RUB.
• retail возвращает розничную цену.
• personal возвращает только выбранный уровень текущего пользователя. Для уровня Розн значение personal равно null.
• sale.active берется из признака распродажи UMI, а sale.value - из спеццены.
• Нулевая или отсутствующая цена возвращается как { "value": null, "onRequest": true }.
• UMI-флаг «Не отображать цены» устанавливает pricing.onRequest = true и скрывает суммы от обычного пользователя.
• Администратор видит массив pricing.levels со всеми уровнями. Для товара с запретом показа цен у администратора сохраняется onRequest: true, но исходные значения доступны для диагностики.

Дополнительные данные

Дополнительные части подключаются через comma-separated include:

GET /api/v2/products/6119904?include=description,media,features,seo,filterValues,sections,warehouses,documentation,software

Значение	Что добавляет
description	Полное описание товара
media	Массив media.photos; preview есть в базовом объекте
features	Сгруппированные публичные технические характеристики
seo	SEO-заголовок и HTML-контент товара
filterValues	Фасетные значения товара для локальной фильтрации
sections	Все публичные разделы товара
warehouses	Остатки по отдельным складам
configurator	Безопасный payload конфигуратора при наличии доступа
documentation	Публичные HTTP(S)-ссылки из поля UMI «Документация»
software	Публичные HTTP(S)-ссылки из поля UMI «Программное обеспечение»

Неизвестное значение include возвращает HTTP 400.

features сохраняет публичные группы и порядок UMI. Фасетные alias, цены, SEO, служебные и коммерческие поля в характеристики не попадают. Гарантийные условия считаются публичными характеристиками:

{
  "features": [
    {
      "uid": "f7d10333-e23c-11e6-8dc0-00155d0c1500",
      "name": "Конструктивное исполнение",
      "items": [
        {
          "uid": "f7d10340-e23c-11e6-8dc0-00155d0c1500",
          "fieldId": 192786,
          "name": "Класс защиты",
          "value": "IP40"
        }
      ]
    }
  ]
}

filterValues предназначен в том числе для приложений, которые хранят каталог в собственной базе. key совпадает с ключом значения в section.filters, а sectionIds показывает, в каких публичных разделах применяется значение:

{
  "filterValues": [
    {
      "uid": "124786f0-d1ef-11e7-9887-00155d0c1500",
      "fieldId": 192680,
      "value": "IP40",
      "key": "ip40",
      "sectionIds": ["178225", "37057"]
    }
  ]
}

SEO возвращается независимо от описания и характеристик:

{
  "seo": {
    "title": "SEO-заголовок товара",
    "html": "<p>SEO-контент</p>"
  }
}

hasConfigurator присутствует только у администратора или пользователя с доступом к конфигуратору. Явный include=configurator без такого доступа возвращает HTTP 403. Сырой priceData конфигуратора не отдается: обычный пользователь получает розничную и свою персональную цену, администратор - все нормализованные уровни.

Документация и программное обеспечение

Документация и ПО синхронизируются отдельным процессом и читаются публичным API только из PostgreSQL. Оба include независимы. Если include запрошен, но у товара нет ресурсов этого типа, API возвращает пустой массив:

{
  "documentation": [
    {
      "title": "Руководство пользователя",
      "description": "Версия 2.1",
      "url": "https://nnz-ipc.ru/files/manual.pdf",
      "fileType": "pdf",
      "sizeBytes": 1048576,
      "size": "1 Мб"
    }
  ],
  "software": []
}

description, fileType, sizeBytes и size могут быть null. FTP-ссылки, ссылки со встроенными учетными данными и опасные URL публично не отдаются. Сырой HTML UMI также не входит в ответ. Пояснение рядом со ссылкой попадает в description только тогда, когда sync может однозначно связать их друг с другом.

Товары раздела каталога

GET /api/v2/catalog/sections/:id/products
Authorization: Bearer <token>

:id — публичный строковый идентификатор раздела из API каталога. По умолчанию возвращаются уникальные товары раздела и всех его дочерних разделов:

GET /api/v2/catalog/sections/178225/products?scope=subtree&page=1&pageSize=50

Для получения только непосредственно связанных товаров используйте scope=direct.

Фильтры и сортировка

Параметр	Значение
vendor	Comma-separated список публичных id производителей, например axiomtek,advantech
available	true, если есть положительный остаток хотя бы на одном складе; false — если его нет
sale	Фильтр по признаку распродажи true или false
hasPrice	true, если текущему пользователю доступна положительная розничная, персональная или корректная распродажная цена
sort	name, -name, stockNumber или -contentUpdatedAt

Разные фильтры объединяются через AND, а несколько производителей внутри vendor — через OR. Скрытая цена «по запросу» не удовлетворяет hasPrice=true, в том числе при запросе администратора.

Пример:

GET /api/v2/catalog/sections/178225/products?scope=subtree&vendor=axiomtek,advantech&available=true&hasPrice=true&sort=name&page=1&pageSize=1000&include=media,features

Пагинация и ответ

page по умолчанию равен 1, pageSize — 50. Максимальный pageSize равен 1000; отдельного режима без пагинации нет.

{
  "status": true,
  "data": {
    "items": [],
    "meta": {
      "sectionId": "178225",
      "scope": "subtree",
      "sort": "name",
      "pagination": {
        "page": 1,
        "pageSize": 1000,
        "pageCount": 1,
        "total": 846
      }
    }
  },
  "error": {},
  "message": ""
}

Элементы items имеют тот же базовый ProductDto, что и endpoint одного товара. Разрешены description, media, features, seo, filterValues, sections, warehouses, documentation и software. include=configurator в списке не поддерживается. Связанные ресурсы страницы читаются одним пакетным запросом, без запроса на каждый товар.

Существующий пустой раздел возвращает 200 и пустой items. Отсутствующий или непубличный раздел возвращает 404 CatalogSectionNotFoundError.

Список всегда возвращает только актуальное состояние. Для инкрементальной синхронизации, включая удаленные и перенесенные товары, используйте /api/v2/catalog/sections/:id/product-changes.

Ошибки

Если публично видимый товар с таким stockNumber не найден, API возвращает HTTP 404 и ProductNotFoundError.