ДОКУМЕНТАЦИЯ ДЛЯ ПАРТНЁРОВ

Каталог «Квантум» через API

Подключите товары, согласованные цены и информацию о наличии к своему сайту или учётной системе. Каждая компания получает отдельный ключ и только разрешённый ей ассортимент.

Первая версия — только чтение каталога. API не оформляет заказы, не резервирует товары и не выполняет оплату. Сейчас подключён только источник in_stock: товары с положительным остатком на «Общем Складе Компании». Каталог под заказ пока не подключён. Примеры ответов ниже иллюстративные. Тип продажной цены и доступ назначает сотрудник после рассмотрения заявки.

Аутентификация

Передавайте ключ в заголовке Authorization. Его создаёт уполномоченный сотрудник «Квантум» в закрытом админ-центре. Ключ не является токеном МоегоСклада и не открывает доступ к административным операциям.

Authorization: Bearer <КЛЮЧ_ВАШЕЙ_КОМПАНИИ>

Права компании проверяются при каждом запросе. При отзыве или истечении ключ перестаёт работать. Изменение разрешённого ассортимента применяется ко всем ключам этой компании.

Каталог товаров

GET/v1/products

Получить разрешённые товары и предложения. Фильтры не расширяют доступ: они выбирают позиции только из уже разрешённого ассортимента.

Параметр	Описание
`source`	`in_stock` — в наличии; `on_order` — под заказ.
`brand`	Название бренда в каталоге, например `Apple`.
`category`	Название категории в принятом снимке.
`search`	Поиск по названию в пределах разрешённых товаров.
`limit`	От 1 до 100 позиций. По умолчанию — 50.
`cursor`	Значение `next_cursor` предыдущей страницы. Не создавать вручную.

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

Домен ниже — нерабочий пример. Используйте выданный адрес API. Выполняйте запрос на сервере, а не в JavaScript клиентского сайта.

curl 'https://api.quantumgir.ru/v1/products?brand=Apple&source=in_stock&limit=50' \
  -H 'Authorization: Bearer <КЛЮЧ_ВАШЕЙ_КОМПАНИИ>'

Условный пример ответа

{
  "snapshot_id": "demo-snapshot-001",
  "generated_at": "2026-10-14T17:00:00+03:00",
  "demo": true,
  "stale": false,
  "sources": [{
    "source": "in_stock",
    "available": true,
    "stale": false,
    "build_id": "demo-source-build",
    "source_updated_at": "2026-10-14T17:00:00+03:00"
  }],
  "total": 1,
  "products": [{
    "product_id": "demo-product-01",
    "offer_id": "demo-offer-01",
    "name": "Apple iPhone 16 128 GB",
    "brand": "Apple",
    "category": "Смартфоны",
    "source": "in_stock",
    "price": {"amount": "75000.00", "currency": "RUB"},
    "prices": [
      {"kind": "standard", "amount": "75000.00", "currency": "RUB", "vat_included": null},
      {"kind": "with_vat", "amount": "86150.50", "currency": "RUB", "vat_included": true}
    ],
    "stock": "8.000",
    "availability": "available",
    "vat_included": null,
    "source_updated_at": "2026-10-14T17:00:00+03:00"
  }],
  "next_cursor": null
}

GET/v1/products/{product_id}

Получить разрешённые предложения конкретного товара в той же структуре страницы. Если товар отсутствует или не разрешён компании — 404.

GET/v1/catalog/status

Узнать, какие из разрешённых источников имеют полный снимок и когда обновлялись. Не считать отсутствие снимка пустым прайсом.

Поля ответа

Поле	Смысл
`product_id`, `offer_id`	Идентификаторы товара и предложения. Похожие товары из разных источников не объединяются автоматически.
`prices`	Разрешённые варианты цены одного предложения: `standard` — обычная, `with_vat` — подтверждённая цена с НДС. Каждый вариант содержит сумму, RUB и свой признак НДС. Отсутствующая цена с НДС не вычисляется и не заменяется нулём.
`price.amount`	Основная разрешённая цена для совместимости: обычная, если доступна компании; иначе разрешённая цена с НДС. Десятичная строка, не себестоимость. Для выбора условий используйте `prices[].kind`, не только основную цену.
`stock`	Десятичная строка количества либо `null`, если точное количество не разрешено или неизвестно. `null` не означает бесконечный остаток.
`availability`	`available`, `unavailable` или `on_order`. Наличие не гарантирует резерв.
`vat_included`	`true` / `false` только при подтверждённых условиях. `null` — режим не подтверждён.
`source_updated_at`	Время исходных данных с часовым поясом. Не время открытия страницы.
`demo`	`true` — синтетический контур. Нельзя использовать для реальной продажи.

Верхний vat_included относится только к основной price, а не ко всем вариантам. Профиль согласованных цен компании и разрешённые варианты цены — разные ограничения. Если разрешена только цена с НДС, товары без неё не попадают в этот разрешённый каталог. Два варианта цены не удваивают количество товаров или остаток. Пример выше полностью вымышленный, это не налоговый расчёт.

Источники и свежесть

Каталог в наличии и предложения под заказ обновляются независимо. generated_at обозначает сборку снимка, а source_updated_at — актуальность соответствующего источника. stale: true означает, что данные устарели или последняя загрузка источника завершилась ошибкой.

При сбое сохраняется последний корректный снимок. Политика использования устаревших цен и остановки продаж согласуется при подключении. Частый опрос API не делает исходный прайс более свежим. Срок поставки, изображения и иные дополнительные поля не обещаются до проверки источника.

Полная загрузка каталога

Начните запрос без cursor и сохраните snapshot_id.
Загружайте страницы с возвращаемым next_cursor, не меняя фильтры и limit.
Все страницы относятся к одной версии. Загрузка завершена, когда next_cursor равен null.
Заменяйте локальный каталог и снимайте исчезнувшие предложения только после полной успешной загрузки.

Ошибка, таймаут или недоступный источник — не пустой ассортимент. При 409 начните загрузку заново: курсор истёк, изменились права или параметры запроса.

Ошибки и лимиты

HTTP	Что делать
`401`	Проверить ключ: он отсутствует, отозван или истёк. Не повторять бесконечно.
`403`	Компания приостановлена или запрошенный источник не разрешён. Обратиться к менеджеру.
`404`	Товар отсутствует либо недоступен по правам компании.
`409`	Перезапустить полную загрузку с текущими правами и без старого курсора.
`422`	Исправить фильтры или размер страницы.
`429`	Выдержать задержку из `Retry-After`. Лимит общий для всех ключей компании.
`503`	Нет полного снимка одного из запрошенных источников. Сохранить локальный последний корректный каталог.

Начинайте повтор GET-запроса после сетевого сбоя с увеличивающейся задержкой. Не создавайте параллельные бесконтрольные выгрузки. Ограничение запросов и частоту обновления согласуйте при подключении.

Безопасность подключения

Используйте HTTPS и храните ключ только на сервере.
Не вставляйте ключ в URL, браузерный код, аналитику или открытые логи.
Не передавайте его в Obsidian, Git и переписку с ИИ.
При утечке немедленно запросите отзыв и замену ключа.
Ключ каталога не даёт доступа к админ-центру, клиентам, платежам, прибыли или данным других компаний.

Рабочие цены, разрешения и условия подключения выдаются вашей компании отдельно. Общая документация не является коммерческим предложением.

Версия API v1 · Локальная реализация 0.1.0. Публичная публикация, подключение реальных источников и внешний мониторинг ещё не выполнены. Проверить страницу состояния →