API для продавців і ШІ-агентів

Розміщуйте сотні товарів з прайсу, оновлюйте ціни й знімайте продане — програмою або доручіть це ШІ-агенту. Безкоштовно, з тими самими правилами, що й на сайті.

1 Отримайте ключПрофіль → API-ключі → «Створити ключ».

2 Дайте агенту скілЗавантажте SKILL.md — інструкцію, як правильно подавати оголошення.

3 Попросіть«Розмісти товари з цього прайсу на reklama.vn.ua» — агент сам підбере рубрики, характеристики й фото.

Скіл для ШІ-агента

Скіл — це інструкція, яку агент (Claude та інші) читає перед роботою: порядок запитів, як обрати рубрику, заповнити характеристики, написати чесний опис і не створити дублів.

Claude Code: збережіть файл як ~/.claude/skills/reklama-vn-ua-ads/SKILL.md і задайте ключ: export REKLAMA_API_KEY=rk_…
Claude (claude.ai): Налаштування → Можливості → Скіли → завантажте папку reklama-vn-ua-ads з цим файлом.
Інші агенти: додайте вміст файлу в системні інструкції.

Відкрити SKILL.md

Доступ

Адреса: https://reklama.vn.ua/api/v1. Кожен запит — з ключем у заголовку, тіло — JSON:

curl https://reklama.vn.ua/api/v1/me \
  -H "Authorization: Bearer $REKLAMA_API_KEY"

Ліміти на ключ: 120 запитів і 20 фото на хвилину, 600 фото на годину. Запити — послідовно, без паралельних; після кожного фото — пауза 2 с. Ключ дає доступ лише до ваших оголошень; відкликати його можна будь-коли.

Методи

GET	/me	Хто я: акаунт, вітрина, ліміти, валюти
GET	/shop	Вітрина й розділи з кількістю оголошень
PATCH	/shop	Створити чи змінити вітрину: title, slug, about, city, nationwide
POST	/shop/sections	Розділ за назвою: знайде наявний або створить
PATCH	/shop/sections/{id}	Перейменувати ({"name"}) або пересунути ({"sort": 0})
DELETE	/shop/sections/{id}	Видалити розділ (оголошення лишаються)
GET	/categories	Дерево рубрик; оголошення подаються лише в "leaf": true
GET	/categories/suggest?q=…	Рубрики, де найчастіше продають схоже (підказка)
GET	/categories/{id}/attributes	Характеристики рубрики: типи, обов'язковість, варіанти
GET	/cities?q=…	Пошук населеного пункту → city_id
POST	/photos	Фото: multipart "photo" або JSON {"url"} → id
POST	/ads	Створити або оновити (за external_id) оголошення
GET	/ads?status=&external_id=&page=	Мої оголошення, по 100
GET	/ads/{id}	Оголошення з описом і характеристиками
PATCH	/ads/{id}	Змінити лише передані поля
POST	/ads/{id}/status	{"status": "archived"} — зняти, "active" — повернути
DELETE	/ads/{id}	Видалити назавжди

Оголошення

external_id	рядок	Ваш ідентифікатор товару (артикул, рядок прайсу). Повтор з ним оновлює оголошення, а не створює дубль
category_id	число	Найглибша рубрика (leaf)
city_id	число	З /cities
title	рядок	10–70 символів, без CAPS LOCK
description	рядок	40–9000 символів
price	число	У валюті currency; без ціни — «Договірна»
currency	UAH \| USD \| EUR	Покупцям показуємо в гривнях за поточним курсом
is_negotiable	true/false	Можливий торг
attrs	об'єкт	code → value: enum — value варіанта, multi — масив, number — число, bool — true
photos	масив id	З /photos, до 12, перше — головне
phone	рядок	+380XXXXXXXXX
section	рядок	Розділ вітрини за назвою (знайде або створить); або section_id; null — без розділу
sale_price, sale_until	число, дата	Знижка з таймером до вказаної дати (до 90 днів)

Поле condition в рубриках товарів обов'язкове: nove або vzhyvane. Перелік характеристик і їхніх варіантів — у /categories/{id}/attributes.

# 1. фото за посиланням
curl https://reklama.vn.ua/api/v1/photos -H "Authorization: Bearer $REKLAMA_API_KEY" \
  -H "Content-Type: application/json" -d '{"url": "https://example.com/macbook-1.jpg"}'
# → {"id": 9001, "urls": {...}}

# 2. оголошення
curl https://reklama.vn.ua/api/v1/ads -H "Authorization: Bearer $REKLAMA_API_KEY" -H "Content-Type: application/json" -d '{
  "external_id": "MBP16-M1MAX-64-1TB-S1",
  "category_id": 123, "city_id": 456,
  "title": "MacBook Pro 16 2021 M1 Max 64/1TB Silver, батарея 84%",
  "description": "Потужний 16-дюймовий MacBook Pro для монтажу й 3D…",
  "price": 1730, "currency": "USD",
  "attrs": {"condition": "vzhyvane", "laptop_brand": "apple", "cpu": "apple-m1-max", "ram": "64", "storage": "1024", "screen": 16},
  "photos": [9001, 9002],
  "section": "MacBook"
}'
# → 201 {"id": 777, "status": "active", "url": "https://reklama.vn.ua/oholoshennia/…-777", "created": true}

Помилки

Відповідь з кодом 4xx містить error (машинний код), message і details — що саме виправити:

{"error": "validation", "message": "Оголошення не збережено.", "details": ["Заголовок має містити від 10 до 70 символів."]}

401 unauthorized — немає ключа або його відкликано;
403 email_not_verified, limit_reached — підтвердіть email / ліміт активних оголошень;
404 not_found — немає такого оголошення серед ваших;
422 validation, bad_photo, not_leaf — дані не підходять, див. details;
429 rate_limited — зачекайте хвилину.

Оголошення через API проходять ту саму модерацію й правила, що й подані вручну (Правила розміщення). Питання — на сторінці Контакти.