Authentication

Все inbound-запросы партнёра обязаны нести три заголовка:

Authorization: Bearer <api_key>
X-Signature:   sha256=<HMAC-SHA256(raw_body, hmac_secret)>
X-Timestamp:   <unix seconds>

Отсутствие или несовпадение любого — приведёт к отклонению запроса с 401 / 403.

Bearer token

api_key — это длинная строка вида ccrm_live_4f7a9.... Идентифицирует партнёра. Передаётся в заголовке Authorization: Bearer <api_key>.

При ротации ключа (POST /api/affiliates/{id}/rotate-key) старый сразу становится недействительным — у клиентов с обоими ключами параллельной работы нет.

Что случится	Код	error
Нет заголовка	401	missing_bearer
Не наш ключ	401	invalid_api_key
Партнёр в архиве / paused	401	invalid_api_key

HMAC signature

Каждый запрос подписывается поверх raw body (байт-в-байт того, что улетает по сети, без переформатирования JSON, без пробелов между ключами, если они есть, и т.д.).

Формула:

signature = HMAC-SHA256(body, hmac_secret)
header    = "sha256=" + hex(signature)

Заголовок:

X-Signature: sha256=8a7b...e4

Подписывайте именно те байты, что улетают на сервер

Если ваш HTTP-клиент по дороге переформатирует JSON (как часто делают axios / requests при работе с объектами), подпись не совпадёт. Самое надёжное — собрать строку JSON один раз, посчитать подпись от неё и отправить ту же строку как тело.

Что случится	Код	error
Подпись не совпала	403	bad_signature
IP не в whitelist (если включён)	403	ip_not_allowed

См. HMAC подпись для пошаговой инструкции с примерами вычислений.

X-Timestamp (анти-replay)

X-Timestamp: 1748390000

Unix-время в секундах. Сервер сверяет с локальным временем и отбрасывает запросы, у которых дрифт > 300 секунд (5 минут).

Что случится	Код	error
Нет заголовка / не число	401	missing_timestamp
Дрифт > 5 минут	401	timestamp_out_of_range

Синхронизация времени

Если регулярно ловите timestamp_out_of_range — проверьте NTP на ваших серверах. Особенно актуально для виртуалок с уехавшим временем.

IP whitelist (опционально)

При желании менеджер может включить для вашего партнёра IP-whitelist — список адресов, с которых разрешено слать лиды. Запросы с других IP вернут 403 ip_not_allowed.

По умолчанию whitelist пустой — запросы принимаются с любого IP, если HMAC и Bearer ок.

Сводный пример валидного запроса

POST /v1/inbound/leads HTTP/1.1
Host: cartelcrm.com
Authorization: Bearer ccrm_live_4f7a9c2e8b1d3a5f7e9c1b2d4a6f8e0c
X-Signature: sha256=8a7b3c2d1e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b
X-Timestamp: 1748390000
Idempotency-Key: aff42-lead-2026-05-27-001
Content-Type: application/json
Content-Length: 247

{"external_id":"aff42-lead-001","first_name":"Иван","last_name":"Петров","phone":"+380501234567","email":"ivan@example.com","country":"UA","source":"facebook_ads"}