Карточки товаров

Методов в разделе: 6. Все методы

Метод	Путь	Описание	Области	Статус
GET	`/cards`	Список карточек	`cards:read`	Доступно
POST	`/cards`	Создать карточку	`cards:write`	Доступно
GET	`/cards/{code}`	Получить карточку	`cards:read`	Доступно
PATCH	`/cards/{code}`	Изменить карточку	`cards:write`	Доступно
DELETE	`/cards/{code}`	Удалить карточку	`cards:write`	Доступно
POST	`/conversations/{id}/cards`	Отправить карточки в диалог	`conversations:write`	Доступно ПДн

GET /cards Доступно

#Список карточек

Карточки товаров аккаунта в порядке sort, затем создания. ai_enabled=true|false — только доступные (или недоступные) ИИ-продажнику.

Области: cards:read
Предел частоты: чтение
Идемпотентность: не требуется
Успешный ответ: 200 Страница карточек.

Параметры

Поле	Тип	Описание
`limit`	integer необязательное	Где: query. Размер страницы, 1–100, по умолчанию 50.
`cursor`	string необязательное	Где: query. Значение next_cursor из предыдущего ответа. Живёт 24 часа; при смене фильтров начинайте заново.
`ai_enabled`	boolean необязательное	Где: query. Фильтр по доступности ИИ-продажнику.

Тело ответа

Поле	Тип	Описание
`data`	array<Card> обязательное
`next_cursor`	string обязательное, может быть null	Курсор следующей страницы; null — список закончился. Живёт 24 часа.

Примеры

Запрос

curl -X GET 'https://formula-cream.pro/api/public/v1/cards' \
  -H 'Authorization: Bearer '"$API_KEY"

Ответ 200

{
  "data": [
    {
      "id": "EXAMPLE_ID",
      "code": "string",
      "name": "string",
      "description": null,
      "image_url": null,
      "price_text": null,
      "badge": null,
      "page_url": null,
      "buttons": [
        null
      ],
      "ai_enabled": false,
      "sort": 0,
      "active": false,
      "created_at": "2026-10-11T09:00:00Z",
      "updated_at": "2026-10-11T09:00:00Z"
    }
  ],
  "next_cursor": "EXAMPLE_CURSOR"
}

Пример ошибки

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

POST /cards Доступно

#Создать карточку

Создаёт товар с карточкой. Код занят — validation_failed на /code. Адреса — только https:// или путь вашего сайта («/…»): javascript:, data:, http: и чужой путь хранилища отвергаются (validation_failed).

Области: cards:write
Предел частоты: запись
Идемпотентность: обязателен Idempotency-Key
Успешный ответ: 201 Карточка.

Параметры

Поле	Тип	Описание
`Idempotency-Key`	string обязательное	Где: header. Уникальная строка (обычно UUID v4), новая для каждой новой операции. Повтор с тем же ключом и телом даёт тот же результат.

Тело запроса Карточка.

Поле	Тип	Описание
`code`	string обязательное	Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код].
`name`	string обязательное	Название. До 120 знаков.
`description`	string необязательное, может быть null	Описание. До 500 знаков.
`image_url`	string необязательное, может быть null	Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта.
`page_url`	string необязательное, может быть null	Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта).
`badge`	string необязательное, может быть null	Плашка («Хит»). До 30 знаков.
`price_text`	string необязательное, может быть null	Цена текстом. До 40 знаков.
`buttons`	array<CardButton> необязательное	До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url.
`ai_enabled`	boolean необязательное	Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код.
`sort`	integer необязательное	Порядок в каталоге продажника и выборе оператора (по возрастанию).
`active`	boolean необязательное	Товар активен; неактивную карточку нельзя отправить.

Тело ответа

