API для постинга в телеграм, ВКонтакте и MAX

Первый пост за три шага

1. 1

   Возьмите ключ

   Ключи доступа → «Создать ключ». Он показывается один раз и начинается с smk_ — скопируйте сразу. У нас в базе лежит только его хеш, восстановить строку нельзя: потеряли — удалите и выпустите новый.

2. 2

   Отправьте пост

   Подставьте свой ключ и ярлык канала. Ярлыки — то, чем каналы адресуются: посмотреть их можно запросом GET /api/v1/channelsили в кабинете.

   Публикация в каналы с ярлыком «новости»Скопировать

   curl -X POST https://smmly.ru/api/v1/posts \
     -H "Authorization: Bearer smk_ВАШ_КЛЮЧ" \
     -H "Content-Type: application/json" \
     -d '{
       "tags": ["новости"],
       "content": "Привезли новую обжарку — ждём с утра.",
       "source": "moj-kron",
       "externalKey": "obzharka-2026-09-05"
     }'

3. 3

   Заберите ответ

   201 и groupId — пост принят и уйдёт в течение минуты. По строке на каждый канал, куда он поставлен. Дальше судьбу поста смотрите по этому же groupId.

   ОтветСкопировать

   HTTP/1.1 201 Created
   
   {
     "groupId": "6f1c2f3a-8d21-4a77-9d0e-2b7c1f0a5e44",
     "posts": [
       { "id": 812, "channelId": 17, "provider": "telegram", "name": "Кофейня на Мойке", "state": "queued" },
       { "id": 813, "channelId": 18, "provider": "vk",       "name": "Кофейня на Мойке", "state": "queued" }
     ]
   }

Четыре ручки, и всё

Подключение каналов, оплата, выдача ключей и токены площадок наружу не выставлены намеренно: ключ даёт право вести каналы, а не управлять аккаунтом.

curl https://smmly.ru/api/v1/channels \
  -H "Authorization: Bearer smk_ВАШ_КЛЮЧ"

{
  "channels": [
    { "id": 17, "provider": "telegram", "name": "Кофейня на Мойке", "tags": ["новости", "акции"], "disabled": false, "needsReauth": false },
    { "id": 18, "provider": "vk",       "name": "Кофейня на Мойке", "tags": ["новости"],           "disabled": false, "needsReauth": false }
  ]
}

{
  "tags": ["новости"],              // или "providers": ["telegram"], или "channelIds": [17, 18]
  "content": "текст на все площадки",
  // либо по площадкам: {"default": "…", "telegram": "<b>…</b>", "vk": "…", "max": "…", "x": "…"}
  "format": "html",                 // plain (по умолчанию) или html
  "mediaUrls": ["https://site.ru/card.png"],
  "media": [{"type": "image", "rel": "…"}],   // ответ /api/v1/media, как есть
  "buttons": [
    {"text": "Записаться", "url": "https://site.ru/zapis/"}
  ],
  "firstComment": "Подробности: …",
  "partial": true,                  // отказ одного канала не валит остальные; отвергнутые придут в skipped
  "publishAt": "2026-09-06T09:00:00+03:00",   // нет → уходит сейчас
  "state": "queued",                // draft — положить в кабинет, но не отправлять
  "source": "moj-kron",             // пара source + externalKey = защита от повтора
  "externalKey": "obzharka-2026-09-05",
  "payload": {}                     // что угодно, ляжет рядом с событием источника
}

curl "https://smmly.ru/api/v1/posts?group=6f1c2f3a-8d21-4a77-9d0e-2b7c1f0a5e44" \
  -H "Authorization: Bearer smk_ВАШ_КЛЮЧ"

{
  "groupId": "6f1c2f3a-8d21-4a77-9d0e-2b7c1f0a5e44",
  "posts": [
    {
      "id": 812, "channelId": 17, "provider": "telegram", "name": "Кофейня на Мойке",
      "state": "published",
      "publishAt": "2026-09-05T06:00:00.000Z",
      "publishedAt": "2026-09-05T06:00:11.402Z",
      "externalUrl": "https://t.me/mycoffee/1481",
      "error": null,
      "attempts": 1
    }
  ]
}

curl -X POST https://smmly.ru/api/v1/media \
  -H "Authorization: Bearer smk_ВАШ_КЛЮЧ" \
  -F "file=@card.png"

{
  "media": { "type": "image", "rel": "42/6f1c2f3a-….png", "name": "card.png", "size": 184320 },
  "url": "/api/media/42/6f1c2f3a-….png"
}

Поле title в контракте есть, но сегодня оно ни на что не влияет: ни одна из четырёх подключаемых площадок отдельного заголовка у поста не различает. Всё решает текст.

Что доедет до каждой площадки

Один замысел — четыре разных набора правил. Всё проверяемое мы проверяем при постановке в очередь, а не в момент отправки: узнать, что текст на триста знаков длиннее лимита, надо ДО того, как половина каналов уже опубликовалась.

• Разметку и кнопки, которых площадка не умеет, мы не отбиваем, а тихо не шлём: пост во ВКонтакте уедет без тегов, в MAX — без кнопки. Отбить публикацию из-за кнопки было бы хуже, чем опубликовать без неё.
• Единственное исключение — кнопки на альбоме: телеграм не принимает клавиатуру к группе вложений вовсе, и такой пост мы отбиваем (400) вместо тихой потери кнопок, ради которых его и собирали.
• Вложений в одном посте — не больше десяти, считая и media, и mediaUrls. Ссылки мы скачиваем сами, по разу на замысел, а не на канал.

API или MCP

Это не два продукта, а два входа в одну очередь. Ключ один и тот же, каналы те же, посты видны в одном календаре. Разница — кто принимает решение опубликовать.

Отказы и что с ними делать

• 400

  Тело не прошло проверку

  «Нужен content…», «Укажите, куда постить…», «Под этот отбор не нашлось ни одного живого канала». Отдельный случай — «Пост не проходит по площадкам» со списком в issues: там по строке на канал, что именно длиннее лимита или несовместимо.

• 401

  Ключа нет или он мёртв

  Проверьте заголовок: Authorization: Bearer smk_… Удалённый в кабинете ключ перестаёт работать сразу, и «нет такого» от «отозван» снаружи не отличается намеренно.

• 402

  Нет действующей подписки

  Очередь закрыта: код no_subscription. Черновик (state: draft) при этом принимается — терять уже написанный текст из-за просроченной карты незачем.

• 403

  Почта аккаунта не подтверждена

  Тот же гейт, что и в кабинете. Ключ его не обходит — иначе он был бы дыркой в обход самой проверки.

• 404

  Замысел не найден

  GET по чужому или несуществующему groupId. Формат обязан быть uuid.

• 413

  Файл больше предела

  Картинка — до 10 МБ, видео и pdf — до 50 МБ.

• 429

  Слишком часто

  Больше 60 запросов в минуту на ключ. Отказ держится до конца минуты, повторять стоит с паузой.