Реферальная система

Набор методов для работы с реферальной программой бота: выдача реферальных кодов, статистика по приглашённым пользователям, баланс вознаграждений и выплаты.

Во всех методах под «пользователем» понимается Telegram-пользователь вашего бота, и он передаётся как user_id (это Telegram ID, а не ваш внутренний ID).

Как это работает в двух словах

Вы создаёте реферальный код для пользователя (create-code) и даёте ему ссылку вида https://t.me/your_bot?start=КОД.
Когда по этой ссылке переходит новый человек, он автоматически засчитывается как приглашённый (referral) этому пользователю.
Если вы используете свои собственные коды (не выданные этим API) — сообщите систему, кому какой код принадлежит, через set-code-owners.
Узнать, сколько человек привёл пользователь и сколько ему причитается — методы referrals и balance.
Когда пользователь хочет вывести вознаграждение — вызовите payout.
Если начисление оказалось ошибочным — его можно отменить через reverse-accrual.

Реферальная система подробней описана в этом разделе

1. Создать реферальный код

POST /v1/referral/create-code (также поддерживается GET)

Создаёт новый уникальный реферальный код для пользователя и сразу отдаёт готовую ссылку-приглашение. Один и тот же пользователь может иметь сколько угодно кодов — каждый вызов создаёт новый код, старые при этом не отзываются.

Параметры

Параметр

Тип

Обязательный

Описание

user_id

int

да

Telegram ID пользователя, для которого создаётся код (реферер)

Пример вызова

GET /v1/referral/create-code?user_id=123456789

Ответ

{  
    "ok": true,  
    "data": {    
        "code": "kT7xQm2p",
        "link": "https://t.me/your_bot?start=kT7xQm2p"  
    }
}

Поле

Тип

Описание

code

string

Сам код, 8 символов. Цифры и буквы без похожих друг на друга символов (нет 0, O, 1, l, I), чтобы код было легко прочитать и ввести вручную

link

string|null

Готовая ссылка-приглашение вида https://t.me/<бот>?start=<код>. Будет null, если у бота не определён username

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте заголовок Api-Key / параметр api-key

500

Внутренняя ошибка сервера

Повторите запрос позже; если повторяется — обратитесь в поддержку

2. Привязать владельца к коду (set-code-owners)

POST /v1/referral/set-code-owners

Этот метод нужен только в одном случае: если ваш бот сам генерирует или раздаёт реферальные коды (не через create-code), а нашей системе об этом неизвестно. Метод сообщает: «вот этот код принадлежит вот этому пользователю».

Дополнительный эффект — бэкофилл: если по этому коду уже были переходы до того, как вы сообщили владельца, все они задним числом будут засчитаны этому пользователю как приглашённые.

Можно передать сразу несколько кодов в одном запросе.

Рекомендуем, по возможности передавать кода заранее, это положительно скажется при построении возможных отчетов в будущем

Параметры (тело запроса — массив объектов)

Параметр

Тип

Обязательный

Описание

code

string

да

Реферальный код

user_id

int

да

Telegram ID владельца кода (реферера)

Пример вызова

POST /v1/referral/set-code-owners

 [
  { 
    "code": "ABC123", 
    "user_id": 123456789 
  },
  { 
    "code": "XYZ789",
    "user_id": 987654321 
  }
]

Ответ

{  
    "ok": true,  
    "data": {    
        "results": [      
            { 
                "code": "ABC123", 
                "owner_id": 123456789, 
                "created": false, 
                "backfilled": 5 
            },  
            { 
                "code": "XYZ789", 
                "owner_id": 987654321, 
                "created": true, 
                "backfilled": 0 
            }
        ] 
    }
}

Поле

Тип

Описание

code

string

Код, который был обработан

owner_id

int

Telegram ID, который был привязан к коду

created

bool

true — кода раньше не существовало, он был зарегистрирован прямо сейчас. false — код уже существовал, и ему просто назначили владельца

