md2vk/docs/vk-api.md

md2vk — Взаимодействие с VK API

Источник: официальная документация VK (dev.vk.com / id.vk.ru), проверено 2026-09. Услуга работает через официальный протокол OAuth 2.0 и VK API — никакого «взлома».

Как это работает

1. OAuth-авторизация. Пользователь нажимает «Прикрепить аккаунт» → редирект на VK. Пользователь подтверждает вход и выдаёт приложению права (scopes, обязателен wall). Сервис не получает пароль — только временный код/токен.
2. Access Token. VK возвращает сервису access token — цифровой ключ с ограниченными правами (например, только публикация записей).
3. Публикация через API. Сервис вызывает wall.post с текстом/вложениями, owner_id, from_group. Авторизация — access_token в параметрах запроса.

Ссылки на официальную документацию

Что	Ссылка
Создание и настройка приложения (VK ID, Standalone)	https://id.vk.com/about/business/go/docs/ru/vkid/latest/vk-id/connection/create-application
Общая документация по API	https://dev.vk.com/ru/reference
Авторизация (OAuth 2.0/2.1)	https://id.vk.com/about/business/go/docs/ru/vkid/latest/vk-id/connection/start-integration/auth-without-sdk/auth-without-sdk-web
Метод wall.post	https://dev.vk.com/ru/method/wall.post
Создать приложение (dev.vk.com)	https://dev.vk.com

OAuth-флоу (ссылка для получения токена)

https://oauth.vk.com/authorize?client_id=<client_id>&scope=wall,offline&redirect_uri=<redirect>&response_type=token

• client_id — ID приложения VK (см. VK ID).
• scope — обязателен wall; offline — долгоживущий токен.
• response_type=token — токен приходит в фрагменте редиректа.
• После ответа: access_token, user_id, expires_in (0 = бессрочно).

Публикация (wall.post)

https://api.vk.com/method/wall.post
POST data: access_token, v=5.199, owner_id, message, from_group, attachments, publish_date, format_data

Параметры в нашем клиенте (app/vk_client.py):

Параметр	Когда	Значение
owner_id	группа	отрицательный ID сообщества (-123), для пользователя не передаём
from_group	группа	1 — пост от имени группы
friends_only	опц.	только друзьям
publish_date	отложка	Unix timestamp
attachments	опц.	photo123_456,...
signed	группа	подпись автора
format_data	всегда	JSON {"version":1,"items":[...]}

Ответ: {"response":{"post_id":N,"owner_id":M}} → URL https://vk.com/wall{M}_{N}.

Важно про токены

• Для личной стены — токен пользователя.
• Для стены сообщества — токен администратора группы с правами wall и photos.
• Токены сообщества из настроек группы («Работа с API») для wall.post не подходят — нужен именно пользовательский токен.

Лонгриды (статьи) — ограничение

• Создавать статьи через официальный VK API нельзя. В FAQ VK: «методов для работы с лонгридами пока что нет».
• Можно опубликовать на стене существующую статью через wall.post: attachments=articleXXX_YYY, где XXX — ID автора (для сообщества — с минусом), YYY — ID статьи. Статья должна быть уже опубликована (черновик прикрепить нельзя).
• Значит, полный автоматический дубликат блога (генерация лонгридов «из коробки») невозможен. Варианты: посты+фото+ссылки через API, статьи вручную, гибрид.

Версия API

• В конфиге VK_API_VERSION=5.199 (app/config.py).
• Проверка токена: users.get (пустой user_ids → текущий пользователь).

Ошибки

Формат ошибки VK: {"error":{"error_code":N,"error_msg":"..."}}. Наш клиент бросает VkApiError(error_code, error_msg); в API публикации ошибка пишется в publications.error_message, ответ success=false.