Разработчикам

API v2: товары, справочники, цены и остатки

Три независимых потока с одинаковым протоколом: первичная выгрузка, затем журнал изменений по курсору. Документация на русском — в Swagger.

Потоки

Каждый поток — status, bootstrap, manifest, catalog, changes, batch

/v2/sync/*Карточки товаров: название, описания, изображения, ссылки на справочники и характеристики.
/v2/references/*Категории, бренды, коллекции, характеристики и их варианты.
/v2/offers/*Полные пакеты цен и остатков товара по складам поставщиков.
/v2/countries, /v2/measures, /v2/storesСтраны, единицы измерения и разрешённые вам склады.

Пример

Статус, изменения, цены

Ключ передаётся в заголовке Authorization без Bearer — тот же, что для v1.

01 / Обмен

Журнал изменений по курсору

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

  • upsert
  • revoke
  • next_cursor
  • has_more
terminal

$ curl -H "Authorization: $KEY" https://gpd-api.skeeks.com/v2/sync/status

{"protocol":1,"stream":"catalog","seeded":true,"revision":"597","pending":0,"errors":0,"offers_supported":false}

$ curl -H "Authorization: $KEY" "https://gpd-api.skeeks.com/v2/sync/changes?cursor=$CURSOR&limit=25"

{"items":[{"id":123,"revision":"598","product_revision":"7","operation":"upsert","data":{"id":123,"name":"Пример товара","brand_id":10,"category_id":20,"collection_ids":[30],"properties":[{"property_id":40,"value":"Пример"}]}},{"id":124,"revision":"599","operation":"revoke"}],"next_cursor":"…","has_more":false}

$ curl -H "Authorization: $KEY" "https://gpd-api.skeeks.com/v2/offers/changes?cursor=$OFFERS"

{"items":[{"id":123,"operation":"upsert","data":{"kind":"offers","payload":{"currency":"RUB","complete":true,"offers":[{"id":9001,"store_id":5,"supplier_code":"LMS-6060G","supplier_name":"КГ LUMIO STONE GRIS 600*600 МАТ","quantity":124.2,"purchase_price":1650,"selling_price":1890,"is_active":true}]}}}],"next_cursor":"…","has_more":false}

Сокращённые ответы. Полные схемы — в Swagger.

Порядок интеграции

Четыре шага до работающего обмена

  1. Справочники

    Получите страны, единицы измерения и склады, настройте их у себя.

  2. Первичная выгрузка

    Запустите bootstrap справочников, товаров и цен, дочитайте все страницы.

  3. Изменения

    Перейдите на changes от границы, которую выдал сервер.

  4. Сопоставление

    Сопоставляйте по исходному ID и ревизии — повтор страницы и события безопасен.

Правила протокола

Что важно учесть

pending

Карточка ещё готовится — повторите batch позже. Это не удаление.

Только revoke исключает

not_available, сетевой сбой, неполная страница, 401, 403 и 503 не дают права очищать каталог.

410 — заново bootstrap

История хранится 30 дней. Потеряли курсор — начните первичную выгрузку, сохранив локальные товары.

Доступ по сделке

При неактивной подписке API отвечает 403 с кодом ошибки — каталог при этом не очищайте.

Вопросы и ответы

Об интеграции через API.

Не нашли ответ?Расскажите о своём магазине или ассортименте — подскажем, как подключиться.Задать вопрос
Нужен ли отдельный ключ для v2?

Нет. Используется тот же ключ, что и для v1, в заголовке Authorization.

Можно ли продолжать работать на v1?

Да, v1 продолжает работать и отдаёт актуальную карточку. Новым интеграциям v1 не нужен.

Как часто опрашивать changes?

Когда удобно вашему расписанию. has_more=true означает, что нужно читать дальше без ожидания следующего опроса.

Есть ли готовый модуль?

Для сайтов на SkeekS Платформе приём уже встроен. Для других платформ интеграцию пишет ваш разработчик по Swagger.