Подключить API для заявок
Как создать API-ключ студии, отправить контрольную заявку с сервера и проверить, что повтор запроса не создает дубль. Методы, права и коды ошибок.
В этой инструкции
- Для кого
- Владелец или администратор студии и разработчик интеграции.
- Что подготовить
- Активный доступ к нужной студии, право управлять API-ключами и сервер с Node.js 24 для контрольного примера.
От ключа до заявки в CRM
- Откройте CRM нужной студии и перейдите в Настройки → Коммуникации → API и интеграции («Налаштування» → «Комунікації» → «API та інтеграції»).
- Нажмите Создать 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-ключ.