Поле	Тип	Описание
`id`	string обязательное	Идентификатор товара.
`code`	string обязательное	Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код].
`name`	string обязательное	Название. До 120 знаков.
`description`	string обязательное, может быть null	Описание. До 500 знаков.
`image_url`	string обязательное, может быть null	Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта.
`price_text`	string обязательное, может быть null	Цена текстом; не задана — из цены и валюты товара; null — цены нет.
`badge`	string обязательное, может быть null	Плашка («Хит»). До 30 знаков.
`page_url`	string обязательное, может быть null	Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта).
`buttons`	array<CardButton> обязательное	До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url.
`ai_enabled`	boolean обязательное	Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код.
`sort`	integer обязательное	Порядок в каталоге продажника и выборе оператора (по возрастанию).
`active`	boolean обязательное	Товар активен; неактивную карточку нельзя отправить.
`created_at`	string обязательное	ISO 8601 UTC.
`updated_at`	string обязательное	ISO 8601 UTC.

Примеры

Запрос

curl -X POST 'https://formula-cream.pro/api/public/v1/cards' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Idempotency-Key: '"$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "string",
  "name": "string",
  "description": "string",
  "image_url": "https://example.com/hooks/sapport",
  "page_url": "https://example.com/hooks/sapport",
  "badge": "string",
  "price_text": "string",
  "buttons": [
    {
      "label": "string",
      "url": "https://example.com/hooks/sapport"
    }
  ],
  "ai_enabled": false,
  "sort": 0,
  "active": false
}'

Ответ 201

{
  "id": "EXAMPLE_ID",
  "code": "string",
  "name": "string",
  "description": "string",
  "image_url": "https://example.com/hooks/sapport",
  "price_text": "string",
  "badge": "string",
  "page_url": "https://example.com/hooks/sapport",
  "buttons": [
    {
      "label": "string",
      "url": "https://example.com/hooks/sapport"
    }
  ],
  "ai_enabled": false,
  "sort": 0,
  "active": false,
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z"
}

Пример ошибки

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing bad_request validation_failed payload_too_large idempotency_key_required idempotency_conflict operation_in_progress

GET /cards/{code} Доступно

#Получить карточку

Карточка по коду. Чужая или несуществующая — not_found.

Области: cards:read
Предел частоты: чтение
Идемпотентность: не требуется
Успешный ответ: 200 Карточка.

Параметры

Поле	Тип	Описание
`code`	string обязательное	Где: path. Код карточки.

Тело ответа

Поле	Тип	Описание
`id`	string обязательное	Идентификатор товара.
`code`	string обязательное	Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код].
`name`	string обязательное	Название. До 120 знаков.
`description`	string обязательное, может быть null	Описание. До 500 знаков.
`image_url`	string обязательное, может быть null	Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта.
`price_text`	string обязательное, может быть null	Цена текстом; не задана — из цены и валюты товара; null — цены нет.
`badge`	string обязательное, может быть null	Плашка («Хит»). До 30 знаков.
`page_url`	string обязательное, может быть null	Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта).
`buttons`	array<CardButton> обязательное	До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url.
`ai_enabled`	boolean обязательное	Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код.
`sort`	integer обязательное	Порядок в каталоге продажника и выборе оператора (по возрастанию).
`active`	boolean обязательное	Товар активен; неактивную карточку нельзя отправить.
`created_at`	string обязательное	ISO 8601 UTC.
`updated_at`	string обязательное	ISO 8601 UTC.

Примеры

Запрос

curl -X GET 'https://formula-cream.pro/api/public/v1/cards/EXAMPLE_ID' \
  -H 'Authorization: Bearer '"$API_KEY"

Ответ 200

{
  "id": "EXAMPLE_ID",
  "code": "string",
  "name": "string",
  "description": "string",
  "image_url": "https://example.com/hooks/sapport",
  "price_text": "string",
  "badge": "string",
  "page_url": "https://example.com/hooks/sapport",
  "buttons": [
    {
      "label": "string",
      "url": "https://example.com/hooks/sapport"
    }
  ],
  "ai_enabled": false,
  "sort": 0,
  "active": false,
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z"
}

Пример ошибки

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

PATCH /cards/{code} Доступно

#Изменить карточку

Меняет переданные поля; передайте хотя бы одно. Уже отправленные сообщения не меняются — в них копия карточки. Адреса — только https:// или путь вашего сайта («/…»): javascript:, data:, http: и чужой путь хранилища отвергаются (validation_failed).

Области: cards:write
Предел частоты: запись
Идемпотентность: не требуется
Успешный ответ: 200 Карточка после правки.

Параметры

