Розробникам

Довідник з 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 + цього значення, тож повтор того самого запиту не створить другий рядок і не задвоїть ні списання, ні постбеки, ні конверсії в рекламних кабінетах. Зворотний бік: дві справді різні конверсії по одному кліку - другий депозит - мають нести різний ключ, інакше друга схлопнеться в першу і зникне. Повна модель дедуплікації - в Подіях і конверсіях.