Для AI-агентов: markdown этой страницы — /docs-content/entities/catalogs.md индекс документации — /llms.txt

Каталоги

Торговые каталоги портала: список, получение и фильтрация. Каталог задаёт iblockId, по которому работают товары, разделы и цены. Каталоги доступны только для чтения.

Битрикс24 API: catalog.catalog.* Скоуп: catalog

Список каталогов

GET /v1/catalogs

Возвращает список торговых каталогов портала с поддержкой фильтрации, сортировки и выборки полей.

Параметры

Параметр Тип По умолч. Описание
Параметрlimit Типnumber По умолч.50 ОписаниеКоличество записей (до 5000). При limit > 50 ответ автоматически собирается из нескольких страниц Битрикс24
Параметрoffset Типnumber По умолч.0 ОписаниеСколько каталогов пропустить с начала выдачи: ?offset=1 начинает со второго каталога
Параметрselect Типstring По умолч.— ОписаниеВыборка полей: ?select=id,name. Возвращаются только перечисленные поля
Параметрsort Типstring По умолч.— ОписаниеПоле сортировки. Префикс - — по убыванию: ?sort=-id
Параметрorder Типobject | string По умолч.— ОписаниеСортировка в одной из двух форм.
Поле и направление: ?order[id]=desc. Поля те же, что у sort. Работает, только если sort не передан. Направление — asc, desc, ASC или DESC, другое значение возвращает 400 INVALID_SORT_DIRECTION.
Только направление: ?sort=id&order=desc. Дополняет sort и разворачивает по убыванию его поля без префикса -. Поле с - остаётся по убыванию и при order=asc. Без sort и со значением вне asc и desc не действует
Параметрfilter Типobject По умолч.— ОписаниеФильтрация по полям GET /v1/catalogs/fields.
Синтаксис фильтрации. Пример: ?filter[iblockTypeId]=CRM_PRODUCT_CATALOG
ПараметрwithTotal Типstring По умолч.— ОписаниеИгнорируется: у каталогов подсчёт не отключается, поэтому meta.total приходит так же, как без параметра, при любом значении, в том числе false. Листание и количество записей

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/catalogs" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/catalogs" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalogs', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Каталогов: ${meta.total}`)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/catalogs', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata Типarray ОписаниеМассив каталогов (все поля — см. Поля каталога)
Полеmeta.total Типnumber ОписаниеОбщее количество каталогов, соответствующих фильтру. Не приходит на пустой странице при offset больше нуля
Полеmeta.hasMore Типboolean ОписаниеЕсть ли ещё записи за пределами limit

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 25,
      "iblockId": 25,
      "iblockTypeId": "CRM_PRODUCT_CATALOG",
      "lid": "s1",
      "name": "Товарный каталог CRM",
      "productIblockId": null,
      "skuPropertyId": null,
      "subscription": "N",
      "vatId": 1,
      "yandexExport": false
    },
    {
      "id": 27,
      "iblockId": 27,
      "iblockTypeId": "CRM_PRODUCT_CATALOG",
      "lid": "s1",
      "name": "Товарный каталог CRM (предложения)",
      "productIblockId": 25,
      "skuPropertyId": 101,
      "subscription": "N",
      "vatId": 1,
      "yandexExport": false
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

Пример ответа при ошибке

400 — фильтр по несуществующему полю:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'nonExistentField' for entity 'catalogs'. Available: id, iblockId, iblockTypeId, lid, name, productIblockId, skuPropertyId, subscription, vatId, yandexExport"
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодUNKNOWN_FILTER_FIELD ОписаниеФильтр по полю, которого нет у каталога. Сообщение содержит список доступных полей
HTTP400 КодUNKNOWN_SORT_FIELD ОписаниеСортировка по полю, которого нет у каталога
HTTP400 КодINVALID_SORT_DIRECTION ОписаниеВ словаре order направление вне asc, desc, ASC и DESC
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа catalog
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке x-ratelimit-limit. Повторите после срока из заголовка Retry-After

Полный список общих ошибок API — Ошибки.

Известные особенности

Каталог товаров или каталог предложений. Тип каталога в выдаче видно по полям productIblockId и skuPropertyId: у базового каталога товаров оба null; у каталога предложений они заполнены, причём productIblockId — это iblockId связанного каталога товаров.

Когда использовать search вместо list: для условий по нескольким полям удобнее POST /v1/catalogs/search — фильтр передаётся в теле запроса.

Смотрите также