Поле	Тип	Описание
`code`	string обязательное	Где: path. Код карточки.

Тело запроса Изменяемые поля.

Поле	Тип	Описание
`code`	string необязательное	Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код].
`name`	string необязательное	Название. До 120 знаков.
`description`	string необязательное, может быть null	Описание. До 500 знаков.
`image_url`	string необязательное, может быть null	Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта.
`page_url`	string необязательное, может быть null	Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта).
`badge`	string необязательное, может быть null	Плашка («Хит»). До 30 знаков.
`price_text`	string необязательное, может быть null	Цена текстом. До 40 знаков.
`buttons`	array<CardButton> необязательное	До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url.
`ai_enabled`	boolean необязательное	Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код.
`sort`	integer необязательное	Порядок в каталоге продажника и выборе оператора (по возрастанию).
`active`	boolean необязательное	Товар активен; неактивную карточку нельзя отправить.

Тело ответа

Поле	Тип	Описание
`id`	string обязательное	Идентификатор товара.
`code`	string обязательное	Код карточки, уникален в аккаунте: строчные латинские буквы, цифры, «_» и «-», до 40 знаков. ИИ-продажник ставит в ответ маркер [CARD:код].
`name`	string обязательное	Название. До 120 знаков.
`description`	string обязательное, может быть null	Описание. До 500 знаков.
`image_url`	string обязательное, может быть null	Картинка: https:// или путь файла, загруженного в хранилище вашего аккаунта.
`price_text`	string обязательное, может быть null	Цена текстом; не задана — из цены и валюты товара; null — цены нет.
`badge`	string обязательное, может быть null	Плашка («Хит»). До 30 знаков.
`page_url`	string обязательное, может быть null	Страница товара. Только https:// или путь вашего сайта, начинающийся с «/» (разворачивается по основному домену аккаунта).
`buttons`	array<CardButton> обязательное	До 3 кнопок. Пусто — одна кнопка «Подробнее» на page_url.
`ai_enabled`	boolean обязательное	Карточка доступна ИИ-продажнику: код, название и цена попадают в его каталог. Нужен код.
`sort`	integer обязательное	Порядок в каталоге продажника и выборе оператора (по возрастанию).
`active`	boolean обязательное	Товар активен; неактивную карточку нельзя отправить.
`created_at`	string обязательное	ISO 8601 UTC.
`updated_at`	string обязательное	ISO 8601 UTC.

Примеры

Запрос

curl -X PATCH 'https://formula-cream.pro/api/public/v1/cards/EXAMPLE_ID' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "code": "string",
  "name": "string",
  "description": "string",
  "image_url": "https://example.com/hooks/sapport",
  "page_url": "https://example.com/hooks/sapport",
  "badge": "string",
  "price_text": "string",
  "buttons": [
    {
      "label": "string",
      "url": "https://example.com/hooks/sapport"
    }
  ],
  "ai_enabled": false,
  "sort": 0,
  "active": false
}'

Ответ 200

{
  "id": "EXAMPLE_ID",
  "code": "string",
  "name": "string",
  "description": "string",
  "image_url": "https://example.com/hooks/sapport",
  "price_text": "string",
  "badge": "string",
  "page_url": "https://example.com/hooks/sapport",
  "buttons": [
    {
      "label": "string",
      "url": "https://example.com/hooks/sapport"
    }
  ],
  "ai_enabled": false,
  "sort": 0,
  "active": false,
  "created_at": "2026-10-11T09:00:00Z",
  "updated_at": "2026-10-11T09:00:00Z"
}

Пример ошибки

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing not_found bad_request validation_failed payload_too_large

DELETE /cards/{code} Доступно

#Удалить карточку

Снимает карточку с товара (код, картинка, кнопки, доступ продажнику); сам товар остаётся. Повтор — not_found.

Области: cards:write
Предел частоты: запись
Идемпотентность: не требуется
Успешный ответ: 204 Карточка снята; тела нет.

Параметры

Поле	Тип	Описание
`code`	string обязательное	Где: path. Код карточки.

Примеры

Запрос

curl -X DELETE 'https://formula-cream.pro/api/public/v1/cards/EXAMPLE_ID' \
  -H 'Authorization: Bearer '"$API_KEY"

