BlackSea OAuth API побудований на REST і відповідає у форматі JSON. Як розпізнати помилок, описано нижче.
Щоб почати користуватися API, потрібно зареєструвати свій OAuth-додаток.
Після створення додатку ви отримаєте його ID і секрет.
Автентифікація
Відкрийте свій додаток у Налаштування → Додатково → Додатки і натисніть «Згенерувати токен доступу». Передавайте токен у заголовку Authorization: Bearer … або параметром access_token:
curl https://api.blacksea.in.ua/v2/user \ -H "Authorization: Bearer ACCESS_TOKEN"
Області доступу
Доступні п'ять областей доступу (scopes), які додаток може запитати, коли користувач його авторизує.
edit_products: доступ на читання й запис до продуктів користувача та їхніх варіантів, промокодів і додаткових полів.
view_sales: доступ на читання інформації про продажі продуктів користувача, зокрема їх кількість. Ця область також потрібна, щоб підписатися на продажі користувача.
mark_sales_as_shipped: доступ на запис, щоб позначати продажі продуктів користувача як відправлені.
refund_sales: доступ на запис, щоб повертати кошти за продажі продуктів користувача.
Методи API
Усі методи працюють за адресою https://api.blacksea.in.ua/v2.
Повний список методів із параметрами й прикладами відповідей — у специфікації OpenAPI. Її можна відкрити в Swagger Editor або передати ШІ-агенту.
Щоб дізнаватися про продажі без постійних запитів, налаштуйте вебхук.
Для ШІ-агентів (Claude, Cursor тощо) є MCP-сервер: https://mcp.blacksea.in.ua/mcp.
Кастомні HTML-лендінги
Як зробити кастомний лендінг
Кастомний лендінг повністю замінює стандартну сторінку продукту вашим власним дизайном. Будувати HTML вручну не треба — у редакторі продукту все робиться через готовий промпт для AI-агента.
- У редакторі продукту відкрийте вкладку «Поділитися» і знайдіть блок «Лендінг».
- Натисніть «Скопіювати промпт» — це готова інструкція для ШІ з усіма потрібними деталями саме вашого продукту.
- Створіть токен доступу (scope
edit_products) у Налаштування → Додатково → Додатки і передайте промпт разом із токеном AI-агенту (Claude, Cursor тощо). - Агент згенерує HTML, перевірить його попереднім переглядом і опублікує — сторінка одразу замінить стандартну.
- Поверніться в блок «Лендінг» → «Перегляд», щоб побачити результат, і обов'язково протестуйте кнопку купівлі.
Важливо: кастомна сторінка прибирає стандартну кнопку, тож на ній має бути щонайменше один елемент купівлі — data-blacksea-action="buy". Живі дані продукту підставляються через data-blacksea-field="name|price|description". HTML автоматично очищується й працює в пісочниці: небезпечний код вирізається, а сторінка не має доступу до акаунта покупця.
Довідка API
Замініть стандартну сторінку продукту повністю кастомним лендінгом. HTML очищується (заборонені теги й атрибути вирізаються) і показується в ізольованому iframe, тож інлайнові CSS/JS і Tailwind через CDN працюють, але сторінка не має доступу до акаунта покупця й не може надсилати дані на інші сайти. Потрібні scope edit_products і ввімкнена для продавця функція.
PUT /v2/products/:id/custom_html — опублікувати (або очистити, передавши порожнє значення) лендінг. Надішліть повний HTML у полі custom_html. Повертає продукт і sanitization_report зі списком вирізаного.
POST /v2/products/:id/preview_custom_html — запустити очищувач без збереження. Повертає очищений custom_html і sanitization_report, щоб виправити HTML перед публікацією.
Кастомний лендінг замінює стандартну кнопку купівлі, тож додайте щонайменше один елемент купівлі. Позначте живі значення через data-blacksea-field="name|price|description", а кнопки купівлі — data-blacksea-action="buy" (опційно data-blacksea-option, data-blacksea-quantity, data-blacksea-price, data-blacksea-recurrence для попереднього вибору в оформленні).
Ресурси
Створіть OAuth-додаток у Налаштування → Додатково → Додатки, щоб отримати доступ до API.
Корисні посилання
Якщо хочете дізнатися більше про OAuth, ось кілька корисних посилань:
Помилки API
Перевіряйте поле <code>success</code> у кожній відповіді. Якщо продукт чи продаж не знайдено або їх не вдалося змінити, API відповідає кодом 200 з <code>"success": false</code> і поясненням у <code>message</code>. Інші коди відповіді:
200 OK запит виконано (перевірте success).
400 Bad Request неправильні параметри запиту.
401 Unauthorized токен відсутній, недійсний або відкликаний.
403 Forbidden токену бракує потрібної області доступу (scope).
404 Not Found такої адреси в API немає.
500, 502, 503, 504 Server Error помилка на нашому боці, спробуйте пізніше.
Відповідь з помилкою виглядає так:
{
"success": false,
"message": "The product was not found."
}
Якщо message присутній, він описує конкретну проблему та підказки, що пішло не так.