backfilled

int

Сколько прошлых переходов по этому коду задним числом получили этого владельца как реферера

Возможные ошибки

Код

Когда возникает

Как исправить

400

Тело запроса не массив или пустой массив

Передайте непустой JSON-массив объектов

400

В одном из объектов отсутствует code или user_id (или user_id равен 0)

Проверьте, что в каждом объекте заполнены оба поля

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

3. Список кодов пользователя

GET /v1/referral/codes

Возвращает все реферальные коды, выданные конкретному пользователю через create-code, плюс общее число приглашённых им людей (по всем его кодам сразу).

Параметры

Параметр

Тип

Обязательный

Описание

user_id

int

да

Telegram ID пользователя

Пример вызова

GET /v1/referral/codes?user_id=123456789

Ответ

{
  "ok": true,
  "data": {
    "total_referrals": 12,
    "codes": [
      {
        "code": "kT7xQm2p",
        "link": "https://t.me/your_bot?start=kT7xQm2p",
        "date_create": "2026-06-10 14:32:01"
      }
    ]
  }
}

Поле

Тип

Описание

total_referrals

int

Сколько всего людей привёл этот пользователь (по всем его кодам)

codes

array

Список кодов, от новых к старым

codes[].code

string

Код

codes[].link

string|null

Готовая ссылка-приглашение

codes[].date_create

string

Дата и время создания кода (YYYY-MM-DD HH:MM:SS, UTC)

Метод показывает только коды, созданные через create-code. Коды, привязанные через set-code-owners без предварительного создания, в этом списке не появятся.

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

4. Список приглашённых пользователей

GET /v1/referral/referrals

Возвращает список людей, которых пользователь привёл по своим реферальным кодам (по всем кодам сразу), с датой перехода каждого.

Параметры

Параметр

Тип

Обязательный

По умолчанию

Описание

user_id

int

да

—

Telegram ID реферера

limit

int

нет

Сколько записей вернуть за раз (от 1 до 200; значения вне диапазона будут автоматически округлены до границ)

offset

int

нет

Сколько записей пропустить с начала списка — используется для постраничной выгрузки

Пример вызова

GET /v1/referral/referrals?user_id=123456789&limit=20&offset=0

Ответ

{
  "ok": true,
  "data": {
    "referrals": [
      { "referral_id": 555111222, "date": "2026-06-15 09:12:44" }
    ]
  }
}

Поле

Тип

Описание

referrals

array

Список приглашённых, от новых к старым

referrals[].referral_id

int

Telegram ID приглашённого пользователя

referrals[].date

string

Дата и время перехода по реферальной ссылке (UTC)

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

5. Баланс вознаграждений

GET /v1/referral/balance

Показывает, сколько денег (или другой валюты вознаграждения) накопил пользователь за привлечённых им людей, в разбивке по статусам.

Параметры

Параметр

Тип

Обязательный

Описание

user_id

int

да

Telegram ID реферера

Пример вызова

GET /v1/referral/balance?user_id=123456789

Ответ

{
  "ok": true,
  "data": {
    "balance": [
      {
        "unit_id": 1,
        "available": 150.5,
        "reserved": 20,
        "paid": 300,
        "on_hold": 10
      }
    ]
  }
}

Поле

Тип

Описание

balance

array

Одна строка на каждую валюту (unit_id), в которой у пользователя есть какие-либо начисления

balance[].unit_id

int

Идентификатор валюты/единицы вознаграждения

balance[].available

number

Доступно к выводу прямо сейчас

balance[].reserved

number

Зарезервировано — уже включено в созданную, но ещё не обработанную выплату

balance[].paid

number

Уже выплачено пользователю ранее

balance[].on_hold

number

На удержании — начислено, но ещё не подтверждено к выплате (например, ожидает проверки)

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

6. Запросить выплату

POST /v1/referral/payout

