Поля страницы

GET /v1/pages/fields

Возвращает карту всех полей страницы с типом, подписью и признаком только для чтения, а у полей, которые могут прийти пустыми, — с признаком nullable. Поля без признака только для чтения доступны для записи при создании и обновлении.

Примеры

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

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

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

curl "https://vibecode.bitrix24.tech/v1/pages/fields" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

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

const res = await fetch('https://vibecode.bitrix24.tech/v1/pages/fields', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Полей:', Object.keys(data.fields).length)

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

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

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

Поля ответа

Объект data содержит карту fields (имя поля → { type, readonly, label }, у части полей есть ещё description, а у полей, которые могут прийти пустыми, — nullable), список batch с операциями массового режима, список доступных include и набор aggregatable полей для группировки в агрегации.

Поля, которые могут быть пустыми

У поля, которое Битрикс24 не всегда заполняет, в ответе эндпоинта стоит "nullable": true, а в таблице выше тип записан как … | null. Таких полей девять: description, xmlId, tplId, tplCode, folderId, searchContent, initiatorAppCode, rule, datePublic. Значение приходит как null — не как пустая строка и не как 0, — поэтому проверяйте его перед разбором. У остальных полей значение есть всегда.

Формат дат

Даты — строки в формате локали портала, НЕ ISO 8601. dateCreate, dateModify и datePublic Битрикс24 отдаёт строкой, и конкретный шаблон зависит от региональных настроек портала: на RU-локали это ДД.ММ.ГГГГ ЧЧ:ММ:СС (30.12.2021 12:30:52), на EN-локали — MM/DD/YYYY hh:mm:ss am/pm (12/30/2021 12:30:52 pm). Вайбкод отдаёт значение как есть, без приведения к ISO, одинаково в списке и в карточке — расхождения между GET /v1/pages и GET /v1/pages/:id нет. new Date(value) вернёт Invalid Date либо тихо перепутает день и месяц: не разбирайте дату по фиксированному шаблону и не доверяйте new Date(). Тот же формат нужен и в фильтре — см. Поиск страниц.

Доступные include

Эндпоинт возвращает список доступных include: site — сайт-владелец страницы. Подробнее: Связанные данные.

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

Каждое поле, помимо type и readonly, содержит label (короткое название) и description (пояснение) на русском языке. Заголовками запроса язык не переключается. У поля, которое может прийти пустым, дополнительно стоит nullable. В примере ниже description показан только у active — у остальных полей он опущен для краткости.

{
  "success": true,
  "data": {
    "fields": {
      "id": { "type": "number", "readonly": true, "label": "ID страницы" },
      "title": { "type": "string", "readonly": false, "label": "Название" },
      "siteId": { "type": "number", "readonly": false, "label": "ID сайта" },
      "active": {
        "type": "boolean",
        "readonly": true,
        "label": "Активна",
        "description": "Опубликована ли страница. Только для чтения: Битрикс24 не принимает поле ни на создании, ни на обновлении, а новая страница всегда создаётся неактивной. Публикация через POST /v1/pages/:id/publication и снятие с публикации через POST /v1/pages/:id/unpublish."
      },
      "xmlId": { "type": "string", "readonly": false, "nullable": true, "label": "Внешний идентификатор" },
      "datePublic": { "type": "datetime", "readonly": true, "nullable": true, "label": "Дата публикации" }
    },
    "relations": {
      "site": { "type": "one", "entity": "site", "includable": true }
    },
    "aggregatable": ["siteId", "active", "deleted", "public", "folderId", "tplId", "createdById", "modifiedById"],
    "batch": ["create", "update", "delete"],
    "include": ["site"]
  }
}

Показаны 6 из 27 полей. Полный список — в таблице выше.

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

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

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

Ошибки

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

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

• Создать страницу
• Обновить страницу
• Агрегация страниц
• Страницы
• Entity API