Разработчикам

API генерации карточек

REST API для тарифа «Бизнес»: генерируйте карточки Wildberries, Ozon, Яндекс Маркета и Lamoda из своего кода — каталогом, по расписанию, из таблиц или PIM. Один вызов = одна карточка: заголовки под лимиты площадки, описание, SEO-ядро, характеристики и rich-контент. Документация собрана из живого кода сервиса — квоты и языки ниже совпадают с тем, что проверяет сервер.

Токен — в «Профиле»

Раздел «API-токены»: создание, маскированный список и отзыв. Тариф «Бизнес», до 5 активных токенов.

Квота — 500 генераций в месяц

Счётчик API отдельен от веб-генераций и обнуляется 1-го числа месяца. Ответ 429 предупредит заранее.

Быстрый старт

Создайте токен в профиле и повторите пример — ответ вернёт готовую карточку. Тело запроса — обычный JSON.

curl -X POST https://mp-kartochka.ru/api/v1/generate \
  -H "Authorization: Bearer cp_ВАШ_ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "productName": "Термокружка 450 мл стальная",
    "features": "держит тепло 8 часов, сталь 304, не потеет, крышка с блокировкой",
    "category": "Посуда",
    "audience": "офис и дорога",
    "tone": "expert",
    "marketplace": "wb",
    "language": "ru"
  }'

То же на Node.js (обработка ошибок и квот):

const res = await fetch("https://mp-kartochka.ru/api/v1/generate", {
  method: "POST",
  headers: {
    Authorization: "Bearer " + process.env.KARTOCHKA_TOKEN,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    productName: "Термокружка 450 мл стальная",
    features: "держит тепло 8 часов, сталь 304, не потеет",
    marketplace: "ozon",
    language: "ru",
  }),
});

if (!res.ok) {
  // 402 — нет подписки «Бизнес» или генераций на балансе
  // 429 — месячная квота API исчерпана
  throw new Error(`API ${res.status}: ${await res.text()}`);
}

const { card, balance, usedSubscription } = await res.json();
console.log(card.title, card.description, balance);

Аутентификация

Каждый запрос несёт заголовок Authorization: Bearer cp_.... Токен начинается с cp_, показывается полностью один раз при создании и дальше — только маской. Действует, пока активна подписка «Бизнес»; отзыв — мгновенный. Передавайте токен только по HTTPS и не коммитьте в репозиторий.

POST /api/v1/generate

Генерация карточки. Обязательных поля два — остальное подсказывает сервис умолчаниями.

productName: string · обязательно

Название товара. Минимум 3 символа — уходит в промпт как основа карточки.

features: string · обязательно

Особенности товара списком или текстом. Минимум 5 символов. Чем конкретнее — тем точнее карточка.

category: string

Категория товара. По умолчанию — «Другое».

audience: string

Целевая аудитория — кто покупает и зачем. Уточняет тон описания.

tone: string

Тон подачи: expert · friendly · emotional · premium · minimal. По умолчанию expert.

descLength: string

Объём описания: short · standard · max. По умолчанию standard.

marketplace: string

Площадка: wb · ozon · yandex · lamoda — под её лимиты и правила. По умолчанию wb.

language: string

Язык карточки (локальные рынки и экспорт). По умолчанию ru.

analyzeCompetitors: boolean

true — перед генерацией проанализировать выдачу конкурентов и учесть разрывы в карточке.

marketplace

wbozonyandexlamoda

Wildberries · Ozon · Яндекс Маркет · Lamoda

language

rukkbeuzen

Русский (РФ) · Қазақша (Казахстан) · Беларуская (Беларусь) · Oʻzbekcha (Oʻzbekiston) · English (Ozon Global / экспорт) — цена генерации не меняется.

Ответ 200

Три поля: card — карточка целиком, balance — остаток генераций на балансе, usedSubscription — списана ли подписочная генерация (приоритет: квота подписки → баланс). Поля карточки:

id

Идентификатор карточки (cuid) — пригодится в веб-интерфейсе и галерее.

title / titleShort

Полный заголовок и короткий (под лимит площадки, например 60 символов WB).

titleVariants

JSON-строка: массив альтернативных заголовков для A/B.

description

Продающее описание товара — основной текст карточки.

keywords

JSON-строка: массив поисковых запросов (SEO-ядро) под выбранную площадку и язык.

characteristics

JSON-строка: массив характеристик {name, value} для полей площадки.

richContent

JSON-строка: массив rich-блоков {type: text|image|video, title, text, url?} — расширенное описание Ozon/ЯМ.

marketplace / language

Площадка и язык, под которые собрана карточка.

createdAt

Время создания (ISO 8601).

JSON-строки (titleVariants, keywords, characteristics, richContent) — сериализованные массивы: распарсьте их на своей стороне. Это сделано, чтобы ответ оставался плоским и предсказуемым для типизации.

Коды ошибок

400

Некорректный JSON, productName короче 3 символов или features короче 5.

401

Токен не передан, недействителен или отозван. Формат: Authorization: Bearer cp_...

402

Подписка «Бизнес» не активна — или на балансе нет генераций (INSUFFICIENT_BALANCE).

429

Исчерпана месячная квота API: 500 генераций. Обнулится 1-го числа следующего месяца.

500

Внутренняя ошибка сервиса — повторите вызов позже.

502

ИИ-провайдер не ответил (AI_ERROR). Средства за попытку не списываются.

Квоты и лимиты

Управление токенами

Те же учётные данные сайта (не API-токен, а обычная сессия профиля):

GET /api/api-tokens

Список своих токенов: id, метка, маска вида cp_ab12••••••••wxyz, время последнего использования.

POST /api/api-tokens {"label"}

Создать токен (метка до 40 символов). Полный токен возвращается один раз — сохраните сразу. Требует активной подписки «Бизнес», иначе 402.

DELETE /api/api-tokens?id=...

Отозвать токен — мгновенно и необратимо; интеграция начнёт получать 401.

О чём договоримся заранее

Нужен батч-эндпоинт под ваш PIM, webhook или лимиты под объём? Напишите в поддержку из раздела «Профиль» — обсудим.