Для 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 — личный ключ
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-приложение
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 — личный ключ
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-приложение
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:
{
"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 или передана пустая строка:
{
"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: повтор может добавить ещё одну карточку. - Ответ читается из черновика. Карточки в ответе берутся из черновика страницы, включая неопубликованные правки.