Купецъмедиа

API для разработчиков

Публичный API Купецъ позволяет публиковать, редактировать и удалять посты и статьи из ваших приложений — в личную ленту/блог или в ваши каналы. Всё работает от вашего имени по API-ключу.

Авторизация

Создайте ключ в настройках → API-ключи. Ключ показывается один раз — сохраните его. Передавайте ключ в заголовке:

Authorization: Bearer adspm_XXXXXXXXXXXXXXXX

Базовый адрес всех методов: https://kupec.media/api/v1

Кто я

GET/me
Возвращает владельца ключа и профиль автора, под которым публикуется контент.
GET/me/channels
Список ваших каналов (блогов). Поле id используется как channel при публикации в канал. Если channel не указан — публикация идёт в вашу личную ленту/блог.

Публикация

POST/posts
Короткий пост в ленту или канал.
curl -X POST https://kupec.media/api/v1/posts \
  -H "Authorization: Bearer adspm_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Текст поста (HTML допустим, до 4000 знаков)",
    "title": "Необязательный заголовок",
    "image": "https://.../cover.jpg",
    "images": ["https://.../1.jpg", "https://.../2.jpg"],
    "imagesLayout": "carousel",
    "channel": "ID_канала (необязательно)",
    "status": "PUBLISHED"
  }'

Поля: text (обязательно), title, image, images (до 10), imagesLayout (carousel / grid), channel, platformId, status (PUBLISHED / DRAFT).

Разметка в text. Допустимы теги <p> <br> <strong> <b> <em> <i> <u> <s> <a> <ul> <ol> <li> <blockquote> <h2> <h3> <h4> <code> <mark>. У ссылок сохраняется только href (http, https, mailto, tel или /), остальные атрибуты и все прочие теги вырезаются. Картинки в пост — полями image/images, а не тегом <img>. Голые ссылки в тексте кликабельны автоматически, оборачивать в <a> не обязательно. Лимит — 4000 знаков без учёта тегов.

POST/articles
Полноценная статья с обложкой.
curl -X POST https://kupec.media/api/v1/articles \
  -H "Authorization: Bearer adspm_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Заголовок статьи",
    "description": "Краткое описание (для анонса и SEO)",
    "body": "<p>Полный текст статьи в HTML</p>",
    "preview": "https://.../cover.jpg",
    "tags": "таргет, аналитика",
    "readingTime": 7,
    "channel": "ID_канала (необязательно)",
    "status": "PUBLISHED"
  }'

Поля: title, description, body (обязательны), preview — обложка, tags — через запятую, readingTime (мин), channel, platformId, status.

Разметка в body. Присылайте обычный HTML: <h2> <h3> <p> <strong> <em> <a href> <ul>/<ol>/<li> <blockquote> <img src> <figure>/<figcaption> <hr> <pre>/<code>. Небезопасные теги и атрибуты (скрипты, style, обработчики) вырезаются при показе. У <img> нужен абсолютный src — либо внешний URL, либо ссылка из POST /api/v1/upload. Относительные пути и data:-URL (кроме картинок) не отображаются.

Ответ содержит id, slug, status, url — сохраните id, он нужен для редактирования и удаления.

POST/cases
Кейс: задача, что сделали, результат.
curl -X POST https://kupec.media/api/v1/cases \
  -H "Authorization: Bearer adspm_XXXX" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "52 заявки по 922 ₽ на бариатрию",
    "niche": "Медицина",
    "description": "Краткое описание для карточки",
    "task": "Что нужно было решить",
    "body": "<p>Полный текст кейса в HTML</p>",
    "result": "52 заявки, выручка 2 000 000 ₽",
    "metrics": { "Заявок": "52", "Цена лида": "922 ₽" },
    "preview": "https://.../cover.jpg",
    "screenshots": ["https://.../1.jpg"],
    "adBudget": 48000,
    "channel": "ID_канала (необязательно)",
    "status": "PUBLISHED"
  }'

