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

POST /v1/departments/search

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

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

Параметр Тип По умолч. Описание
filter object — Фильтрация по полям GET /v1/departments/fields.
Синтаксис фильтрации. Пример: { "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

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

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
  }
}

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

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'department' scope"
  }
}

#Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа department
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Параметры order и offset не применяются. Поле order в теле запроса принимается без ошибки, но порядок результата не меняется. Поле offset тоже принимается, но всегда возвращается выборка с начала. Для больших порталов запрашивайте всю выборку фильтра и сортируйте на стороне клиента.

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