POST/v1/integrations/leads
Создать заявку
Передаёт имя и контакт в текущую студию. Idempotency-Key защищает повтор после потерянного ответа.
Нужное право: leads.create
Публичный API · версия 1.0.0
Сервер вашего сайта создаёт заявку в нужной студии и читает её состояние. Ключ открывает только ту студию, которая его выдала.
Адресhttps://api.clubbase.fit
В студии может быть до 20 ключей, срок действия нового — до 366 дней. Замена сразу отключает предыдущий секрет; отзыв окончательный. Cookie входа в CRM ключ не заменяет.
Открыть свою CRMКлюч передаётся заголовком Authorization: Bearer …. Для создания заявки нужен ещё Idempotency-Key — любой UUID, который вы храните вместе с заявкой.
curl -X POST https://api.clubbase.fit/v1/integrations/leads \
-H "Authorization: Bearer $CLUBBASE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen | tr 'A-Z' 'a-z')" \
-d '{
"displayName": "Пример API",
"contact": {
"type": "email",
"value": "[email protected]"
},
"sourceId": null,
"note": "Контрольная заявка интеграции"
}'import { randomUUID } from 'node:crypto';
// Ключ берётся из переменных окружения, никогда из кода страницы.
const response = await fetch('https://api.clubbase.fit/v1/integrations/leads', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.CLUBBASE_API_KEY}`,
'Content-Type': 'application/json',
// Повтор с тем же ключом вернёт ту же заявку, а не вторую.
'Idempotency-Key': randomUUID(),
},
body: JSON.stringify({
"displayName": "Пример API",
"contact": {
"type": "email",
"value": "[email protected]"
},
"sourceId": null,
"note": "Контрольная заявка интеграции"
}),
});
if (!response.ok) {
const problem = await response.json();
throw new Error(`${problem.status} ${problem.code}: ${problem.detail}`);
}
const lead = await response.json();<?php
// Ключ читается из окружения сервера, а не из кода страницы.
// Idempotency-Key должен быть именно UUID: 32 hex-символа без дефисов API отклонит.
$bytes = random_bytes(16);
$bytes[6] = chr(ord($bytes[6]) & 0x0f | 0x40);
$bytes[8] = chr(ord($bytes[8]) & 0x3f | 0x80);
$idempotencyKey = vsprintf('%s%s-%s-%s-%s-%s%s%s', str_split(bin2hex($bytes), 4));
$ch = curl_init('https://api.clubbase.fit/v1/integrations/leads');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('CLUBBASE_API_KEY'),
'Content-Type: application/json',
'Idempotency-Key: ' . $idempotencyKey,
],
CURLOPT_POSTFIELDS => json_encode([
'displayName' => "Пример API",
'contact' => [
'type' => "email",
'value' => "[email protected]",
],
'note' => "Контрольная заявка интеграции",
], JSON_UNESCAPED_UNICODE),
]);
$response = curl_exec($ch);Успех возвращает 201 и тело заявки с её идентификатором. Повтор того же Idempotency-Key вернёт ту же заявку, а не вторую.
POST/v1/integrations/leads
Передаёт имя и контакт в текущую студию. Idempotency-Key защищает повтор после потерянного ответа.
Нужное право: leads.create
GET/v1/integrations/leads/{id}
Возвращает разрешённые поля одной заявки. Чужой или неизвестный ID возвращает 404.
Нужное право: leads.read
GET/v1/integrations/leads
Читает заявки постранично. Значение nextCursor передайте в следующий запрос без изменений.
Нужное право: leads.read
curl "https://api.clubbase.fit/v1/integrations/leads?limit=20" \
-H "Authorization: Bearer $CLUBBASE_API_KEY"curl https://api.clubbase.fit/v1/integrations/leads/$LEAD_ID \
-H "Authorization: Bearer $CLUBBASE_API_KEY"Список отдаётся страницами. limit — от 1 до 100, по умолчанию 25. Ответ содержит nextCursor: передайте его в следующий запрос параметром cursor без изменений. nextCursor: null значит, что страниц больше нет.
Сеть обрывает ответ чаще, чем кажется. Если вы не дождались ответа, повторите тот же запрос с тем же Idempotency-Key: ClubBase вернёт исходный результат и не создаст вторую заявку.
Тот же ключ с другим телом — это ошибка 409 integration_idempotency_conflict: так видно, что где-то потерялось состояние, и дубль не создаётся молча.
Если запустить пример дважды с новым Idempotency-Key и тем же контактом, ответ будет 409 integration_lead_already_open. Это не ошибка интеграции: в студии уже есть открытая заявка от этого человека, и ClubBase не заводит вторую. Чтобы проверить повтор, меняйте ключ вместе с контактом, а не по отдельности.
Ответ с ошибкой — application/problem+json с полями status, code, detail.
| Код | Идентификатор | Когда возникает |
|---|---|---|
| 400 | integration_invalid_request | Неизвестное поле, неверный контакт или cursor либо нет UUID в Idempotency-Key. |
| 401 | integration_key_invalid | Ключ не передан, отозван, заменён или срок его действия истёк. |
| 402 | subscription_suspended | Доступ к студии приостановлен. |
| 403 | integration_scope_forbidden | Ключ не разрешает эту операцию. |
| 403 | integration_issuer_forbidden | Текущие права того, кто выдал ключ, больше не разрешают интеграцию. |
| 404 | integration_lead_not_found | Заявка недоступна в студии этого ключа. |
| 409 | integration_idempotency_conflict | Тот же Idempotency-Key использован с другими данными. |
| 409 | integration_lead_already_open | У контакта уже есть открытая заявка. |
| 400 | integration_source_invalid | Источник заявки не принадлежит этой студии или отключён. |
| 429 | integration_rate_limited | Подождите столько секунд, сколько указано в Retry-After. |
| 503 | integration_rate_unavailable | Проверка квоты временно недоступна; запись не выполнена. |
429 приходит с заголовком Retry-After — это количество секунд до следующей попытки. Соблюдайте его: иначе следующий ответ будет таким же.
Опишите, что должно передаваться в ClubBase и в какую сторону, — разберём ваш сценарий.
Написать команде