Підключити API для заявок
Створити ключ студії, передати контрольну заявку із сервера та перевірити повтор без дубля.
У цій інструкції
- Для кого
- Власник або адміністратор студії та розробник інтеграції.
- Що підготувати
- Активний доступ до потрібної студії, право керувати API-ключами та сервер із Node.js 24 для контрольного прикладу.
Від ключа до заявки у CRM
- Відкрийте CRM потрібної студії та перейдіть у Налаштування → Комунікації → API та інтеграції.
- Натисніть «Створити API-ключ», задайте назву й строк дії. Для прикладу виберіть обидва права: «Читати заявки» (leads.read) і «Створювати заявки» (leads.create).
- Збережіть одноразово показаний секрет у змінній середовища CLUBBASE_API_KEY на сервері інтеграції. Не вставляйте його в код публічної сторінки, браузерний запит або URL.
- Завантажте «Серверний приклад (Node.js)» за посиланням унизу та виконайте кроки розділу «Контрольний запуск».
- Відкрийте «Заявки» у цій самій CRM та знайдіть «Приклад API» за контрольним email із вашим UUID. Після успіху приклад повертає ID цієї заявки, replay: same_result і read: PASS.
Доступні методи
Ключ працює лише зі студією, яка його видала. Передавайте його в заголовку Authorization: Bearer. Склад полів, відповіді, пагінацію та квоти описує документація API; OpenAPI JSON доступний за окремим посиланням.
| Метод | Право | Результат |
|---|---|---|
| POST /v1/integrations/leads | leads.create | Створення заявки; потрібен Idempotency-Key з UUID цієї операції. |
| GET /v1/integrations/leads/{id} | leads.read | Поточний стан заявки за її ID. |
| GET /v1/integrations/leads | leads.read | Список заявок частинами через limit і cursor. |
Контрольний запуск
Приклад записує одну контрольну заявку «Приклад API» з email у домені example.test у студію вашого ключа. Він надсилає два однакові запити створення та читає результат за ID. Це перевірка вашого підключення; її запуск створює запис у CRM.
- Збережіть завантажений файл як integration-leads.mjs на сервері з Node.js 24.
- У серверному середовищі задайте CLUBBASE_API_URL=https://api.clubbase.fit без /v1 наприкінці та CLUBBASE_API_KEY зі збереженим секретом.
- Згенеруйте UUID, збережіть його та задайте як CLUBBASE_REQUEST_ID. Для повтору цієї контрольної заявки залишайте той самий UUID.
- Запустіть node integration-leads.mjs. Після втраченої відповіді повторіть запуск із тим самим CLUBBASE_REQUEST_ID. Без цієї змінної кожен запуск генерує новий UUID і створює нову контрольну заявку.
Заміна ключа та повтор запиту
«Замінити секрет» одразу вимикає старий секрет, але зберігає ID інтеграції та історію повторів. Оновіть CLUBBASE_API_KEY на сервері; для повтору попередньої операції збережіть її UUID і ті самі дані. Новій заявці потрібен новий UUID.
«Відкликати» остаточно вимикає ключ. Прострочений ключ також не працює. Якщо людина, яка видала ключ, втратила потрібні права, власник або адміністратор має замінити секрет. Призупинення доступу до студії зупиняє API-запити.
Поточний API охоплює створення й читання заявок.
Результат
Контрольна заявка є у потрібній CRM; повтор тієї самої операції повертає початковий результат без дубля, а GET за ID показує поточний стан.
Якщо не вийшло
Для 401 перевірте секрет, строк і відкликання; для 403 — права ключа та його поточного видавця; для 402 — стан доступу до студії. Для 409 перевірте UUID, незмінність даних повтору та наявну відкриту заявку цього контакту. Після 429 дочекайтеся строку Retry-After; для 503 повторіть пізніше з тим самим UUID. Повний перелік кодів і квот є в документації API. Пароль або браузерна сесія не замінюють API-ключ.