Вебхук про продажі (Ping)

Вебхук — це сигнал, який BlackSea надсилає на твій сервер щоразу, коли хтось купує твій продукт.

Наприклад, з ним можна:

  • автоматично подякувати покупцеві на своєму сайті;
  • створити покупцеві акаунт на своїй платформі;
  • записати продаж у свою таблицю чи CRM.

Вебхук — це HTTP POST-запит на адресу, яку ти вказуєш у розділі Налаштування → Додатково. Тіло запиту — у форматі application/x-www-form-urlencoded, поля описані в таблиці нижче.

Успішною вважається будь-яка відповідь з кодом 2xx. Якщо твій сервер відповів 499, 500, 502, 503 або 504, ми повторимо запит ще тричі: через 1, 3 і 10 хвилин. Іншу помилку, обрив з'єднання і відповідь, довшу за 5 секунд, не повторюємо, тож відповідай одразу, а довгу роботу роби у фоні.

Перевірити свій обробник можна кнопкою «Надіслати тестовий пінг на URL» у тих самих налаштуваннях: прийде твій останній продаж з полем test=true.

Щоб знати, звідки прийшов покупець, додай до посилання на продукт власні параметри, наприклад ?campaignid=c123. Вони прийдуть у полі url_params.

Через API можна отримувати й інші події: повернення, оскарження платежу, скасування й поновлення підписки. Для цього створи підписку методом POST /v2/resource_subscriptions, опис є в специфікації OpenAPI.

Безпека

Вказуй адресу з https://, інакше дані покупця підуть мережею відкритим текстом.

Запити вебхука поки не мають цифрового підпису, тож твій сервер сам не відрізнить справжній запит від підробленого: надіслати його може будь-хто, хто дізнається адресу. Тому перш ніж відкривати доступ чи видавати щось цінне, перевір продаж через API: візьми sale_id із запиту і запитай його зі своїм токеном. Якщо API відповідає помилкою або продукт і сума не збігаються, ігноруй запит.

curl https://api.blacksea.in.ua/v2/sales/SALE_ID \
  -H "Authorization: Bearer ACCESS_TOKEN"

Токен створюється в Налаштування → Додатково, блок «Додатки»: потрібен дозвіл view_sales. Тримай токен тільки на сервері, ніколи в коді сторінки.

Додатково зроби адресу такою, щоб її не можна було вгадати: додай до неї довгий випадковий рядок.

Поля запиту

Поле Опис
sale_id Ідентифікатор продажу. За ним продаж можна перевірити через API.
sale_timestamp Час продажу у форматі ISO 8601.
order_number Номер замовлення, числова форма sale_id.
seller_id Твій ідентифікатор продавця, той самий, що в налаштуваннях.
product_id Ідентифікатор продукту.
product_name Назва продукту.
product_permalink Повне посилання на продукт.
short_product_id Короткий ідентифікатор продукту з його посилання.
email Email покупця.
full_name Ім'я покупця, якщо він його вказав.
purchaser_id Ідентифікатор акаунта покупця на BlackSea, якщо акаунт є.
price Сума, яку заплатив покупець, у копійках (найменших одиницях валюти з поля currency). 12900 — це 129 грн.
currency Валюта продукту, наприклад uah.
fee Скільки утримала BlackSea, у копійках: комісія 10% (15%, якщо продаж прийшов через Знахідки), а якщо ти продаєш як фізособа, то ще й ПДФО та військовий збір, які платформа сплачує за тебе.
discover_fee_charged true, якщо продаж прийшов через Знахідки і комісія була 15%.
quantity Кількість.
variants Обрані варіанти, якщо є, наприклад {"Розмір" => "L"}.
offer_code Промокод, якщо покупець його застосував.
custom_fields Відповіді покупця на додаткові поля при оформленні, якщо є. Кожна відповідь також приходить окремим полем з назвою цього поля.
url_params Параметри з посилання, за яким прийшов покупець, якщо є, наприклад {"campaignid" => "c123"}.
subscription_id Ідентифікатор підписки, якщо продукт — членство.
recurrence Періодичність оплати підписки, наприклад monthly або yearly.
is_recurring_charge true для повторних списань за підпискою.
license_key Ліцензійний ключ, якщо для продукту ввімкнено ліцензії.
is_multiseat_license true, якщо ліцензія підписки розрахована на кілька місць.
is_preorder_authorization true, якщо це передзамовлення.
affiliate Email партнера, якщо продаж прийшов від нього.
affiliate_credit_amount_cents Винагорода партнера, у копійках.
is_gift_receiver_purchase true, якщо продукт купили в подарунок.
gifter_email Email того, хто подарував.
gift_price Сума, яку заплатив дарувальник, у копійках.
shipping_information Адреса доставки, якщо продукт фізичний.
shipping_rate Вартість доставки фізичного продукту, у копійках.
sku_id Ідентифікатор SKU, якщо продукт фізичний або має SKU.
ip_country Країна за IP-адресою покупця, якщо її вдалося визначити.
referrer Сторінка, з якої покупець перейшов на продукт.
can_contact true, якщо покупець погодився отримувати від тебе листи.
test true для тестового запиту і для покупки власного продукту.
refunded true, якщо гроші за продаж повернуто.
disputed true, якщо покупець оскаржив платіж у банку.
dispute_won true, якщо оскарження вирішилося на твою користь.
card Тип картки й замаскований номер, якщо є.
resource_name Подія, на яку оформлено підписку через API, наприклад sale або refund.