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

Поиск отделов

POST /v1/departments/search

Поиск отделов с фильтрами. Аналог GET /v1/departments с фильтрами, но через POST — удобнее для составных запросов из нескольких условий.

Поля запроса (body)

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

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/departments/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "parentId": 1 },
    "limit": 10
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/departments/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "parentId": 1 },
    "limit": 10
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/departments/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { parentId: 1 },
    limit: 10,
  }),
})

const { success, data, meta } = await res.json()
console.log('Найдено:', meta.total)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/departments/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { parentId: 1 },
    limit: 10,
  }),
})

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

Поля ответа

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

Поля meta лежат рядом с data, а не внутри него. Обходить страницы нужно по meta.hasMore: длина data, равная 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,
    "durationMs": 252
  }
}

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

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

JSON 
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_FILTER",
    "message": "UNSUPPORTED_FILTER: operators are not supported on 'departments' (near 'id'). Its Bitrix24 method (department.get) filters by exact match only — operators are silently ignored by Bitrix24. Use exact match (field: value) or $in (field: {$in: [...]}) on: id, name, parentId, headId."
  }
}

Ошибки

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

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

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

Параметр order не применяется; offset применяется построчно. Поле order в теле запроса принимается без ошибки, но порядок результата не меняется — метод Битрикс24 department.get не принимает сортировку. Поле offset считается по записям: offset=7 вернёт выборку начиная с 8-го департамента. Порядок при этом задаёт Битрикс24, поэтому для устойчивой постраничной обработки запрашивайте всю выборку фильтра и сортируйте на стороне клиента.

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