API SMM-панели: заказы и автоматизация

От подключения до первой публикации

1. Выберите услугу

   Получите service_id услуги автопостинга в каталоге. Запросите GET /autopost/capabilities?service_id=…: здесь режимы публикации, доступные AI-модели и ограничения.

2. Создайте клиента

   PUT /autopost/clients/customer_42 с именем клиента или пустым объектом создаёт контекст. Повторный PUT обновляет его.

3. Подтвердите привязку в боте

   POST link-sessions возвращает deep_link. Передайте ссылку клиенту и опрашивайте GET link-sessions по полученному id до status=linked. При expired создайте новую сессию. Для MAX укажите platform=max.

4. Проверьте канал и выберите источники

   После выдачи боту необходимых прав вызовите channels/check. Нужны permissions=ready и can_order=true. Сохраните UUID id ответа как channel_id. Получите источники через GET sources с service_id или задайте собственные HTTPS-ссылки.

5. Оформите заказ

   Передайте service_id, channel_id, external_order_id, months и settings. Укажите расписание или таймер. max_amount ограничивает сумму списания; 1500.00 в примере — условный предел, а не тариф.

6. Дождитесь результата

   202 означает, что команда принята. Опрашивайте URL из Location с интервалом Retry-After до succeeded или failed. По subscription_id успешной операции получите подписку, настройки и очередь. При failed прочитайте error.

Примеры запросов

Пути указаны относительно домена API. Замените ключ, UUID, ссылки, идентификаторы и предел суммы своими значениями. UUID ниже приведены только для примера. Один Idempotency-Key соответствует одной команде.

PUT /api/v1/autopost/clients/customer_42
X-API-Key: vw_your_key
Content-Type: application/json

{
  "name": "Customer 42"
}

POST /api/v1/autopost/clients/customer_42/link-sessions
X-API-Key: vw_your_key
Idempotency-Key: link-customer42-001
Content-Type: application/json

{
  "service_id": "11111111-1111-4111-8111-111111111111",
  "platform": "telegram"
}

GET /api/v1/autopost/clients/customer_42/link-sessions/{id}
X-API-Key: vw_your_key

POST /api/v1/autopost/clients/customer_42/channels/check
X-API-Key: vw_your_key
Idempotency-Key: check-customer42-001
Content-Type: application/json

{
  "service_id": "11111111-1111-4111-8111-111111111111",
  "platform": "telegram",
  "target": "https://t.me/your_channel"
}

GET /api/v1/autopost/clients/customer_42/sources?service_id=11111111-1111-4111-8111-111111111111&kind=catalog
X-API-Key: vw_your_key

POST /api/v1/autopost/clients/customer_42/orders
X-API-Key: vw_your_key
Idempotency-Key: order-customer42-001
Content-Type: application/json

{
  "service_id": "11111111-1111-4111-8111-111111111111",
  "channel_id": "22222222-2222-4222-8222-222222222222",
  "external_order_id": "order-2026-001",
  "months": 1,
  "max_amount": "1500.00",
  "settings": {
    "source_selection": {
      "type": "catalog",
      "source_ids": [
        "33333333-3333-4333-8333-333333333333"
      ]
    },
    "queue_mode": "new_and_old",
    "publication": {
      "mode": "schedule",
      "timezone": "Europe/Moscow",
      "days": {
        "1": [
          {
            "at": "09:00"
          },
          {
            "from": "17:00",
            "to": "19:00"
          }
        ]
      }
    }
  }
}

HTTP/1.1 202 Accepted
Location: /api/v1/autopost/clients/customer_42/operations/{id}
Retry-After: 2

GET /api/v1/autopost/clients/customer_42/operations/{id}
X-API-Key: vw_your_key

GET /api/v1/autopost/clients/customer_42/orders/{order_id}
X-API-Key: vw_your_key

GET /api/v1/autopost/clients/customer_42/subscriptions/{subscription_id}/queue
X-API-Key: vw_your_key

GET /api/v1/autopost/clients/customer_42/subscriptions/{id}
X-API-Key: vw_your_key

HTTP/1.1 200 OK
ETag: "1"

PATCH /api/v1/autopost/clients/customer_42/subscriptions/{id}/settings
X-API-Key: vw_your_key
If-Match: "1"
Content-Type: application/json

