Гайд - Платформа

API-ключи

API-ключ - это учётные данные вашего аккаунта для Leadgram API. Управляются они в настройках: здесь вы создаёте ключ, даёте ему имя и отзываете, когда нужно. Разберём, что ключ умеет и чего не умеет, как его создать, как отправить им событие и как ротировать или отозвать.

Зачем нужны API-ключи

API-ключ позволяет внешнему инструменту или скрипту репортить конверсии в Leadgram от вашего имени, не передавая ему логин или сессионную куку. Это механизм для server-to-server интеграций: партнёрская сеть, CRM рекламодателя или собственный скрипт отправляют событие в момент депозита, а не человек кликает в дашборде. Для использования в браузере ключ не предназначен.

Создание ключа

  1. Откройте Настройки → API-ключи.
  2. Дайте ключу название, по которому узнаете его позже, например «Keitaro» или «скрипт отчётов» - это единственное поле в форме.
  3. Нажмите Создать ключ. Секрет показывается ровно один раз, сразу после создания, в блоке для копирования - скопируйте его сейчас же. Ни таблица ключей, ни какой-либо запрос больше не покажут полное значение - сохраняются только название и дата создания.
Панель API-ключей с диалогом создания ключаПанель API-ключей с диалогом создания ключа

Что ключ может и чего не может

Ключ привязан к вашему аккаунту и работает в пределах вашей организации, но полноценным доступом к дашборду он не является:

  • Можно: отправлять события на POST /api/events. Это единственное, что ключ открывает - и на запись, и на чтение.
  • Нельзя: всё остальное - создавать и менять кампании, флоу, ботов, правила постбэков, участников команды, биллинг. Разрушающие операции ключом не выполняются в принципе, так что утёкший ключ не даёт снести ваш аккаунт.
  • Читать данные ключом тоже нельзя. Клики, отчёты, кампании, подписчики, события, биллинг - все эти эндпоинты и все страницы дашборда считают ключ отсутствием доступа. Запрос с ключом куда угодно, кроме POST /api/events, получает 403 или 401, независимо от того, что владельцу ключа доступно в браузере.

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

Отправка события: POST /api/events

Ключ передаётся в заголовке x-api-key:

curl -X POST https://leadgram.org/api/events \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clickId": "tz4k9m2p1xq7v0b3n8s6d5fg",
    "type": "deposit",
    "payout": 42.50,
    "nonce": "crm-conversion-8813",
    "payload": { "telegram_user_id": 123456789 }
  }'

Поля тела:

  • clickId - обязательное. Id клика, который выдал Leadgram: это то значение, что приходит к вам из макроса {click_id} в URL оффера, редиректа кампании или лендинга. Клик чужой организации не подойдёт.
  • type - обязательное, одно из: click, land, bot_start, channel_join, join_request, first_dm, miniapp_launch, lead, registration, deposit, ftd, purchase, subscription_renewed, subscription_cancelled, custom_1-custom_8. Принимать тип и производить его - разные вещи: у click, land и first_dm внутри Leadgram продюсера нет, они существуют только потому, что вы их прислали; а у bot_start, channel_join, join_request, miniapp_launch, purchase и обоих subscription_* продюсер внутри Leadgram уже есть - пришлёте их вручную, рядом с автоматическим появится второе событие. Единственное исключение - bot_start, и оно с условиями: ваш вызов сойдётся с уже записанным стартом, только если несёт telegram user id в payload (без него - 422, bot_start_missing_telegram_user_id) и в запросе есть чем назвать бота, которого запустил человек - payload.bot_username или payload.bot_id, а если их нет, то бот названного clickId. У клика из обычной редирект-кампании бота нет, как и у клика, чьего бота удалили: такой вызов без bot_username/bot_id пару назвать не может и запишется отдельным событием. Второго списания это вам не стоит - Leadgram списывает один раз за человека на рабочее пространство, а Telegram-аккаунт узнаёт этого человека всегда, так что дубль бесплатен, - но в Meta уйдёт второй Lead с другим event_id, свести который никакая дедупликация уже не сможет, и оптимизатор вашей кампании выучит, что один человек сконвертился дважды. Подробности в Событиях и конверсиях.
  • payout - необязательное. Выплата по этой конверсии: число от 0 до 1 000 000 (строка вида "42.50" тоже принимается, отрицательные значения отклоняются). Если поле не передать, конверсия унаследует «Выплату» оффера, привязанного к клику.
  • nonce - необязательное, от 1 до 128 символов. Ключ идемпотентности: id события выводится из тройки clickId + type + nonce, поэтому повтор того же запроса не создаст вторую строку и не задвоит ни списание, ни постбэки, ни конверсии в рекламных кабинетах. А вот две действительно разные конверсии одного клика (второй депозит) обязаны прислать разный nonce. Вместо поля можно передать заголовок Idempotency-Key - он подхватывается как запасной источник того же значения.
  • payload - необязательный объект произвольной формы, но три ключа внутри него платформа разбирает отдельно. По telegram_user_id считается биллинг и работает дедупликация постбэков по пользователю. bot_username и bot_id относятся только к bot_start и называют бота, которого человек на самом деле запустил: @имя (со знаком @ или без) либо внутренний id бота в Leadgram. Оба необязательны, но их стоит присылать, как только у вас больше одного бота: без них пара опирается на бота из клика, а это догадка, и она неверна, когда клик пришёл из кампании с другим ботом. Имя, которое не принадлежит вашим ботам, получает 403, а не тихий откат к догадке.

Успешный ответ - 201 с созданной строкой события. 400 означает, что тело не прошло валидацию, 403 - клик не найден или принадлежит другой организации, 401 - ключ не принят. Эндпоинт держит 300 запросов в минуту на организацию; сверх этого приходит 429 с заголовком Retry-After.

Ротация и отзыв

Механизма «перегенерировать на месте» нет - секрет ключа фиксирован на всё время его жизни. Чтобы ротировать ключ: сначала создайте новый, подставьте его в интеграцию, убедитесь, что события проходят, и только потом отзовите старый ключ в таблице, чтобы ничего не осталось работать на нём. Отзыв происходит мгновенно - нажмите Отозвать в строке ключа, и он сразу перестаёт работать, без периода на переезд, поэтому сначала переключайтесь, потом отзывайте, а не наоборот.

Частые грабли

  • Секрет показывается один раз, при создании. Закрыли диалог, не скопировав, - он потерян навсегда: отзывайте ключ и создавайте новый.
  • Ключ пишет конверсии в вашу организацию, так что утёкший ключ - это чужие события в вашей аналитике и в ваших списаниях. Читать данные и трогать аккаунт им нельзя, но это всё равно ваши деньги и ваши отчёты: не вставляйте ключ в чат поддержки, публичный репозиторий или общий скрипт, а если утёк - ротируйте.
  • Забытый nonce на ретраях. Без него повторная отправка того же события схлопнется в одну строку, и это хорошо, но вторая настоящая конверсия по тому же клику без нового nonce потеряется точно так же.
  • Чужой или устаревший clickId даёт 403, а не тихий успех: событие никуда не запишется, и молчание в отчётах будет означать именно это.
  • У отзыва нет отмены и нет задержки: любая интеграция, которая всё ещё использует старый ключ, сразу начинает падать.
  • Называйте ключи по тому, куда они подключены (например «Keitaro prod»), чтобы точно знать, какой отзывать, когда что-то сломалось, а не гадать по голой дате создания.