Разработчикам

Справочник по API

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

Аутентификация

Каждый запрос аутентифицируется заголовком x-api-key с секретом, который вы выпускаете в разделе Настройки → API-ключи. Как создавать, называть, ротировать и отзывать ключи - в API-ключах.

Ключ - это не сессия. Он открывает ровно один маршрут - POST /api/events - и больше ничего. Клики, постбэки, отчёты, кампании, подписчики, биллинг и даже GET /api/events: любой другой эндпоинт и любая страница дашборда считают ключ отсутствием доступа и отвечают 401 или 403, что бы его владельцу ни было доступно в браузере. Запрос к /api/auth/* с ключом отклоняется сразу с 403.

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

POST /api/events

Один эндпоинт, один метод. Он записывает событие-конверсию на клик, принадлежащий вашей организации. Тело - JSON; минимум - это clickId плюс type.

  • clickId (строка, обязательно) - id клика от Leadgram, то значение, что пришло к вам из макроса {click_id}. Клик чужой организации отклоняется.
  • type (строка, обязательно) - один тип события воронки или конверсии: land, bot_start, registration, lead, deposit, ftd, purchase и остальные из Событий и конверсий.
  • payout (число, необязательно) - сумма платящей конверсии (deposit, ftd, ...). Она питает колонку «Доход» в отчётах и уходит как ценность конверсии в рекламный кабинет. Строка вида "42.50" принимается, отрицательные значения отклоняются.
  • payload (объект, необязательно) - произвольная форма, прокидывается в событие. telegram_user_id внутри него - ключ для биллинга и дедупликации по пользователю; bot_username / bot_id называют бота для bot_start.

Отправка через curl:

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

Ответы:

  • 201 - записано. В теле - созданная строка события.
  • 400 - тело не прошло валидацию: нет clickId, неизвестный type, отрицательный payout.
  • 401 - ключ не принят или креденшл не прислан вовсе.
  • 403 - клик не найден или принадлежит другой организации (и то же самое получает ключ на любом маршруте, кроме этого).
  • 422 - bot_start без telegram user id в payload (bot_start_missing_telegram_user_id); принять его - значит задвоить списание против старта, который Leadgram уже записал.
  • 429 - превышен лимит; отступите и повторите после окна (см. ниже).

Постбэки (исходящие)

Постбэки идут в обратную сторону: на каждую конверсию, которую Leadgram записывает, он server-to-server дёргает S2S-URL вашего партнёрского трекера, чтобы регистрации и депозиты оставались видны в Keitaro или RedTrack, где вы оптимизируете. Настраиваются они в приложении, а не через API-ключ - правило это триггер-событие, шаблон URL и метод, сохранённые на Постбэках. Пресеты предзаполняют шаблон: Keitaro, RedTrack или Custom с чистого листа, с макросами вроде {click_id}, {event_type} и {sub1}-{sub5}, которые подставляются при каждом срабатывании. Payout макросом постбэка не является - он едет с событием, а не с постбэком. Полный список макросов, порядок связки и логика ретраев - в гайде по постбэкам.

Лимиты и идемпотентность

Эндпоинт событий держит примерно 300 запросов в минуту на организацию. Сверх этого приходит 429 с заголовком Retry-After и заголовками X-RateLimit-*, называющими потолок и момент сброса, - выждите указанный интервал вместо того, чтобы долбить.

Ретраи безопасны, если сделать их идемпотентными. Пришлите заголовок Idempotency-Key (или поле nonce в теле), и id события выведется из clickId + type + этого значения, поэтому повтор того же запроса не создаст вторую строку и не задвоит ни списание, ни постбэки, ни конверсии в рекламных кабинетах. Обратная сторона: две действительно разные конверсии по одному клику - второй депозит - обязаны нести разный ключ, иначе вторая схлопнется в первую и пропадёт. Полная модель дедупликации - в Событиях и конверсиях.