Getting started

Эта страница даёт минимально-достаточный набор шагов, чтобы залить ваш первый тестовый лид и получить callback. Подробности по каждому шагу — в отдельных разделах.

1. Получите креды

После создания вас как партнёра в Cartel CRM менеджер передаст вам три секрета:

Поле	Описание
api_key	Bearer-токен для аутентификации. Уникальный, ротируемый.
hmac_secret	Ключ для подписи ваших исходящих запросов в нашу сторону.
callback_secret	Ключ для подписи наших исходящих callback'ов в вашу сторону.

Эти секреты показываются один раз

Менеджер видит их в окне создания партнёра, а потом — никогда. Если потеряете — нужно ротировать (POST /api/affiliates/{id}/rotate-key), старый ключ становится недействителен. Храните в секретах CI/CD или secret manager, не в коде.

2. Базовый URL

Окружение	Base URL
Production	https://cartelcrm.com/api
Staging	https://staging.cartelcrm.com/api

Все партнёрские endpoint'ы живут под префиксом /v1/inbound/.... Версионирование — через URL (v1), breaking changes выпускаются как v2 и существуют параллельно с v1 минимум 6 месяцев.

3. Соберите запрос

Минимальный запрос для приёма лида:

POST /v1/inbound/leads HTTP/1.1
Host: cartelcrm.com
Authorization: Bearer ccrm_live_XXXXXXXXXXXXXXXX
X-Signature: sha256=<HMAC-SHA256(body, hmac_secret)>
X-Timestamp: 1748390000
Idempotency-Key: aff42-lead-2026-05-27-001
Content-Type: application/json

{
  "external_id": "aff42-lead-001",
  "first_name": "Иван",
  "last_name": "Петров",
  "phone": "+380501234567",
  "email": "ivan@example.com",
  "country": "UA",
  "language": "ru",
  "source": "facebook_ads",
  "funnel": "crypto-v3",
  "sub_id": "sub-789",
  "click_id": "fb-click-abc"
}

Минимальное обязательное поле — phone

Всё остальное опционально, но чем больше контекста — тем точнее распределение и тем выше конверсия. Минимум, который мы советуем для боевой интеграции: phone, country, source, external_id.

4. Поймайте ответ

Успешный приём:

{
  "id": "le-12345",
  "status": "accepted",
  "reason": null,
  "duration_ms": 42
}

Возможные status:

Значение	HTTP	Что это значит
accepted	200	Лид принят, распределён, попал в работу.
duplicate	409	Найден дубль в окне дедупликации.
validation_error	422	Не прошёл валидацию (см. поле reason).
rejected	422	Отклонён бизнес-правилами (страна, гео-блок и т.п.).

При duplicate поле id всё равно вернётся — это id уже существующего лида.

5. Получите callback

Если при создании партнёра вы указали callback_url, мы пришлём POST на этот URL, когда лид сменит статус (например, lead.accepted, lead.ftd):

POST /your/callback HTTP/1.1
X-Signature: sha256=<HMAC-SHA256(body, callback_secret)>
X-Timestamp: 1748390123
X-Event: lead.ftd
Content-Type: application/json
User-Agent: CartelCRM-Webhook/1.0

{
  "event": "lead.ftd",
  "external_lead_id": "aff42-lead-001",
  "internal_id": "le-12345",
  "status": "ftd",
  "our_status": "ftd",
  "is_depositor": true,
  "timestamp": "2026-05-27T14:22:03+00:00"
}

Ваша задача:

1. Прочитать X-Signature и сверить с HMAC-SHA256(raw_body, callback_secret).
2. Проверить, что X-Timestamp не старше 5 минут.
3. Вернуть 200 OK за ≤10 секунд. Любой другой ответ — будет ретрай.

Никаких денег

В payload callback'а никогда нет amount, currency, ftd_amount. Это договорное ограничение — финансовая часть остаётся только на нашей стороне. См. Callbacks.

Что дальше

• Authentication — детально о Bearer + HMAC.
• HMAC подпись — пошаговая инструкция со скриншотами вычисления.
• Field mapping — если ваш payload не похож на наш канонический.
• Lead lifecycle — какие бывают статусы и как они меняются.
• Examples — готовые сниппеты на cURL / Node / PHP / Python.