Запускает выплату всего доступного (available) баланса пользователя. Метод только создаёт заявку на выплату — сама выплата (например, отправка вебхука с уведомлением о начислении) выполняется системой отдельно, по расписанию.

Важно: метод не проверяет минимальный порог для вывода и не спрашивает разрешения — если вы его вызвали, заявка создаётся сразу на всю доступную сумму. Решение, когда вызывать этот метод (например, только если у пользователя накопилось от 100 ₸), остаётся на стороне вашего бота.

Параметры

Параметр

Тип

Обязательный

По умолчанию

Описание

user_id

int

да

—

Telegram ID реферера

unit_id

int

нет

не задано

Валюта, по которой нужно вывести средства. Если не передать — выводится весь доступный баланс по любой валюте, где он есть

method

string

нет

webhook

Способ исполнения выплаты: webhook — система сама отправит уведомление о выплате на ваш вебхук; manual — выплата будет отмечена как требующая ручной обработки администратором

Пример вызова

POST /v1/referral/payout

{ "user_id": 123456789, "unit_id": 1, "method": "webhook" }

Ответ

{
  "ok": true,
  "data": { "payout_id": 4821 }
}

Поле

Тип

Описание

payout_id

int

Идентификатор созданной заявки на выплату. Используйте его, чтобы найти эту выплату в GET /v1/referral/payouts

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

400

У пользователя нет доступного баланса для вывода (no available balance)

Перед вызовом проверяйте баланс через GET /v1/referral/balance — выводить нечего, если available равен нулю

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

7. История выплат

GET /v1/referral/payouts

Возвращает список всех заявок на выплату пользователя — как уже обработанных, так и ещё в процессе.

Параметры

Параметр

Тип

Обязательный

По умолчанию

Описание

user_id

int

да

—

Telegram ID реферера

limit

int

нет

Сколько записей вернуть за раз (от 1 до 200)

offset

int

нет

Сколько записей пропустить с начала списка

Пример вызова

GET /v1/referral/payouts?user_id=123456789&limit=20&offset=0&api-key=YOUR_API_KEY

Ответ

{
  "ok": true,
  "data": {
    "payouts": [
      {
        "payout_id": 4821,
        "amount": 150.5,
        "unit_id": 1,
        "status": 2,
        "method": "webhook",
        "initiated_by": "api",
        "requested_at": "2026-06-18 10:00:00",
        "processed_at": "2026-06-18 10:05:32"
      }
    ]
  }
}

Поле

Тип

Описание

payouts

array

Список заявок на выплату, от новых к старым

payouts[].payout_id

int

Идентификатор заявки

payouts[].amount

number

Сумма выплаты

payouts[].unit_id

int

Валюта/единица выплаты

payouts[].status

int

Числовой статус заявки (этап обработки внутри системы)

payouts[].method

string

Способ исполнения: webhook или manual

payouts[].initiated_by

string

Кто инициировал заявку: api (через этот метод), admin (вручную в админ-панели) или auto (автоматически системой)

payouts[].requested_at

string

Дата и время создания заявки (UTC)

payouts[].processed_at

string|null

Дата и время фактической обработки заявки. null, если ещё не обработана

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

8. Аннулировать начисление

POST /v1/referral/reverse-accrual

Отменяет одно конкретное начисление вознаграждения по его идентификатору (accrual_id). Используется, если начисление было сделано по ошибке (например, отменённый/возвращённый платёж приглашённого пользователя).

Поведение зависит от текущего состояния начисления:

если начисление ещё не выплачено — оно просто помечается как отменённое, и сумма исчезает из баланса пользователя;
если начисление уже выплачено — создаётся компенсирующая запись (как бы «минус» на ту же сумму), а само начисление помечается как аннулированное.

Параметры (тело запроса)

Параметр

Тип

Обязательный

Описание

accrual_id

int

да

Идентификатор начисления, которое нужно аннулировать

reason

string

нет

Причина аннулирования — сохраняется для истории, ни на что не влияет

Пример вызова

