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

Список отделов

GET /v1/departments

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

Параметры

Параметр Тип По умолч. Описание
limit number 50 Количество записей (до 5000). При limit > 50 запрос автоматически собирается из нескольких страниц на стороне сервера
select string — Выборка полей: ?select=id,name. Возвращаются только перечисленные поля
filter object — Только точное равенство и $in (IN-множество) по полям id, name, parentId, headId. Операторы (>, >=, <, <=, !, %, $ne, $contains, $nin) и другие поля не поддерживаются — вернётся 400 UNSUPPORTED_FILTER.
Синтаксис фильтрации. Пример: ?filter[parentId]=1

Примеры

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/departments?filter[parentId]=1" \
  -H "X-Api-Key: YOUR_API_KEY"

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/departments?filter[parentId]=1" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/departments?filter[parentId]=1', {
  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/departments?filter[parentId]=1', {
  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 Общее количество записей, соответствующих фильтру
meta.hasMore boolean Есть ли ещё записи за пределами limit

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 47,
      "name": "Коммерческий отдел",
      "sort": 500,
      "parentId": 1,
      "headId": 99
    },
    {
      "id": 107,
      "name": "Отдел разработки",
      "sort": 600,
      "parentId": 1,
      "headId": 1
    }
  ],
  "meta": {
    "total": 2,
    "hasMore": false
  }
}

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

400 — оператор или неподдерживаемое поле в фильтре:

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: 'sort' is not filterable on 'departments'. Its Bitrix24 method (department.get) filters by exact match only. Filterable: id, name, parentId, headId."
  }
}

Ошибки

HTTP Код Описание
400 UNSUPPORTED_FILTER Оператор или неподдерживаемое поле в фильтре. Фильтруйте точным равенством или $in по id, name, parentId, headId
403 SCOPE_DENIED API-ключ не имеет скоупа department
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Сортировка не поддерживается; offset работает построчно. Параметр order / sort отклоняется с ошибкой 400 INVALID_SORT_FIELD — метод Битрикс24 department.get не принимает порядок сортировки; для упорядочивания отсортируйте выборку на стороне клиента. Параметр offset считается по записям: offset=7 начинает выборку с 8-го департамента. Битрикс24 отдаёт результат страницами по 50, поэтому Vibe запрашивает страницу, покрывающую нужную позицию, и отбрасывает лишнее начало. При limit > 50 Vibe сам собирает нужные страницы (см. параметр limit выше), поэтому весь список департаментов загружается одним запросом без ручной постраничной навигации.

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

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