Avito n8n Custom Node

English | Русский

✨ Update: The project was migrated to the current src/ layout, @n8n/node-cli, and recommended runtime n8n >= 2.19.2.

Compatibility: v2.0.0 may be incompatible with n8n versions earlier than 2.12.0 because OAuth2 credential handling was fundamentally changed. Recommended runtime is n8n >= 2.19.2; starting from this line, the Authorization Code scope issue from #1 is presumed to be fixed. If authentication fails after updating, recreate Avito OAuth2 credentials.

Совместимость: v2.0.0 может быть несовместима с n8n ранее 2.12.0 из-за фундаментального изменения OAuth2 credentials. Рекомендуется n8n >= 2.19.2: начиная с этой ветки, проблема Authorization Code scopes из #1 предположительно исправлена. Если после обновления авторизация не работает, пересоздайте Avito OAuth2 credentials.

English

🚀 Overview

Avito n8n Custom Node is a community node for n8n that integrates with Avito API for Business. It provides ready-to-use Avito resources in the n8n UI, including items, promotion, messenger, ratings, autoload, CPA, CallTracking, user finance, tariffs, and special offers.

✨ Key Features

• 🔧 Convenient API Integration: Direct access to Avito API functionality from n8n workflows
• 🔑 OAuth2 Token Management: Avito 403 Forbidden token expiry is handled through credential-level refresh
• 📊 Broad API Coverage: Items, User, Promotion v1, CPXPromo Legacy, Messenger, CPA, CallTracking, Ratings & Reviews, Autoload, Tariff, and Special Offers
• 🧩 Current n8n Layout: Source code lives in src/ and builds through @n8n/node-cli
• 🛡️ Validation & Error Handling: Local validation for documented limits and clearer Avito API errors

🎯 Problem Solved

Avito returns 403 Forbidden when an access token expires. Earlier n8n setups required awkward custom logic to refresh tokens on 403. In current n8n versions this is much simpler: the credential defines hidden tokenExpiredStatusCode: 403, so refresh is handled at credential level.

Authorization Code scopes are entered as comma-separated values:

items:info,stats:read,user:read

Client Credentials usually does not require scope. If a specific Avito API explicitly requires one, for example Special Offers, use the documented scope when the connection flow supports it.

Version 2.0.0 may be incompatible with n8n versions earlier than 2.12.0 because the OAuth2 credential implementation changed significantly. Use n8n >= 2.19.2 where possible; this is the recommended line because the Authorization Code scope handling issue reported in #1 is presumed to be resolved there. Existing Avito OAuth2 credentials may need to be recreated after upgrading.

🗂️ Current Project Structure

The old root-level nodes/ and credentials/ layout was refactored into src/.

