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

Добавить карточку с HTML

POST /v1/pages/:pageId/blocks/:blockId/cards

Добавляет в набор карточек блока новую карточку со своей разметкой.

Параметры

Параметр Тип Обяз. Описание
ПараметрpageId (path) Типnumber Обяз.да ОписаниеID страницы. Список: GET /v1/pages
ПараметрblockId (path) Типnumber Обяз.да ОписаниеID блока этой страницы. Список: GET /v1/pages/:pageId/blocks. Блок другой страницы отвечает 404
Параметрscope (query) Типstring Обяз.нет ОписаниеВнутренняя область лендингов: KNOWLEDGE — база знаний, GROUP — база знаний группы, MAINPAGE — главная страница. Для обычного сайта не передаётся

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

Поле Тип Обяз. Описание
Полеselector Типstring Обяз.да ОписаниеСелектор набора карточек с индексом образца: .landing-block-card@0 — новая карточка встанет после первой. Селекторы наборов — ключи объекта cards в ответе GET /v1/pages/:pageId/blocks/:blockId/content. Без @N новая карточка встаёт в начало набора, на позицию 0
Полеcontent Типstring Обяз.да ОписаниеHTML новой карточки. У корневого элемента — класс набора, внутри — те же классы узлов, что у карточек блока: по этим классам карточку находят следующие вызовы. Разметка проходит очистку: теги <script> обезвреживаются

Примеры

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/pages/42/blocks/50/cards" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"selector":".landing-block-card@0","content":"<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}'

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

Terminal
curl -X POST "https://vibecode.bitrix24.tech/v1/pages/42/blocks/50/cards" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"selector":".landing-block-card@0","content":"<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}'

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

javascript
const response = await fetch("https://vibecode.bitrix24.tech/v1/pages/42/blocks/50/cards", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
  body: JSON.stringify({"selector": ".landing-block-card@0", "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

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

javascript
const response = await fetch("https://vibecode.bitrix24.tech/v1/pages/42/blocks/50/cards", {
  method: "POST",
  headers: {"X-Api-Key": "YOUR_APP_KEY", "Authorization": "Bearer USER_SESSION_TOKEN", "Content-Type": "application/json"},
  body: JSON.stringify({"selector": ".landing-block-card@0", "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"}),
})
const result = await response.json()
if (!response.ok) throw new Error(result.error.message)
console.log(result.data)

Поля ответа

Поле Тип Описание
Полеsuccess Типboolean ОписаниеВсегда true при успехе
Полеdata.cards Типobject ОписаниеКарточки блока после записи. Ключ — селектор набора, значение — массив карточек набора по порядку
Полеdata.cards.<селектор>[].index Типnumber ОписаниеТекущая позиция карточки в наборе, с нуля. Это и есть N в @N для следующего вызова
Полеdata.cards.<селектор>[].content Типstring ОписаниеHTML карточки после очистки

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

В блоке были карточки First и Second. Новая карточка встала после первой, на позицию 1:

JSON
{
  "success": true,
  "data": {
    "cards": {
      ".landing-block-card": [
        {
          "index": 0,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">First</h3></div>"
        },
        {
          "index": 1,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Example</h3></div>"
        },
        {
          "index": 2,
          "content": "<div class=\"landing-block-card\"><h3 class=\"landing-block-node-title\">Second</h3></div>"
        }
      ]
    }
  }
}

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

400 — не передан content или передана пустая строка:

JSON
{
  "success": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELDS",
    "message": "content must be non-empty HTML."
  }
}

Ошибки

HTTP Код Описание
HTTP400 КодMISSING_REQUIRED_FIELDS Описаниеcontent must be non-empty HTML. — не передан content или он состоит из пробелов
HTTP400 КодMISSING_REQUIRED_FIELDS Описаниеselector is required. — не передан selector, передана пустая строка или строка из пробелов
HTTP404 КодENTITY_NOT_FOUND ОписаниеPage, block or card not found. — блок не принадлежит странице pageId, в блоке нет набора с таким селектором или в наборе нет карточки с индексом @N. Тот же ответ, если блок не существует
HTTP400 КодINVALID_PARAMS Описаниеselector index must be a non-negative safe integer. — после @ стоит не целое неотрицательное число, в селекторе больше одного @ или перед @ пусто
HTTP400 КодINVALID_PARAMS ОписаниеpageId and blockId must be positive safe integers. — pageId или blockId не является положительным целым числом
HTTP400 КодINVALID_PARAMS ОписаниеBody must be a JSON object. — тело не является JSON-объектом
HTTP400 КодINVALID_PARAMS ОписаниеBody contains an unsupported field. — в теле есть поле кроме selector и content
HTTP400 КодINVALID_SCOPE Описаниеscope не равен KNOWLEDGE, GROUP или MAINPAGE
HTTP422 КодBITRIX_NO_EFFECT ОписаниеBitrix24 did not confirm the card action. — Битрикс24 не подтвердил запись
HTTP422 КодBITRIX_NO_EFFECT ОписаниеBitrix24 did not return cards after the action. — после записи Битрикс24 не вернул содержимое блока
HTTP422 КодBITRIX_NO_EFFECT ОписаниеBitrix24 did not persist the requested card count. — разметка блока после записи не изменилась
HTTP422 КодBITRIX_ERROR ОписаниеБитрикс24 отклонил действие. Текст ошибки приходит от Битрикс24
HTTP502 КодBITRIX_ERROR ОписаниеBitrix24 returned invalid or oversized card content. — разметка блока не разбирается или карточки занимают больше 8 МиБ
HTTP403 КодSCOPE_DENIED ОписаниеAPI-ключ не имеет скоупа landing
HTTP403 КодWRITE_BLOCKED_READONLY_KEY ОписаниеКлюч работает в режиме «только чтение», запрос отклонён до обращения к Битрикс24
HTTP403 КодBITRIX_ACCESS_DENIED ОписаниеУ пользователя Битрикс24, от имени которого выпущен ключ, нет прав на изменение страницы
HTTP401 КодMISSING_API_KEY ОписаниеНе передан заголовок X-Api-Key
HTTP401 КодINVALID_API_KEY ОписаниеКлюч в X-Api-Key не найден или отозван
HTTP401 КодTOKEN_MISSING ОписаниеAPI-ключ не имеет настроенных токенов
HTTP409 КодLANDING_MODULE_NOT_ENABLED ОписаниеМодуль «Сайты» недоступен на портале
HTTP409 КодPORTAL_ADDRESS_CHANGED ОписаниеКоробочный Битрикс24 переехал на новый адрес, а вебхук ключа выписан на прежний. Выпустите вебхук ключа заново
HTTP429 КодRATE_LIMITED ОписаниеПревышен лимит запросов к Битрикс24. Повторите запрос через 1-2 секунды
HTTP502 КодBITRIX_UNAVAILABLE ОписаниеБитрикс24 не ответил или ответил ошибкой сервера
HTTP503 КодBITRIX_TIMEOUT ОписаниеБитрикс24 не ответил за отведённое время

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

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

  • Индексы сдвигаются после каждой записи. Карточки не имеют постоянного ID: N в @N — позиция в наборе на момент вызова. Перед следующей операцией берите индексы из data.cards последнего ответа.
  • Отказ после записи не отменяет добавление. Ответы 422, 502 и 503 не означают, что карточка не добавлена. Прежде чем повторить вызов, перечитайте блок через GET /v1/pages/:pageId/blocks/:blockId/content: повтор может добавить ещё одну карточку.
  • Ответ читается из черновика. Карточки в ответе берутся из черновика страницы, включая неопубликованные правки.

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