{ "accrual_id": 99812, "reason": "Платёж пользователя был возвращён" }

Ответ

{
  "ok": true,
  "data": {}
}

Метод не возвращает дополнительных данных — успешный ответ (ok: true) означает, что начисление аннулировано.

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан accrual_id

Передайте корректный идентификатор начисления

404

Начисление с таким accrual_id не найдено (или принадлежит другому боту)

Проверьте, что accrual_id верный и относится к вашему боту

409

Начисление уже находится в состоянии, не допускающем аннулирование (например, уже отменено ранее)

Повторное аннулирование не требуется — начисление уже неактивно

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

9. Пометить пользователя как реферала (mark-referral)

POST /v1/referral/mark-referral

Напрямую помечает пользователя как реферала — без перехода по реферальной ссылке. Используйте, если вы сами знаете (из своих данных), что пользователь пришёл от конкретного реферера, и хотите просто сообщить об этом системе.

Укажите реферера одним из двух способов:

code — уже существующий реферальный код (выданный через create-code или сообщённый через set-code-owners);
referrer_user_id — Telegram ID реферера напрямую. Если у него ещё нет своего кода, он будет создан автоматически.

Передавать оба параметра одновременно нельзя.

Метод идемпотентен: если у пользователя уже есть привязанный реферер (в том числе по более раннему переходу по ссылке), повторный вызов ничего не меняет — в ответе вернётся уже существующий реферер.

Параметры (тело запроса)

Параметр

Тип

Обязательный

Описание

referral_user_id

int

да

Telegram ID пользователя, которого нужно пометить рефералом

code

string

один из двух (code или referrer_user_id)

Существующий реферальный код реферера

referrer_user_id

int

один из двух (code или referrer_user_id)

Telegram ID реферера

Пример вызова

{ "referral_user_id": 555111222, "referrer_user_id": 123456789 }

Ответ

{
  "ok": true,
  "data": {
    "referral_id": 555111222,
    "referrer_id": 123456789,
    "code": "kT7xQm2p",
    "already_attributed": false
  }
}

Поле

Тип

Описание

referral_id

int

Telegram ID помеченного реферала (тот же referral_user_id)

referrer_id

int|null

Telegram ID реферера. null возможен только при привязке по code, если у этого кода ещё нет известного владельца

code

string|null

Код, через который оформлена привязка. null, если привязка делалась по referrer_user_id и у реферера уже был свой код (использован он, но его строка не возвращается)

already_attributed

bool

true — у пользователя уже был реферер (текущий запрос ничего не изменил, вернули то, что уже есть). false — привязка создана этим вызовом

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан referral_user_id, либо переданы и code, и referrer_user_id одновременно, либо не передан ни один из них

Передайте referral_user_id и ровно один из code/referrer_user_id

400

Пользователь пытается стать рефералом самого себя

Проверьте, что referral_user_id и реферер — разные пользователи

404

Указанный code не найден

Проверьте код, либо используйте referrer_user_id

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

10. Список начислений

GET /v1/referral/accruals

Возвращает доходную часть истории баланса пользователя — список отдельных начислений вознаграждения (по каждому приведённому пользователю и событию отдельная строка). Списания (выплаты) возвращает GET /v1/referral/payouts — вместе эти два метода дают полную ленту движений по балансу.

Аннулированные и отменённые начисления (см. reverse-accrual) в список не попадают — это леджер «живого» баланса, а не полный аудит.

Параметры

Параметр

Тип

Обязательный

По умолчанию

Описание

user_id

int

да

—

Telegram ID реферера

limit

int

нет

Сколько записей вернуть за раз (от 1 до 200)

offset

int

нет

Сколько записей пропустить с начала списка

Пример вызова

GET /v1/referral/accruals?user_id=123456789&limit=20&offset=0

Ответ

