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

API-ключі

API-ключ - це облікові дані вашого акаунта для Leadgram API. Керуються вони в налаштуваннях: тут ви створюєте ключ, даєте йому ім'я і відкликаєте, коли потрібно. Розберемо, що ключ уміє і чого не вміє, як його створити, як надіслати ним подію і як його ротувати чи відкликати.

Навіщо потрібні API-ключі

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

Створення ключа

Відкрийте Налаштування → API-ключі.
Дайте ключу назву, за якою впізнаєте його пізніше, наприклад «Keitaro» чи «скрипт звітів» - це єдине поле у формі.
Натисніть Створити ключ. Секрет показується рівно один раз, одразу після створення, у блоці для копіювання - скопіюйте його зараз же. Ні таблиця ключів, ні жоден запит більше не покажуть повне значення - зберігаються лише назва і дата створення.

Що ключ може і чого не може

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

Можна: надсилати події на 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»), щоб точно знати, який відкликати, коли щось зламалося, а не гадати за голою датою створення.