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

Поля отдела

GET /v1/departments/fields

Возвращает справочник полей отдела с типами и признаком «только для чтения», а также список операций, доступных в POST /v1/batch.

Примеры

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

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

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

Terminal 
curl "https://vibecode.bitrix24.tech/v1/departments/fields" \
  -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/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)
console.log('Доступные batch-операции:', data.batch)

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

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

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

Поля ответа

Подписи полей label и description приходят на русском языке. Заголовками запроса язык не переключается.

Поле Тип RO Описание
id number да Идентификатор отдела
name string Название отдела
parentId number ID родительского отдела. Для отдела верхнего уровня указывается 1 (виртуальный корень дерева). Источник: GET /v1/departments
headId number ID руководителя отдела. Источник: GET /v1/users. Если руководитель не назначен, приходит 0 или поле отсутствует. Может указывать на запись, которой нет в GET /v1/users, например на чат-бота, — подробнее в разделе Что нужно знать перед работой
sort number Порядок отдела среди соседей (целое число, по возрастанию)

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID", "description": "Уникальный идентификатор отдела." },
      "name": { "type": "string", "readonly": false, "label": "Название", "description": "Название отдела, отображаемое в структуре компании." },
      "parentId": { "type": "number", "readonly": false, "label": "Родительский отдел", "description": "ID родительского отдела в иерархии; для отдела верхнего уровня указывается 1 — виртуальный корень дерева." },
      "headId": { "type": "number", "readonly": false, "label": "Руководитель", "description": "ID пользователя, назначенного руководителем отдела." },
      "sort": { "type": "number", "readonly": false, "label": "Сортировка", "description": "Порядок отдела среди соседних по уровню; по умолчанию 500." }
    },
    "batch": ["create", "update", "delete"]
  }
}

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

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

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

Ошибки

HTTP Код Описание
403 SCOPE_DENIED API-ключ не имеет скоупа department
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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