• src/credentials/avitoOAuth2Api.credentials.ts - OAuth2 credential
• src/nodes/Avito/Avito.node.ts - main Avito node
• src/nodes/Avito/AvitoMessengerTrigger.node.ts - Messenger webhook trigger
• src/nodes/Avito/Descriptions/* - node UI fields
• src/nodes/Avito/router/RouterUtils.ts - operation routing
• src/nodes/Avito/<Resource>/* - API operation implementations

The package configuration points n8n to built files under dist/src/....

📋 Supported Avito API Methods

🏠 Items (Объявления)

• Items list, item information, price update
• Current VAS prices and current VAS application method
• Calls statistics, shallow counters, profile analytics
• Profile spendings via POST /stats/v2/accounts/{user_id}/spendings
• Deprecated old Item VAS endpoints are intentionally not added

👤 User (Пользователь)

• GET /core/v1/accounts/self - authorized user information
• GET /core/v1/accounts/{user_id}/balance/ - wallet balance
• POST /core/v1/accounts/operations_history/ - wallet operations history
• Local validation: max 1 week, not older than 1 year, dateTimeFrom <= dateTimeTo

🎯 Promotion v1 (Продвижение)

• POST /promotion/v1/items/services/dict - service type dictionary
• POST /promotion/v1/items/services/get - active services by item IDs
• POST /promotion/v1/items/services/orders/get - orders list
• POST /promotion/v1/items/services/orders/status - order status
• POST /promotion/v1/items/services/bbip/suggests/get - BBIP budget suggestions
• POST /promotion/v1/items/services/bbip/forecasts/get - BBIP forecast
• PUT /promotion/v1/items/services/bbip/orders/create - create BBIP order

🎯 CPXPromo Legacy

• Existing /cpxpromo/1/* operations are available in a separate CPXPromo Legacy resource
• They are not mixed with the current Promotion v1 API

💬 Messenger

• Chats, chat by ID, V3 messages
• Send text and image messages
• Delete messages and mark chats as read
• Upload images from n8n binary data
• Voice file links, blacklist, webhook subscriptions
• Dedicated Avito Messenger Trigger for incoming webhook V3 events

📤 Autoload (Автозагрузка)

• Category tree and category fields
• Profile get/update
• Reports, last report, report by ID
• Report items and fees
• File upload
• Avito ID / file ID conversion

📞 CPA

• POST /cpa/v3/balanceInfo
• Calls and chats by time
• Chat by actionId
• Phones from target chats
• Complaints by call or actionId
• Required X-Source header is exposed in the UI

☎️ CallTracking

• Call by ID
• Calls by time
• Call recording as binary audio/mpeg

⭐ Ratings & Reviews (Рейтинги и отзывы)

• Rating info
• Reviews list with pagination
• Create review answer using documented message
• Remove review answer

💼 Tariff (Тарифы)

• GET /tariff/info/1 - current and scheduled Transport tariff info
• CPA tariffs are excluded by Avito documentation

💌 Special Offers (Рассылка скидок и спецпредложений)

Beta API:

• POST /special-offers/v1/available
• POST /special-offers/v1/multiCreate
• POST /special-offers/v1/multiConfirm
• POST /special-offers/v1/stats
• POST /special-offers/v1/tariffInfo

Scope: special_offers:sending.

🛠️ Installation

1. Install the package as an n8n community node or place the built package in your custom nodes directory.
2. Restart n8n.
3. The Avito node and Avito Messenger Trigger will appear in n8n.

⚙️ Configuration

1. Create Avito OAuth2 Credentials:

   • Go to n8n Settings → Credentials
   • Add Avito OAuth2 API
   • Choose Client Credentials or Authorization Code
   • Enter client_id and client_secret from Avito

2. Configure the Node:

   • Select resource
   • Choose operation
   • Fill in required parameters
   • The node handles authentication automatically

🧪 Development

npm run build
npm run lint
npm run dev
npm run format

Minimum verification before release:

npx tsc -p tsconfig.json --noEmit
npm run lint
npm run build

n8n-node may print Node.js [DEP0190]; this is not a node code error.

💡 Development Note

This project was built with extensive AI assistance from Claude and Codex (GPT-5.5), plus manual review against Avito API documentation.

⚠️ Disclaimer

• This is an independent community node and is not officially affiliated with Avito or n8n
• The software is provided as-is, without warranties
• Use at your own risk and test workflows before production
• Feature requests and bug reports are welcome, but implementation is not guaranteed

📄 License

MIT.

🤝 Contributing

Issues and pull requests are welcome.

Русский

🚀 Обзор

Avito n8n Custom Node — community-нода для n8n, которая интегрируется с Avito API for Business. Она добавляет готовые ресурсы Авито прямо в интерфейс n8n: объявления, продвижение, мессенджер, отзывы, автозагрузка, CPA, CallTracking, пользовательские финансы, тарифы и рассылки спецпредложений.

✨ Ключевые особенности

• 🔧 Удобная интеграция с API: Прямой доступ к Avito API из workflow n8n
• 🔑 OAuth2 Token Management: Истечение токена Avito через 403 Forbidden обрабатывается на уровне credential
• 📊 Широкое покрытие API: Объявления, Пользователь, Promotion v1, CPXPromo Legacy, Мессенджер, CPA, CallTracking, Рейтинги и отзывы, Автозагрузка, Тарифы, Рассылка скидок
• 🧩 Актуальная структура n8n: Исходники находятся в src/, сборка идет через @n8n/node-cli
• 🛡️ Валидация и ошибки: Локальная проверка документированных лимитов и понятные ошибки Avito API

🎯 Решаемая Проблема

Avito возвращает 403 Forbidden, когда access token истек. Раньше для refresh по 403 приходилось отдельно прописывать неудобную логику. В актуальных версиях n8n это намного проще: credential содержит скрытый tokenExpiredStatusCode: 403, поэтому refresh обрабатывается на уровне credential.

Authorization Code scopes задаются через запятую:

items:info,stats:read,user:read

Для Client Credentials scope обычно не нужен. Если конкретный API Авито явно требует scope, например Special Offers, используйте документированный scope, когда сценарий подключения это поддерживает.

Версия 2.0.0 может быть несовместима с n8n ранее 2.12.0, потому что реализация OAuth2 credential была существенно изменена. По возможности используйте n8n >= 2.19.2: начиная с этой ветки, предположительно закрыта проблема с Authorization Code scopes из #1. После обновления может потребоваться пересоздать Avito OAuth2 credentials.

🗂️ Текущая Структура Проекта

Старая корневая структура nodes/ и credentials/ перенесена в src/.

• src/credentials/avitoOAuth2Api.credentials.ts - OAuth2 credential
• src/nodes/Avito/Avito.node.ts - основная нода Avito
• src/nodes/Avito/AvitoMessengerTrigger.node.ts - Messenger webhook trigger
• src/nodes/Avito/Descriptions/* - UI-поля ноды
• src/nodes/Avito/router/RouterUtils.ts - роутинг операций
• src/nodes/Avito/<Resource>/* - реализации API-методов

В package.json n8n указывает на собранные файлы в dist/src/....

📋 Поддерживаемые Методы API Авито

🏠 Объявления (Items)

• список объявлений, информация по объявлению, обновление цены
• актуальная стоимость VAS и актуальный метод применения VAS
• статистика звонков, счетчики объявлений, аналитика профиля
• расходы профиля через POST /stats/v2/accounts/{user_id}/spendings
• deprecated VAS endpoints из старого Item API намеренно не добавляются

👤 Пользователь (User)

• GET /core/v1/accounts/self - информация об авторизованном пользователе
• GET /core/v1/accounts/{user_id}/balance/ - баланс кошелька
• POST /core/v1/accounts/operations_history/ - история операций кошелька
• локальная проверка: максимум 1 неделя, не дальше 1 года, dateTimeFrom <= dateTimeTo

🎯 Продвижение (Promotion v1)

• POST /promotion/v1/items/services/dict - словарь типов услуг
• POST /promotion/v1/items/services/get - активные услуги по объявлениям
• POST /promotion/v1/items/services/orders/get - список заявок
• POST /promotion/v1/items/services/orders/status - статус заявки
• POST /promotion/v1/items/services/bbip/suggests/get - варианты бюджета BBIP
• POST /promotion/v1/items/services/bbip/forecasts/get - прогноз BBIP
• PUT /promotion/v1/items/services/bbip/orders/create - создание BBIP-заявки

🎯 CPXPromo Legacy

• существующие операции /cpxpromo/1/* доступны в отдельном ресурсе CPXPromo Legacy
• они не смешиваются с актуальным Promotion v1 API

💬 Мессенджер

• чаты, чат по ID, сообщения V3
• отправка текста и изображений
• удаление сообщений и отметка чата прочитанным
• загрузка изображений из binary data n8n
• ссылки на голосовые файлы, blacklist, webhook-подписки
• отдельный Avito Messenger Trigger для входящих webhook V3 событий

📤 Автозагрузка (Autoload)

• дерево категорий и поля категории
• получение и обновление профиля
• отчеты, последний отчет, отчет по ID
• элементы отчета и списания
• загрузка файла
• конвертация Avito ID / file ID

📞 CPA

• POST /cpa/v3/balanceInfo
• звонки и чаты по времени
• чат по actionId
• телефоны из целевых чатов
• жалобы по звонку или actionId
• обязательный заголовок X-Source вынесен в UI

☎️ CallTracking

• звонок по ID
• звонки по времени
• аудиозапись звонка как binary audio/mpeg

⭐ Рейтинги И Отзывы (Ratings & Reviews)

• информация о рейтинге
• список отзывов с пагинацией
• создание ответа на отзыв с документированным полем message
• удаление ответа на отзыв

💼 Тарифы (Tariff)

• GET /tariff/info/1 - информация о текущем и запланированном тарифе в категории Транспорт
• CPA-тарифы исключены по документации Авито

💌 Рассылка Скидок И Спецпредложений (Special Offers)

Beta API:

• POST /special-offers/v1/available
• POST /special-offers/v1/multiCreate
• POST /special-offers/v1/multiConfirm
• POST /special-offers/v1/stats
• POST /special-offers/v1/tariffInfo

Scope: special_offers:sending.

🛠️ Установка

1. Установите пакет как n8n community node или поместите собранный пакет в директорию custom nodes.
2. Перезапустите n8n.
3. В n8n появятся Avito и Avito Messenger Trigger.

⚙️ Настройка

1. Создайте Avito OAuth2 Credentials:

   • Перейдите в n8n Settings → Credentials
   • Добавьте Avito OAuth2 API
   • Выберите Client Credentials или Authorization Code
   • Укажите client_id и client_secret из Авито

2. Настройте ноду:

   • Выберите ресурс
   • Выберите операцию
   • Заполните обязательные параметры
   • Нода автоматически обрабатывает авторизацию

🧪 Разработка

npm run build
npm run lint
npm run dev
npm run format

Минимальная проверка перед релизом:

npx tsc -p tsconfig.json --noEmit
npm run lint
npm run build

n8n-node может выводить предупреждение Node.js [DEP0190]; это не ошибка кода ноды.

💡 Заметка О Разработке

Проект разрабатывался с активной помощью Claude и Codex (GPT-5.5), а также ручной сверкой с документацией Avito API.

⚠️ Отказ От Ответственности

• Это независимая community-нода без официальной связи с Avito или n8n
• ПО предоставляется как есть, без гарантий
• Используйте на свой риск и тестируйте workflow перед production
• Feature requests и bug reports приветствуются, но реализация не гарантируется

📄 Лицензия

MIT.

📝 Примечание О Верификации n8n

Нода намеренно использует русский язык в интерфейсе, потому что ориентирована на пользователей Авито. Если n8n добавит полноценную локализацию, интерфейс можно будет адаптировать под многоязычный формат.

🤝 Вклад В Проект

Issues и pull requests приветствуются.

🔗 Полезные Ссылки

• Авито API для разработчиков
• Документация n8n
• Рекомендации по деплою community nodes