{
  "publication": {
    "mode": "ad_timer",
    "interval_min": 30,
    "interval_max": 60
  }
}

{
  "source_selection": {
    "type": "custom",
    "urls": [
      "https://t.me/your_source"
    ]
  },
  "queue_mode": "new",
  "publication": {
    "mode": "ad_timer",
    "interval_min": 30,
    "interval_max": 60
  },
  "signature_settings": {
    "mode": "append",
    "text": "Наш канал",
    "url": "https://t.me/your_channel"
  },
  "source_signature_settings": {
    "https://t.me/your_source": {
      "mode": "replace",
      "url": "https://t.me/your_channel"
    }
  }
}

Правила интеграции

Повторы запросов

Все POST требуют Idempotency-Key: 1–128 латинских букв, цифр или символов . _ : -. После тайм-аута повторите прежний URL с тем же ключом и телом. Другое тело с тем же ключом даёт 409 idempotency_conflict. Для новой команды создайте новый ключ. PUT и DELETE этого заголовка не требуют.

Ваш номер заказа и предел оплаты

external_order_id обязателен для заказа и каждого продления: 1–128 латинских букв, цифр или символов . _ : -. Он уникален для client_ref. Повтор с теми же параметрами вернёт прежнюю операцию; другие параметры дадут external_order_conflict. max_amount задаётся строкой с двумя знаками после точки; если цена выше, запрос отклоняется с price_changed.

Изменение настроек

PATCH требует If-Match из GET подписки. Без него — 428, при устаревшей версии — 412. Перечитайте настройки и согласуйте изменения. Передавайте изменяемый раздел целиком; пропущенные разделы сохраняются. null не допускается. Ориентируйтесь также на actions в подписке.

Источники и ИИ

Выбирайте один тип source_selection: catalog с source_ids или custom с urls. Для своих источников поддерживаются HTTPS-ссылки t.me, telegram.me и max.ru. Промпты, модели и индивидуальные настройки ИИ изменяет администратор. При создании заказа и PATCH не передавайте ai_settings или source_settings, даже пустые: запрос будет отклонён. ИИ тарифа работает с сохранёнными настройками.

Подпись со ссылкой

signature_settings.mode: off — выключено, remove — удалить найденную подпись, replace — заменить только найденную, append — добавлять свою всегда. text задаёт кликабельный текст (по умолчанию название канала), url — адрес или приглашение (для приватного канала обязателен). Ищем отдельную короткую строку в конце со ссылкой на Telegram/MAX-канал. source_signature_settings задаёт полное переопределение для источника; mode: off отключает общий режим. Правила действуют на ещё не отправленные посты и не обходят остальные рекламные фильтры.

Расписание и таймер

В schedule обязательны timezone и days. Дни недели: 1 — понедельник, 7 — воскресенье. Слот — at либо диапазон from/to в формате HH:MM; даты в dates — YYYY-MM-DD. Для ad_timer интервалы задаются в минутах, по умолчанию 30–60. queue_mode по умолчанию new_and_old; new — только новые публикации.

Подписка и очередь

Список подписок по умолчанию показывает active и paused; status=all включает остальные. publish-next отправляет следующий пост очереди. При delivery_unknown доставка отдельного поста не подтверждена: он не отправляется повторно и не блокирует следующие публикации. Для диагностики пустой очереди используйте summary и empty_reason. При отмене проверяйте can_cancel, возврат — в refunded_amount заказа.

Списки и статусы

Списки возвращают data и next_cursor. Передавайте курсор без изменений с теми же фильтрами, пока он не станет null. limit — от 1 до 100, по умолчанию 50. Webhooks пока нет: проверяйте статусы запросами GET.

Ошибки автопостинга

Ответ содержит error: code, message, request_id, retryable и fields. 401 — ключ, 403 — недостаточно прав, 402 — баланс, 404 — ресурс недоступен в данном контексте, 409 — конфликт, 422 — поля запроса. При 429 соблюдайте Retry-After; при 503 повторите с задержкой и тем же ключом. Для поддержки сохраните X-Request-ID.

Лимиты запросов

Лимиты учитываются по ключу и общему аккаунту владельца. Создание ссылок привязки и проверка каналов имеют отдельные ограничения. Несколько ключей не увеличивают общий лимит; при ограничении API вернёт 429.