# 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`.