## Список услуг `GET /v1/catalog-services` Возвращает услуги товарного каталога с фильтрацией, сортировкой, выборкой полей и пагинацией. Требует фильтр `filter[iblockId]` — ID товарного каталога. Без этого фильтра запрос отклоняется с `400`. Поля `dateCreate`, `timestampX`, `dateActiveFrom` и `dateActiveTo` не принимаются в `filter`: запрос возвращает `400 UNKNOWN_FILTER_FIELD` до обращения к Битрикс24. Эти даты можно запрашивать через `select` и читать в ответе. ## Параметры | Параметр | Тип | Обяз. | По умолч. | Описание | |----------|-----|:-----:|-----------|---------| | `filter` | object | да | — | Фильтрация по полям [`GET /v1/catalog-services/fields`](./fields.md). Ключ `filter[iblockId]` обязателен — ID товарного каталога из [`GET /v1/catalogs`](/docs/entities/catalogs/list), у этого каталога не заполнен `productIblockId`. Услуги одного раздела отбирает `filter[iblockSectionId]` с ID из [`GET /v1/catalog-sections`](/docs/entities/catalog-sections/list).
[Синтаксис фильтрации](/docs/filtering). Пример: `?filter[iblockId]=25&filter[iblockSectionId]=281` | | `select` | string | нет | — | Выборка полей через запятую: `?select=iblockId,id,name,code,sort`. Если параметр передан, в нём обязательны `iblockId` и `id`. Без `select` приходит сокращённый набор полей: символьный код, внешний код, сортировка, ставка НДС, тексты, картинки и свойства каталога возвращаются только по явному перечислению — какие именно, сказано в [Полях услуги](./fields.md). Свойство каталога запрашивается своим именем: `?select=iblockId,id,name,property301` | | `sort` | string | нет | — | Поле сортировки. Префикс `-` — по убыванию: `?sort=-id` | | `limit` | number | нет | `50` | Количество записей (до 5000) | | `offset` | number | нет | `0` | Смещение от начала выборки | Для `limit > 50` ответ автоматически собирается из нескольких страниц на стороне сервера. Максимум — 5000 записей за вызов. Если под фильтр попадает больше записей, чем возвращено, в `meta.hasMore` придёт `true`. ## Примеры ### curl — личный ключ ```bash curl -g "https://vibecode.bitrix24.tech/v1/catalog-services?filter[iblockId]=25&filter[iblockSectionId]=281&limit=10" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl -g "https://vibecode.bitrix24.tech/v1/catalog-services?filter[iblockId]=25&filter[iblockSectionId]=281&limit=10" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — личный ключ ```javascript const params = new URLSearchParams({ 'filter[iblockId]': '25', 'filter[iblockSectionId]': '281', limit: '10', }) const res = await fetch(`https://vibecode.bitrix24.tech/v1/catalog-services?${params}`, { headers: { 'X-Api-Key': 'YOUR_API_KEY', }, }) const { success, data, meta } = await res.json() console.log(`Услуг: ${meta.total}`) ``` ### JavaScript — OAuth-приложение ```javascript const params = new URLSearchParams({ 'filter[iblockId]': '25', 'filter[iblockSectionId]': '281', limit: '10', }) const res = await fetch(`https://vibecode.bitrix24.tech/v1/catalog-services?${params}`, { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { success, data, meta } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data` | array | Массив услуг. Состав полей элемента — см. [Поля услуги](./fields.md) | | `meta.total` | number | Общее количество записей, соответствующих фильтру | | `meta.hasMore` | boolean | Есть ли ещё записи за пределами `limit` | ## Пример ответа ```json { "success": true, "data": [ { "active": true, "available": false, "bundle": false, "createdBy": 1295, "dateActiveFrom": null, "dateActiveTo": null, "dateCreate": "2026-10-08T20:50:59.000Z", "iblockId": 25, "iblockSectionId": 281, "id": 7231, "measure": 9, "modifiedBy": 1295, "name": "Монтаж кондиционера", "timestampX": "2026-10-08T20:50:59.000Z", "type": 7, "vatIncluded": true }, { "active": true, "available": false, "bundle": false, "createdBy": 1295, "dateActiveFrom": null, "dateActiveTo": null, "dateCreate": "2026-10-08T20:51:00.000Z", "iblockId": 25, "iblockSectionId": 281, "id": 7233, "measure": 9, "modifiedBy": 1295, "name": "Чистка кондиционера", "timestampX": "2026-10-08T20:51:00.000Z", "type": 7, "vatIncluded": true } ], "meta": { "total": 2, "hasMore": false } } ``` ## Пример ответа при ошибке 400 — не передан обязательный фильтр: ```json { "success": false, "error": { "code": "MISSING_REQUIRED_FILTER", "message": "GET /v1/catalog-services requires filter fields: iblockId. Example: GET /v1/catalog-services?filter[iblockId]=..." } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `MISSING_REQUIRED_FILTER` | Не передан обязательный фильтр `filter[iblockId]`. Запрос отклоняется до обращения к Битрикс24 — сообщение содержит имя недостающего поля и пример вызова | | 400 | `UNKNOWN_FILTER_FIELD` | Неизвестное поле фильтра или поле даты: `dateCreate`, `timestampX`, `dateActiveFrom`, `dateActiveTo`. Сообщение содержит список доступных полей | | 400 | `UNKNOWN_SORT_FIELD` | Сортировка по полю, которого нет у услуги. Сообщение содержит список доступных полей | | 400 | `UNKNOWN_SELECT_FIELD` | В `select` передано имя, которого нет у услуги. Сообщение содержит список доступных полей | | 400 | `SELECT_FIELD_NOT_RETURNED` | В `select` передано `iblockSection` — это имя в выборке не поддерживается. Основной раздел приходит в `iblockSectionId` | | 422 | `BITRIX_ERROR` | В `select` нет `iblockId` (`Required select fields: iblockId`) | | 422 | `BITRIX_ERROR` | В `select` нет `id` (`Required select fields: id`) | | 422 | `BITRIX_ERROR` | В `filter[iblockId]` передан ID каталога вариаций, а не товарного каталога (`productType is not allowed for this catalog`) | | 422 | `BITRIX_ERROR` | Каталога с указанным `iblockId` нет (`iblock is not catalog`) | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `catalog` | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 429 | `RATE_LIMITED` | Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке `x-ratelimit-limit` (потолок делится на реплики). Повторите после срока из заголовка `Retry-After` | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Известные особенности **Фильтр по `type` выборку не меняет.** В ответ попадают только услуги, у каждой `type` равен `7`. Запрос с `filter[type]=1` возвращает тот же набор услуг, что и без этого фильтра, — обычные товары каталога через этот адрес не читаются. ## Смотрите также - [Создать услугу](/docs/entities/catalog-services/create) - [Получить услугу](/docs/entities/catalog-services/get) - [Поиск услуг](/docs/entities/catalog-services/search) - [Поля услуги](/docs/entities/catalog-services/fields) - [Разделы каталога](/docs/entities/catalog-sections) - [Синтаксис фильтрации](/docs/filtering) - [Справочник API](/docs/api-reference)