Ответ 204

HTTP/1.1 204

Пример ошибки

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

POST /conversations/{id}/cards Доступно ПДн

#Отправить карточки в диалог

Сообщение оператора с карточками (копия на момент отправки, адреса развёрнуты). Канал интеграции получает событие message.created; виджет сайта показывает карточки; Telegram, VK и Max — своим форматом; прочие каналы — текстом. Неизвестный или неактивный код — validation_failed на /codes. Диалог другого арендатора, кабинета ученика или личного ящика — not_found. Повтор того же Idempotency-Key — то же сообщение.

Области: conversations:write
Предел частоты: запись
Идемпотентность: обязателен Idempotency-Key
Успешный ответ: 201 Сообщение записано.

Параметры

Поле	Тип	Описание
`id`	string обязательное	Где: path. Идентификатор диалога.
`Idempotency-Key`	string обязательное	Где: header. Уникальная строка (обычно UUID v4), новая для каждой новой операции. Повтор с тем же ключом и телом даёт тот же результат.

Тело запроса Коды карточек и комментарий.

Поле	Тип	Описание
`codes`	array<string> обязательное	Коды карточек, 1–3.
`comment`	string необязательное, может быть null	Текст над карточками, до 1000 знаков.

Тело ответа

Поле	Тип	Описание
`message_id`	string обязательное	Идентификатор сообщения с карточками.
`conversation_id`	string обязательное
`created_at`	string обязательное	ISO 8601 UTC.
`cards`	array<MessageCard> обязательное
`delivery`	string обязательное	Как карточки доходят до клиента: metadata — виджет сайта и канал интеграции (событие message.created); native — Telegram, VK, Max своим форматом; text — строками «название — цена — ссылка». Значения: `metadata` `native` `text`
`status`	string обязательное	Состояние доставки в канал. Значения: `sent` `delivered` `failed`

Примеры

Запрос

curl -X POST 'https://formula-cream.pro/api/public/v1/conversations/EXAMPLE_ID/cards' \
  -H 'Authorization: Bearer '"$API_KEY" \
  -H 'Idempotency-Key: '"$(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{
  "codes": [
    "string"
  ],
  "comment": "string"
}'

Ответ 201

{
  "message_id": "EXAMPLE_ID",
  "conversation_id": "EXAMPLE_ID",
  "created_at": "2026-10-11T09:00:00Z",
  "cards": [
    {
      "code": "string",
      "name": "string",
      "description": null,
      "image_url": null,
      "price_text": null,
      "badge": null,
      "page_url": null,
      "buttons": [
        null
      ]
    }
  ],
  "delivery": "metadata",
  "status": "sent"
}

Пример ошибки

{
  "type": "https://formula-cream.pro/developers/errors#scope_missing",
  "title": "Scope is missing",
  "status": 403,
  "code": "scope_missing",
  "detail": "EXAMPLE",
  "request_id": "req_EXAMPLE"
}

Примеры иллюстративны: ключ в них условный (EXAMPLE), значения полей выдуманы.

Возможные ошибки

invalid_api_key wrong_cell integration_inactive tenant_inactive ip_not_allowed feature_not_in_plan rate_limited wallet_suspended service_unavailable internal_error scope_missing pii_transfer_not_allowed not_found bad_request validation_failed payload_too_large idempotency_key_required idempotency_conflict operation_in_progress

Начало

Чаты и ИИ-продажник

Аналитика и дашборды

CRM и лиды

Статьи

Стратег

Дополнительно

Шаблоны и примеры

Справочник API

Карточки товаров

#Список карточек

Параметры

Тело ответа

Примеры

Возможные ошибки

#Создать карточку

Параметры

Тело запроса Карточка.

Тело ответа

Примеры

Возможные ошибки

#Получить карточку

Параметры

Тело ответа

Примеры

Возможные ошибки

#Изменить карточку

Параметры

Тело запроса Изменяемые поля.

Тело ответа

Примеры

Возможные ошибки

#Удалить карточку

Параметры

Примеры

Возможные ошибки

#Отправить карточки в диалог

Параметры

Тело запроса Коды карточек и комментарий.

Тело ответа

Примеры

Возможные ошибки