Kelvaro API

Авторизация

Ключ выпускает владелец рекламного кабинета у себя в Kelvaro: «Интеграции» → «API для сторонних сервисов». Ключ привязан к одной учётной записи и открывает только её данные.

Он передаётся заголовком X-API-Key в каждом запросе:

curl -H "X-API-Key: kv_live_…" \
     https://kelvaro.mtech.kz/api/v1/ping

Клиент может отозвать ключ в любой момент — обращения по нему перестают проходить сразу, и приходит 401. Ключ показывается клиенту один раз при выпуске: у нас хранится только его отпечаток, поэтому «напомнить» ключ мы не сможем, его придётся выпустить заново.

Проверка ключа. Ничьих данных не трогает — нужна, чтобы отличить «ключ не тот» от «запрос не тот».

Ответ

{
  "ok": true,
  "account_id": "u_8c93bc2c…",
  "scope": "stats:read"
}

Ни почты, ни имени клиента здесь нет: для проверки ключа они не нужны.

Проекты клиента. Проект — это одна рекламная площадка; его id нужен, чтобы запросить статистику. Отдаются только активные.

Ответ

{
  "data": [
    {
      "id": "p_1f4c…",
      "name": "Стоматология — Meta",
      "platform": "meta",
      "platform_label": "Meta",
      "status": "active"
    }
  ]
}

Возможные platform: meta, tiktok, google, yandex. Статистика собирается по всем четырём; площадка без сборщика ответила бы 501 no_collector.

Итоги и разбивка по кампаниям за период по одному проекту.

Параметры

Запрос

curl -H "X-API-Key: kv_live_…" \
     "https://kelvaro.mtech.kz/api/v1/stats?project=p_1f4c…&period=month"

Ответ

{
  "project":  { "id": "p_1f4c…", "name": "…", "platform": "meta" },
  "period":   { "code": "month", "label": "Месяц",
                "range": "1 — 30 июля 2026" },
  "currency": "KZT",
  "generated_at": "22.08.2026 11:40",
  "totals": {
    "spend": 184300.0, "impressions": 412887, "clicks": 6104,
    "reach": 233410, "leads": 128, "purchases": 14, "revenue": 1260000.0,
    "ctr": 1.4783, "cpc": 30.19, "cpl": 1439.84, "cpp": 13164.29,
    "roas": 6.8367
  },
  "campaigns": [
    { "name": "Импланты — WhatsApp", "spend": 96100.0, "clicks": 3312,
      "impressions": 210044, "reach": 130876, "leads": 81, "purchases": 0,
      "revenue": 0.0, "ctr": 1.5768, "cpc": 29.01, "cpl": 1186.42,
      "cpp": null, "roas": null }
  ]
}

Поля

Числа приходят числами, а не строками: форматирование — дело принимающей стороны. Валюта одна на весь ответ и лежит в currency.

Продажи из переписки

POST /api/v1/conversions — сообщить, что переписка, начатая с рекламы Meta, закончилась продажей. Мы отправляем событие в Meta Conversions API от имени рекламного кабинета клиента; Meta привязывает продажу к объявлению, она появляется в purchases и revenue, а алгоритм начинает искать похожих на тех, кто купил.

Нужен ключ с правом «Передавать продажи» — клиент отмечает его при выпуске. Ключ только для чтения получит 403 forbidden.

Когда отправлять

Один раз, когда сделка оплачена. Повтор с тем же event_id безопасен: уже принятое событие повторно в Meta не уходит, ответ — "duplicate": true. Поэтому при таймауте просто повторяйте запрос.

Тело запроса (JSON)

Номер телефона, имя и текст переписки не передавайте: для привязки к рекламе они не нужны, и мы их не принимаем.

Запрос

curl -X POST -H "X-API-Key: kv_live_…" \
     -H "Content-Type: application/json" \
     "https://kelvaro.mtech.kz/api/v1/conversions" \
     -d '{ "event_id": "deal-48213", "channel": "whatsapp",
           "ctwa_clid": "ARAkLkA8rmlFeiCk…",
           "value": 90000, "currency": "KZT" }'

Ответ

{ "status": "sent", "duplicate": false,
  "event_id": "deal-48213", "project": "p_1f4c…" }

Ошибки этого метода

Ошибки

Тело ошибки всегда одной формы. Завязываться нужно на code, а не на текст сообщения: текст мы можем уточнить, код — нет.

{ "error": { "code": "unauthorized", "message": "…" } }

Коротко: 4xx без api — повторять бессмысленно, нужно действие человека; 502 — временно, повторить позже.

Лимиты и кэш

Ответ /api/v1/stats кэшируется на нашей стороне на 5 минут. За ним стоит обращение в API рекламной площадки, у которой есть собственная квота на токен клиента, — опрашивать чаще смысла нет, вернутся те же цифры.

Разумный режим для интерфейса, где цифры показываются рядом с перепиской: запрашивать при открытии карточки и не чаще раза в 5 минут при обновлении.

Ответы отдаются с Cache-Control: no-store — это данные конкретного клиента, и оседать в промежуточных кэшах они не должны.