Обязательны: title, niche, description, result. Остальное — body, task, metrics (произвольные пары), preview, screenshots (до 20), adBudget, channel, platformId, status.

Ответ содержит id, slug, status, url — сохраните id, он нужен для редактирования и удаления.

Один материал в сутки

Через API можно опубликовать не больше одной публикации в сутки — суммарно на пост, статью и кейс, и на все ваши ключи сразу. Вторая попытка вернёт 429 с полем Retry-After, в котором указано, сколько ждать.

Черновики в лимит не входят — создавайте с status: "DRAFT" сколько угодно. Но перевод черновика в PUBLISHED через PATCH — это тоже публикация, и она тратит ту же суточную квоту. Загрузка картинок квоту не тратит. Публикация руками через сайт лимитом не ограничена.

Картинки

Поля image/preview и теги <img> внутри body принимают URL картинки. Если файл лежит у вас локально — сначала загрузите его этим методом и подставьте полученный url.

POST/upload
Загрузить картинку (multipart/form-data, поле file). Вернёт публичный URL.
curl -X POST https://kupec.media/api/v1/upload \
  -H "Authorization: Bearer adspm_XXXX" \
  -F "file=@/path/to/photo.jpg"

Ответ: { "url": "https://.../photo.jpg", "sizes": { "lg": "...", "md": "...", "sm": "..." } }. Берёте url и кладёте в preview (обложка) или в <img src="..."> внутри body. Форматы: JPEG, PNG, WebP, GIF.

Редактирование

Передавайте только те поля, которые нужно изменить — остальные не трогаются. Адрес публикации (slug) при редактировании не меняется.

PATCH/posts/{id}
Изменить свой пост. Принимает те же поля, что и публикация поста.
curl -X PATCH https://kupec.media/api/v1/posts/POST_ID \
  -H "Authorization: Bearer adspm_XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "text": "Обновлённый текст", "status": "PUBLISHED" }'
PATCH/articles/{id}
Изменить свою статью. Принимает те же поля, что и публикация статьи.
PATCH/cases/{id}
Изменить свой кейс. Принимает те же поля, что и публикация кейса.
curl -X PATCH https://kupec.media/api/v1/articles/ARTICLE_ID \
  -H "Authorization: Bearer adspm_XXXX" \
  -H "Content-Type: application/json" \
  -d '{ "title": "Новый заголовок", "body": "<p>Новый текст</p>" }'

Удаление

DELETE/posts/{id}
Удалить свой пост.
DELETE/articles/{id}
Удалить свою статью.
DELETE/cases/{id}
Удалить свой кейс.
curl -X DELETE https://kupec.media/api/v1/articles/ARTICLE_ID \
  -H "Authorization: Bearer adspm_XXXX"

Ответ: { "ok": true, "deleted": "ID" }. Редактировать и удалять можно только свой контент — чужой или несуществующий вернёт 404.

Чтение (каталог)

Списки опубликованного контента. Поддерживают limit (до 50), offset, search, platform.

GET/articles
Список статей.
GET/cases
Список кейсов.
GET/authors
Список авторов.

Поле url в ответе — это конечный адрес материала, тот же, что стоит в canonical страницы. Его можно публиковать как есть, промежуточных перенаправлений не будет.

Управление ключами

Ключами удобнее управлять в настройках. Доступны также методы GET /keys, POST /keys, DELETE /keys/{id} (работают по сессии личного кабинета).

Ошибки и лимиты

  • 401 — ключ отсутствует или недействителен.
  • 404 — контент не найден или принадлежит не вам.
  • 400 — ошибка валидации (например, пустой текст или сработал фильтр контента).
  • 429 — исчерпан лимит: либо суточный (одна публикация в сутки), либо частотный. В обоих случаях в заголовке Retry-After указано, через сколько секунд повторять.
  • 503 — не удалось проверить суточный лимит. Это временно, повторите позже.