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

Поля линии приложения

GET /v1/telephony-lines/fields

Возвращает схему полей внешней линии приложения: тип каждого поля, доступность на запись, название и описание. Схема нужна перед добавлением и обновлением линии — по ней видно, какие поля принимаются, а какие только читаются.

Примеры

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

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

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

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

const { success, data } = await res.json()
console.log('Поля линии:', Object.keys(data.fields))

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

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

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data.fields object Схема полей линии. Ключ — имя поля в camelCase, значение — его описание
data.fields.<имя>.type string Тип значения поля: string или boolean
data.fields.<имя>.readonly boolean true — поле только читается, запись отклоняется с 400 READONLY_FIELD
data.fields.<имя>.nullable boolean Присутствует у полей, которые могут прийти со значением null
data.fields.<имя>.notReturned boolean Присутствует у полей, которые объявлены в схеме, но в ответах не приходят. Явный select такого имени возвращает UNKNOWN_SELECT_FIELD
data.fields.<имя>.label string Короткое название поля
data.fields.<имя>.description string Развёрнутое описание поля
data.batch array Операции линии, доступные в пакетном вызове: create, update, delete

Схема описывает четыре поля:

Поле Тип RO Описание
number string Номер внешней линии — он же идентификатор линии в путях обновления и удаления
name string | null Название линии, отображаемое в интерфейсе. У линии, созданной без названия, приходит null
crmAutoCreate boolean Создавать ли автоматически лид или контакт по звонкам на этой линии
serverName string да Имя сервера телефонии, на котором зарегистрирована линия. В ответах не приходит, на запись отклоняется

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

JSON 
{
  "success": true,
  "data": {
    "fields": {
      "number": {
        "type": "string",
        "readonly": false,
        "label": "Номер линии",
        "description": "Номер внешней линии — идентификатор телефонной линии."
      },
      "serverName": {
        "type": "string",
        "readonly": true,
        "notReturned": true,
        "label": "Имя сервера",
        "description": "Имя сервера телефонии, на котором зарегистрирована линия. Только для чтения: Битрикс24 его не хранит и не возвращает, поэтому запись отклоняется с 400 READONLY_FIELD, а не теряется молча."
      },
      "name": {
        "type": "string",
        "readonly": false,
        "nullable": true,
        "label": "Название линии",
        "description": "Человекочитаемое название линии, отображаемое в интерфейсе. Может быть null: у линии, созданной без названия, возвращается null."
      },
      "crmAutoCreate": {
        "type": "boolean",
        "readonly": false,
        "label": "Автосоздание в CRM",
        "description": "Создавать ли автоматически сущности CRM (лид/контакт) по звонкам на этой линии."
      }
    },
    "batch": ["create", "update", "delete"]
  }
}

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

401 — не передан ключ:

JSON 
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "API key required. Pass via X-Api-Key header."
  }
}

Ошибки

HTTP Код Описание
401 MISSING_API_KEY Не передан заголовок X-Api-Key
401 INVALID_API_KEY Неверный API-ключ
401 TOKEN_MISSING Ключ не имеет настроенных токенов
401 KEY_INACTIVE API-ключ неактивен или отозван
403 SCOPE_DENIED Ключу не хватает скоупа telephony
429 RATE_LIMITED Превышен лимит запросов

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

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

Схема одинакова на всех порталах. Ответ собирается из описания линии на стороне Вайбкод, а не запрашивается у портала, поэтому набор полей и их типы не зависят от настроек конкретного портала и от доступности Битрикс24. Ответ кэшируется, источник показывает заголовок X-Cache — правила и способы обойти кэш описаны в Лимитах и оптимизации.

serverName объявлено, но не приходит. Поле есть в схеме с пометкой notReturned, и это не рассинхронизация: в ответах списка, создания и обновления его нет ни при каких условиях, а попытка записать значение отклоняется с 400 READONLY_FIELD — молчаливой потери значения не происходит. Явный select=serverName возвращает предупреждение UNKNOWN_SELECT_FIELD, а поле не попадает в ответ. Считайте его справочным описанием, а не источником данных.

batch называет доступные пакетные операции. Массив перечисляет операции линии, которые принимает пакетный вызов: create, update, delete. Чтения в этом списке нет — список линий забирается отдельным вызовом.

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