Синхронизация каталога

Задача: во внешней системе (интернет-магазин, маркетплейс, BI) должна быть копия каталога BILLZ, которая обновляется без полного перечитывания.

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

curl -X GET 'https://api-admin.billz.ai/v2/products?limit=100&page=1' \
  -H 'Authorization: Bearer ТОКЕН'

Страницы перебираются, пока не выбран весь count. Размер страницы — 100–200 записей.

Жёсткие ограничения метода, при превышении — 400:

Параметр	Потолок
`limit`	300
`page`	10 000
`search`	100 символов

Инкрементальное обновление

Дальше запрашивается только изменённое:

curl -X GET 'https://api-admin.billz.ai/v2/products?last_updated_date=2026-08-14%2000:00:00&limit=100' \
  -H 'Authorization: Bearer ТОКЕН'

Цикл: запомнить время начала запроса → выгрузить изменения → при успехе записать это время как новую метку.

Два режима синхронизации витрины

Витрину держат в актуальном состоянии двумя расписаниями поверх одного и того же GET /v2/products.

Режим	Как часто	Что делает	Чего не умеет
Дельта	обычно раз в час	забирает изменения с прошлой синхронизации и обновляет только приехавшие товары	не замечает исчезнувшие товары
Полная	раз в сутки	приводит каталог витрины к тому виду, что пришёл в ответе	дороже по запросам, нельзя гонять часто

Дельта

Запрос с last_updated_date — как в разделе выше. Обновляются только товары из ответа.

Полная

Раз в сутки выгружается весь каталог, не указывая last_updated_date, и витрина приводится к состоянию ответа. Правило на каждый товар витрины:

Есть в каталоге витрины	Есть в ответе API	Есть остаток	Что делать
да	да	да	показывать
да	да	нет	снять с продажи либо показать «нет в наличии» — по логике площадки
да	нет	—	снять с продажи
нет	да	да	завести карточку и показать

Сложная выборка

Когда нужны фильтры по категориям, брендам, поставщикам, диапазонам цен — применяется POST /v2/product-search-with-filters. Отличия от /v2/products:

структура остатков другая: total_active_measurement_value вместо active_measurement_value;
есть курсорная пагинация — в каждом товаре приходит поле sort, которое передаётся в следующий запрос.

curl -X POST 'https://api-admin.billz.ai/v2/product-search-with-filters' \
  -H 'Authorization: Bearer ТОКЕН' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "all",
    "brand_ids": ["e158f882-d0e0-499d-b6f8-9029ac1886ca"],
    "shop_ids": ["6f244db4-75d6-4fac-9841-14867d45e36a"],
    "group_variations": false,
    "limit": 50,
    "page": 1
  }'

Фильтр по атрибутам и кастомным свойствам идёт через один параметр product_field_filters, где field_type — attribute или custom:

{
  "product_field_filters": [
    { "field_id": "491e1d8a-...", "field_type": "attribute", "field_values": ["aee6d71d-..."] },
    { "field_id": "3b6db763-...", "field_type": "custom", "field_values": ["18"] }
  ]
}

Вариативные товары

При "group_variations": true в списке возвращается родительский товар, а вариации лежат в поле variations.

Справочники

Категории, бренды, единицы измерения, характеристики и типы товаров выгружаются отдельными методами: /v2/category, /v2/brand, /v2/measurement-unit, /v2/product-characteristic, /v2/product-type. Обновляются раз в сутки.

Форма ответа у каждого справочника своя: {categories, count}, {brands, count}, {measurement_units, count}, у характеристик вместо count — active_count и deleted_count, а /v2/product-type отдаёт {product_types} без счётчика и без пагинации.

Частота запросов

API принимает до 2 запросов в секунду; при превышении — 429, обрабатывается повтором с экспоненциальной выдержкой. Лимит считается по суммарному потоку интеграции.

Чего не делать

Не отдавать фотографии товаров напрямую с CDN BILLZ; медиа кэшируется на своей стороне.