{
  "ok": true,
  "data": {
    "accruals": [
      {
        "id": 99812,
        "date": "2026-06-15 09:13:01",
        "referral_id": 555111222,
        "amount": 30.10,
        "unit_id": 1,
        "status": 1,
        "available_at": "2026-07-15 09:13:01"
      }
    ]
  }
}

Поле

Тип

Описание

accruals

array

Список начислений, от новых к старым

accruals[].id

int

Идентификатор начисления (используется как accrual_id в reverse-accrual)

accruals[].date

string

Дата и время создания начисления (UTC)

accruals[].referral_id

int

Telegram ID приглашённого пользователя, за чьё действие начислено вознаграждение

accruals[].amount

number

Сумма начисления (может быть отрицательной — компенсирующая запись после аннулирования)

accruals[].unit_id

int|null

Валюта/единица вознаграждения

accruals[].status

int

0 — на выдержке, 1 — подтверждено (доступно к выводу), 2 — выплачено

accruals[].available_at

string|null

Когда начисление станет доступно к выводу (выдержка). null, если выдержка не применяется или уже прошла

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

11. Действующая ставка вознаграждения

GET /v1/referral/rates

Показывает, на каких условиях пользователь получает вознаграждение за приглашённых — по каждому активному правилу программы отдельно (если у бота несколько правил, например за оплату и за подписку). Полезно, чтобы показать пользователю «вы получаете 10% с каждой оплаты» в своём интерфейсе.

Если для пользователя ранее уже было хотя бы одно начисление по правилу — отдаётся его зафиксированная ставка (locked: true), даже если с тех пор общая ставка программы изменилась. Если начислений ещё не было — отдаётся текущая ставка правила (locked: false); она будет зафиксирована за пользователем автоматически при первом подходящем начислении.

Параметры

Параметр

Тип

Обязательный

Описание

user_id

int

да

Telegram ID реферера

Пример вызова

GET /v1/referral/rates?user_id=123456789

Ответ

{
  "ok": true,
  "data": {
    "rates": [
      {
        "rule_id": 7,
        "rule_name": "Процент с оплат",
        "trigger_event_id": 12,
        "reward_type": "percent",
        "reward_amount": null,
        "reward_percent": "10.0000",
        "unit_id": 1,
        "locked": true,
        "source": "auto"
      }
    ]
  }
}

Поле

Тип

Описание

rates

array

Одна строка на каждое активное правило программы у бота

rates[].rule_id

int

Идентификатор правила

rates[].rule_name

string|null

Название правила (как задано в админке)

rates[].trigger_event_id

int

Тип события, за которое начисляется вознаграждение по этому правилу

rates[].reward_type

string

fixed — фиксированная сумма, percent — процент от суммы события, external — вознаграждение выдаётся на вашей стороне

rates[].reward_amount

number|null

Сумма вознаграждения для fixed

rates[].reward_percent

number|null

Процент вознаграждения для percent

rates[].unit_id

int|null

Валюта/единица вознаграждения

rates[].locked

bool

true — ставка зафиксирована конкретно за этим пользователем (не изменится при правке общей ставки программы); false — действует общая текущая ставка программы

rates[].source

string|null

auto — зафиксирована автоматически при первом начислении; manual — индивидуально задана администратором; null, если locked равно false

Возможные ошибки

Код

Когда возникает

Как исправить

400

Не передан user_id, или он не является числом

Передайте корректный Telegram ID

401

API-ключ не передан или недействителен

Проверьте API-ключ

500

Внутренняя ошибка сервера

Повторите запрос позже

Общий формат ошибок

Если запрос завершился неуспешно, в ответе всегда будет "ok": false:

{
  "ok": false,
  "error": "user_id is required",
  "error_code": 400
}

Поле

Описание

ok

Всегда false при ошибке

error

Текстовое описание причины ошибки

error_code

HTTP-код ошибки (совпадает с кодом HTTP-ответа)

ПредыдущаяПодключение кастомного чат-бота

СледующаяРассылки

Последнее обновление 3 месяца назад