HugeProfitДокументація CRM Увійти
Інтеграції

Як підключити свою систему до HugeProfit через API і вебхуки

HugeProfit CRM · 4 хв читання

Якщо потрібної інтеграції немає в списку, підключіть свою систему через API: сайт на власному движку, складську програму, бухгалтерію, Google Таблиці чи сервіси автоматизації. HugeProfit має два API — сучасний API v2 з правами доступу й вебхуками (рекомендований) і старий API (v1) для наявних інтеграцій.

«Налаштування» → «Інтеграції» → вкладка «Інше». Створювати ключі може лише адміністратор акаунта.

Інтеграції: вкладка Інше

API v2

REST API з єдиним форматом відповідей: товари й залишки, продажі, замовлення з маркетплейсів, клієнти, поставки, витрати, виробництво, списання, доставка (зокрема ТТН Нової Пошти) — і вебхуки з підписом та повторною доставкою. Повний опис запитів — документація API v2 (посилання «Документація API v2» є і у формі ключа).

1. Створіть ключ

  1. Картка «API v2» → «Підключити».
  2. «Назва» — для чого ключ (наприклад, «Синк складу» чи «Сайт»). Для кожної системи — свій ключ: так легко відключити одну, не чіпаючи інших.
  3. «Права»:
    • «Повний доступ» — усе;
    • «Тільки читання» — лише отримувати дані (звіти, аналітика);
    • «Вибірково» — для кожного розділу «Немає доступу», «Читання» чи «Читання і запис»: довідники, склади, постачання, постачальники, товари та залишки, зв’язки товарів із зовнішніми системами, категорії, клієнти та теги, продажі, замовлення з маркетплейсів, витрати, виробництво, вебхуки.
  4. «Зберегти».
Новий ключ API v2
Права «Вибірково»
Ключ створено
Ключ показується один раз

⚠️ Повний ключ (hp_live_…) показується лише один раз — скопіюйте його кнопкою поруч і збережіть у налаштуваннях своєї системи. HugeProfit його не зберігає у відкритому вигляді, тож показати повторно не зможе — лише перевипустити.

Видавайте мінімальні права: сайту, який лише показує залишки, достатньо «Товари та залишки — Читання».

2. Перевірте ключ

Ключ передається в заголовку Authorization до адреси https://crm.h-profit.com/bapi-v2. Найпростіша перевірка — запит GET /bapi-v2/me: у відповідь прийде інформація про ключ і його права. Відповіді завжди мають вигляд {"success": true, "data": …}; при помилці — "success": false і код помилки (401 — неправильний ключ, 403 — бракує прав).

3. Керування ключем

Картка ключа API v2
Кожен ключ — окрема картка: назва, початок ключа, права, статус

«Налаштування» на картці ключа:

Налаштування ключа API v2
  • змінити назву й права («Зміна прав почне діяти протягом 30 секунд»);
  • «Перевипустити ключ» — якщо ключ міг потрапити до сторонніх: старий перестане працювати протягом 30 секунд, вебхуки й отримані замовлення збережуться;
  • «Деактивувати» — тимчасово вимкнути: запити не приймаються, вебхуки не надсилаються (події за цей час не накопичуються);
  • 🗑 видалити — разом з вебхуками ключа і замовленнями з маркетплейсів, прийнятими через нього. Незворотно; для паузи краще деактивувати.

4. Вебхуки

Вебхук — HugeProfit сам надсилає на адресу вашої системи повідомлення, коли щось сталося, — не треба постійно опитувати API. У налаштуваннях ключа → «Вебхуки» → «Додати вебхук» (потрібне право «Вебхуки — Читання і запис»):

Новий вебхук
  • «Подія»: створено, змінено чи видалено продаж; створено або змінено товар; створено або змінено клієнта; змінилися залишки; клієнту надіслано SMS.
  • «Адреса (URL)» — лише https://; «Опис»; «Увімкнена».
  • Після збереження HugeProfit покаже секрет підпису — теж один раз. Ним ваша система перевіряє, що запит справді від HugeProfit (заголовок X-GP-Signature, HMAC-SHA256).

Дії з вебхуком: «Перевірити» — надіслати тестову подію й побачити код і час відповіді, що надіслали й що відповіли; «Журнал» — історія доставок зі статусами «Доставлено», «Помилка, буде повтор», «Не доставлено, спроби вичерпані»; «Змінити», «Перевипустити секрет», «Видалити».

Ваша система має відповісти кодом 2xx протягом 15 секунд. Інакше HugeProfit повторить спробу через 1, 5, 15 і 30 хвилин; після п’ятої невдалої спроби доставка позначається як невдала.

API (v1)

Старіший API, на якому працюють наявні інтеграції. Для нових підключень беріть API v2.

Налаштування API v1
  • «Ключ» — створюється автоматично; «Перегенерувати ключ» — новий ключ (старий перестане працювати).
  • «Канал продажів» — з яким каналом створюватимуться продажі, що прийшли через API.
  • «Доступ до складів» — залишки яких складів доступні через API.
  • «Склад для резервації» — де резервувати товар під замовлення з API.

Опис запитів API v1 — за посиланням «Як підключити?» на картці (SwaggerHub).

Поради

  • Не вставляйте ключ у код сайту, який бачить браузер відвідувача, — лише на сервері.
  • Для повторних запитів на створення продажу використовуйте поле external_id — так продаж не задублюється (детально — у документації).
  • Потрібна допомога з інтеграцією — напишіть у підтримку, вкажіть номер ключа з картки (не сам ключ).

Перш ніж писати власну інтеграцію, перевірте готові інтеграції — можливо, ваш сервіс уже підключається без програмування.

Введіть слово або запитання