Сначала определим правила начисления
Реферальная ссылка отвечает на вопрос «кто пригласил», но сама по себе не подтверждает покупку. Разделите три факта: первое знакомство пользователя с ботом, привязка к пригласившему и выполнение условия награды. Тогда повторный /start или повтор события оплаты не превращается в новые баллы.
Привязка возможна только при первом личном сообщении нового пользователя. Существующим клиентам поздняя ссылка не меняет пригласившего.
Для одного приглашённого в программе first-purchase-v1 предусмотрена одна награда. Условие — оплаченная покупка от 1000 рублей после привязки.
При полном возврате заказа награда отменяется отдельной отрицательной операцией. Повторная покупка после отмены не даёт новую награду в этой версии программы.
Баллы в примере — внутренний учёт. Списание на покупки и вывод денег здесь не реализованы.
Опубликуйте эти правила рядом со ссылкой. Если бизнес хочет окно атрибуции, период ожидания после покупки или бонус за несколько заказов, сначала измените правило и ключ уникальности. Нельзя просто убрать UNIQUE ради нового сценария: это одновременно откроет повторные начисления.
Если у вас уже есть пользователи, перенесите их ID в members до включения программы. Иначе приложение посчитает первого после запуска программы посетителя новым, хотя он давно покупает в магазине. Для существующей CRM признак «новый клиент» лучше брать из её проверенного реестра.
Создадим таблицы и подключение
Пример рассчитан на один бот и одну базу SQLite на локальном диске сервера, PHP 8.3+ с расширениями PDO SQLite и cURL. Публичный корень сайта — только папка public/; остальные PHP-файлы, база и Composer-зависимости находятся уровнем выше. Для нескольких ботов добавьте идентификатор бота во все ключи уникальности. Не размещайте SQLite на общей сетевой папке нескольких серверов.
BOT_TOKEN=TOKEN_FROM_BOTFATHER BOT_DB_PATH=/srv/referrals/private/bot.sqlite WEBHOOK_SECRET=RANDOM_SECRET_FROM_PASSWORD_MANAGER WEBHOOK_URL=https://example.com/webhook.php BOT_USERNAME=YourShopBot
Это настоящие переменные окружения процесса: настройте их и для PHP-FPM, и для CLI. Обычный PHP не читает .env автоматически. Создайте закрытую папку private/, дайте пользователю приложения право записи в неё и запретите доступ из веба. Токен и секрет webhook не должны попадать в браузер, репозиторий или логи. В примерах ниже все команды выполняются из корня отдельного учебного приложения.
Понадобятся таблицы участников, неизменяемых привязок, заказов, наград и операций по балансу. Суммы заказов храним целыми копейками: 100000 — это 1000 рублей. Таблица rewards фиксирует основание, reward_log — движение баллов. Отмена не стирает первоначальную запись.
CREATE TABLE members (
user_id INTEGER PRIMARY KEY, code TEXT NOT NULL UNIQUE, joined_at INTEGER NOT NULL
);
CREATE TABLE referrals (
invitee INTEGER PRIMARY KEY REFERENCES members(user_id),
inviter INTEGER NOT NULL REFERENCES members(user_id),
bound_at INTEGER NOT NULL, CHECK(invitee <> inviter)
);
CREATE TABLE orders (
id TEXT PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES members(user_id),
amount INTEGER NOT NULL CHECK(amount > 0), paid_at INTEGER NOT NULL,
status TEXT NOT NULL CHECK(status IN ('paid','refunded'))
);
CREATE TABLE rewards (
id INTEGER PRIMARY KEY, program TEXT NOT NULL,
invitee INTEGER NOT NULL, inviter INTEGER NOT NULL,
order_id TEXT NOT NULL REFERENCES orders(id), points INTEGER NOT NULL,
created_at INTEGER NOT NULL, reversed_at INTEGER,
UNIQUE(program, invitee)
);
CREATE TABLE reward_log (
id INTEGER PRIMARY KEY, reward_id INTEGER NOT NULL REFERENCES rewards(id),
user_id INTEGER NOT NULL, delta INTEGER NOT NULL,
action TEXT NOT NULL CHECK(action IN ('award','reverse')), created_at INTEGER NOT NULL,
UNIQUE(reward_id, action)
);
CREATE TABLE updates (id INTEGER PRIMARY KEY);
<?php
declare(strict_types=1);
function setting(string $name): string
{
$value = getenv($name);
if ($value === false || $value === '') {
throw new RuntimeException('Missing setting: '.$name);
}
return $value;
}
function database(): PDO
{
$path = setting('BOT_DB_PATH');
if (!is_file($path)) {
throw new RuntimeException('Run init.php first');
}
$db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA foreign_keys=ON');
$db->exec('PRAGMA busy_timeout=3000');
return $db;
}
/** @param list<int|string|null> $values */
function sql(PDO $db, string $query, array $values = []): PDOStatement
{
$statement = $db->prepare($query);
$statement->execute($values);
return $statement;
}
/** @return array<string, int|string|null>|null */
function row(PDOStatement $statement): ?array
{
$result = $statement->fetch(PDO::FETCH_ASSOC);
if ($result === false) {
return null;
}
if (!is_array($result)) {
throw new RuntimeException('Invalid database row');
}
foreach ($result as $key => $value) {
if (!is_string($key) || !(is_int($value) || is_string($value) || $value === null)) {
throw new RuntimeException('Invalid database field');
}
}
return $result;
}
/**
* @template T
* @param callable(): T $action
* @return T
*/
function atomic(PDO $db, callable $action): mixed
{
$db->exec('BEGIN IMMEDIATE');
try {
$result = $action();
$db->exec('COMMIT');
return $result;
} catch (Throwable $e) {
$db->exec('ROLLBACK');
throw $e;
}
}
/** @return array<string, mixed> */
function jsonBody(): array
{
$raw = file_get_contents('php://input', length: 65537);
if ($raw === false || strlen($raw) > 65536) {
throw new InvalidArgumentException('Request too large');
}
$data = json_decode($raw, true, 32, JSON_THROW_ON_ERROR);
if (!is_array($data) || array_is_list($data)) {
throw new InvalidArgumentException('Expected JSON object');
}
$result = [];
foreach ($data as $key => $value) {
if (!is_string($key)) {
throw new InvalidArgumentException('Invalid JSON key');
}
$result[$key] = $value;
}
return $result;
}
/** @param array<string, mixed> $data */
function reply(array $data, int $status = 200): never
{
http_response_code($status);
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
echo json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE);
exit;
}
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
if (PHP_SAPI !== 'cli') {
exit(1);
}
$path = setting('BOT_DB_PATH');
if (file_exists($path)) {
throw new RuntimeException('Database already exists');
}
$schema = file_get_contents(__DIR__.'/schema.sql');
if ($schema === false) {
throw new RuntimeException('Missing schema.sql');
}
$db = new PDO('sqlite:'.$path, options: [PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION]);
$db->exec('PRAGMA foreign_keys=ON');
$db->exec($schema);
echo "Database created\n";
php init.php
Создадим код приглашения и неизменяемую привязку
Персональный код — 24 шестнадцатеричных символа. Получится ссылка вида https://t.me/YourShopBot?start=ref_...: это обычный start, не startapp. Код укладывается в ограничение Telegram и не раскрывает последовательный внутренний ID клиента. Бот обрабатывает команду после действия пользователя в Telegram; посещение ссылки в браузере не является регистрацией.
<?php
declare(strict_types=1);
function joinProgram(PDO $db, int $user, ?string $inviteCode, int $now): string
{
return atomic($db, function () use ($db, $user, $inviteCode, $now): string {
$member = row(sql($db, 'SELECT code FROM members WHERE user_id=?', [$user]));
if ($member !== null) {
return (string) $member['code'];
}
// Resolve before insertion: a new member cannot invite themselves.
$inviter = $inviteCode === null ? null : row(sql($db,
'SELECT user_id FROM members WHERE code=?', [$inviteCode]));
$code = bin2hex(random_bytes(12));
sql($db, 'INSERT INTO members(user_id,code,joined_at) VALUES(?,?,?)', [$user, $code, $now]);
if ($inviter !== null && (int) $inviter['user_id'] !== $user) {
sql($db, 'INSERT INTO referrals(invitee,inviter,bound_at) VALUES(?,?,?)',
[$user, (int) $inviter['user_id'], $now]);
}
return $code;
});
}
function awardOrder(PDO $db, string $orderId, int $now): bool
{
return atomic($db, function () use ($db, $orderId, $now): bool {
$order = row(sql($db, 'SELECT o.*,r.inviter,r.bound_at FROM orders o
JOIN referrals r ON r.invitee=o.user_id WHERE o.id=?', [$orderId]));
if ($order === null || $order['status'] !== 'paid' || (int) $order['amount'] < 100000
|| (int) $order['paid_at'] < (int) $order['bound_at']) {
return false;
}
$inserted = sql($db, 'INSERT INTO rewards(program,invitee,inviter,order_id,points,created_at)
VALUES(?,?,?,?,100,?) ON CONFLICT(program,invitee) DO NOTHING',
['first-purchase-v1', (int) $order['user_id'], (int) $order['inviter'], $orderId, $now])->rowCount();
if ($inserted === 0) {
return false;
}
$reward = (int) $db->lastInsertId();
sql($db, 'INSERT INTO reward_log(reward_id,user_id,delta,action,created_at) VALUES(?,?,100,?,?)',
[$reward, (int) $order['inviter'], 'award', $now]);
return true;
});
}
function refundOrder(PDO $db, string $orderId, int $now): void
{
atomic($db, function () use ($db, $orderId, $now): void {
sql($db, "UPDATE orders SET status='refunded' WHERE id=?", [$orderId]);
$reward = row(sql($db, 'SELECT * FROM rewards WHERE order_id=? AND reversed_at IS NULL', [$orderId]));
if ($reward === null) {
return;
}
sql($db, 'INSERT INTO reward_log(reward_id,user_id,delta,action,created_at) VALUES(?,?,?,?,?)',
[(int) $reward['id'], (int) $reward['inviter'], -(int) $reward['points'], 'reverse', $now]);
sql($db, 'UPDATE rewards SET reversed_at=? WHERE id=?', [$now, (int) $reward['id']]);
});
}
function rewardHistory(PDO $db, int $user): string
{
$sum = row(sql($db, 'SELECT COALESCE(SUM(delta),0) AS total FROM reward_log WHERE user_id=?', [$user]));
$text = 'Баланс: '.(int) ($sum['total'] ?? 0)." баллов\nПоследние операции:\n";
$statement = sql($db, 'SELECT delta,action,created_at FROM reward_log WHERE user_id=? ORDER BY id DESC LIMIT 10', [$user]);
while (($entry = row($statement)) !== null) {
$text .= gmdate('Y-m-d H:i', (int) $entry['created_at']).' UTC: '
.($entry['action'] === 'award' ? 'начисление' : 'отмена').' '.(int) $entry['delta']."\n";
}
return $text;
}
Функция joinProgram сначала смотрит существующего участника. Если запись есть, она возвращает его код и не меняет связи. Для нового участника пригласивший ищется до вставки: собственный ещё не созданный код невозможно использовать. Дополнительные проверки invitee ≠ inviter стоят и в коде, и в базе.
Параллельные первые сообщения сериализуются транзакцией. Побеждает первый зафиксированный вход, а не тот, который пользователь считает последним. Это выбранная модель атрибуции; расскажите о ней поддержке, чтобы оператор не обещал сменить пригласившего задним числом. Переходы по другим ссылкам можно хранить как аналитику отдельно от награды.
Подключим команды бота
<?php
declare(strict_types=1);
/**
* @param array<string, mixed> $params
* @return array{state: string, result?: mixed, code?: int, retry_after?: int}
*/
function telegram(string $method, array $params, bool $multipart = false): array
{
$curl = curl_init('https://api.telegram.org/bot'.setting('BOT_TOKEN').'/'.$method);
curl_setopt_array($curl, [
CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 3, CURLOPT_TIMEOUT => 8,
CURLOPT_POSTFIELDS => $multipart ? $params : json_encode($params, JSON_THROW_ON_ERROR),
CURLOPT_HTTPHEADER => $multipart ? [] : ['Content-Type: application/json'],
]);
$raw = curl_exec($curl);
$status = (int) curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
if (!is_string($raw) || $status >= 500) {
return ['state' => 'unknown'];
}
$data = json_decode($raw, true);
if (!is_array($data)) {
return ['state' => 'unknown'];
}
if (($data['ok'] ?? null) === true) {
return ['state' => 'ok', 'result' => $data['result'] ?? null];
}
if (($data['ok'] ?? null) !== false || !is_int($data['error_code'] ?? null)) {
return ['state' => 'unknown'];
}
$parameters = $data['parameters'] ?? null;
$delay = is_array($parameters) ? ($parameters['retry_after'] ?? null) : null;
return ['state' => 'rejected', 'code' => $data['error_code'],
'retry_after' => is_int($delay) && $delay > 0 ? $delay : 60];
}
/** @return array<string, mixed> */
function incomingUpdate(): array
{
$secret = $_SERVER['HTTP_X_TELEGRAM_BOT_API_SECRET_TOKEN'] ?? '';
if (($_SERVER['REQUEST_METHOD'] ?? '') !== 'POST' || !is_string($secret)
|| !hash_equals(setting('WEBHOOK_SECRET'), $secret)) {
reply(['error' => 'Forbidden'], 403);
}
return jsonBody();
}
<?php
declare(strict_types=1);
require dirname(__DIR__).'/common.php';
require dirname(__DIR__).'/telegram.php';
require dirname(__DIR__).'/referrals.php';
$update = incomingUpdate();
$message = $update['message'] ?? null;
$chat = is_array($message) ? ($message['chat'] ?? null) : null;
$from = is_array($message) ? ($message['from'] ?? null) : null;
if (!is_int($update['update_id'] ?? null) || !is_array($message) || !is_array($chat)
|| !is_array($from) || ($chat['type'] ?? '') !== 'private'
|| !is_int($from['id'] ?? null) || ($chat['id'] ?? null) !== $from['id']) {
reply(['ok' => true]);
}
$user = $from['id'];
$text = is_string($message['text'] ?? null) ? $message['text'] : '';
$inviteCode = preg_match('/^\/start(?:@[a-zA-Z0-9_]+)? ref_([a-f0-9]{24})$/D', $text, $match) ? $match[1] : null;
$db = database();
// Every first private message fixes whether this user arrived by referral.
$code = joinProgram($db, $user, $inviteCode, time());
$answer = $text === '/balance' ? rewardHistory($db, $user) :
'Ваша ссылка: https://t.me/'.setting('BOT_USERNAME').'?start=ref_'.$code
."\n100 баллов за нового клиента после оплаченной покупки от 1000 рублей. Баланс: /balance";
if (sql($db, 'INSERT OR IGNORE INTO updates(id) VALUES(?)', [$update['update_id']])->rowCount() === 1) {
$result = telegram('sendMessage', ['chat_id' => $user, 'text' => $answer]);
if ($result['state'] !== 'ok') {
error_log('referral_reply_'.$result['state'].' update='.$update['update_id']);
}
}
reply(['ok' => true]);
Обработчик принимает только личные сообщения и берёт ID из from.id, проверяя соответствие личному чату. Любое первое сообщение создаёт участника, поэтому нельзя сначала пользоваться ботом, а потом получить статус приглашённого через /start. /balance показывает только историю текущего пользователя — ID получателя из текста команды не принимается.
Повтор update_id не меняет привязку и не отправляет ещё один автоматический ответ. Отправка находится после записи фактов в базу. Если ответ потерян, пользователь может запросить /balance или снова написать боту; финансовая часть от ответа Telegram не зависит.
Зарегистрируйте прямой webhook Telegram следующим CLI-скриптом. Здесь принимаются только обновления message; если у бота уже есть обработчики других событий, сохраните их в общем обработчике и в allowed_updates, вместо установки второго webhook. Один бот не использует одновременно этот webhook и getUpdates.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/telegram.php';
if (PHP_SAPI !== 'cli') {
exit(1);
}
$url = setting('WEBHOOK_URL');
if (!str_starts_with($url, 'https://')) {
throw new RuntimeException('HTTPS webhook required');
}
$result = telegram('setWebhook', [
'url' => $url, 'secret_token' => setting('WEBHOOK_SECRET'),
'allowed_updates' => ['message'],
]);
if ($result['state'] !== 'ok') {
throw new RuntimeException('Webhook not confirmed');
}
echo "Webhook configured\n";
php setup-webhook.php
Начислим бонус после подтверждённого действия
awardOrder читает существующий заказ из серверной таблицы. Здесь нет HTTP-маршрута «начислить мне бонус» и нет доверия к сумме из браузера. Ваш обработчик подтверждённой оплаты сначала сохраняет orders с проверенным владельцем, суммой и paid_at, затем после commit вызывает awardOrder. Связь владельца заказа с Telegram должна уже быть проверена, например по привязке аккаунта сайта.
<?php declare(strict_types=1); // common.php и referrals.php уже подключены приложением. // $orderId получен из проверенного платёжного события и найден в вашей БД. // Это точка интеграции, а не публичный обработчик произвольного POST. awardOrder($db, $orderId, time());
Уникальность (program, invitee) защищает от двух разных событий и даже от двух разных подходящих заказов одного приглашённого. Добавление награды и строки +100 происходит одной транзакцией: нет окна, где право на награду занято, а баланс ещё не увеличен. Telegram update_id для этого недостаточен — оплаты могут приходить из другого источника.
Встроенный пример orders — минимальная модель магазина. Он не заменяет проверку подписи платёжного провайдера и сверку суммы с ценой на сервере. Для Stars точка вызова находится после successful_payment, как показано в статье об оплате цифрового доступа. Не начисляйте бонус по экрану «Оплачено» в Mini App.
Восстановим пропущенное начисление
Между сохранением оплаты и вызовом функции процесс может остановиться. Поэтому нужен способ найти оплаченные заказы без награды. Следующий CLI-скрипт обходит подходящие записи небольшими партиями; его можно запускать раз в минуту. Несколько запусков не умножают баллы благодаря тому же ограничению в БД.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/referrals.php';
if (PHP_SAPI !== 'cli') {
exit(1);
}
$db = database();
// Work in bounded batches. Terminal/ineligible orders are excluded from selection.
$statement = sql($db, "SELECT o.id FROM orders o JOIN referrals r ON r.invitee=o.user_id
WHERE o.status='paid' AND o.amount>=100000 AND o.paid_at>=r.bound_at
AND NOT EXISTS (SELECT 1 FROM rewards w WHERE w.program='first-purchase-v1' AND w.invitee=o.user_id)
ORDER BY o.paid_at,o.id LIMIT 100");
$ids = [];
while (($order = row($statement)) !== null) {
$ids[] = (string) $order['id'];
}
$statement->closeCursor();
foreach ($ids as $id) {
awardOrder($db, $id, time());
}
echo "Reconciled\n";
php reconcile.php
Ответ Reconciled означает завершение партии, а не наличие начисления для каждого заказа. Посмотрите rewards и reward_log: заказы ниже порога, до привязки, без пригласившего и уже награждённые должны оставаться без новой записи. При большом объёме добавьте индексы, курсор обхода и наблюдение за отставанием, сохраняя атомарное правило начисления.
Отменим награду и сохраним историю
refundOrder вызывается из доверенного обработчика подтверждённого полного возврата. Он меняет статус заказа и добавляет −100 в одной транзакции. Если возврат пришёл раньше попытки начисления, awardOrder увидит refunded и ничего не выдаст. Если позже — баланс вернётся к прежнему значению. Повтор возврата не добавит вторую отрицательную операцию.
В примере начисленные баллы нельзя тратить, поэтому отрицательный остаток после возврата не возникает. При добавлении списаний нужно заранее определить поведение для уже потраченного бонуса: долг, лимит списания или резерв до окончания периода возврата. Частичный возврат также требует отдельного правила — механически вызывать полный откат для любого refund неверно.
Сумма reward_log — источник баланса. В истории пользователя не показываются Telegram ID приглашённых, состав их покупок и суммы заказов. Сотрудник может видеть связь с order_id в закрытом интерфейсе, но для поддержки полезнее номер операции, причина и время, чем выгрузка персональных данных.
Прогоним пример без реальных покупок
Для первой проверки используйте отдельную пустую базу. Следующий файл создаёт двух вымышленных участников, тестовый оплаченный заказ, дважды вызывает начисление и дважды — возврат. Он работает только в CLI при DEMO_MODE=1. Не оставляйте демонстрационные заказы в рабочей базе.
<?php
declare(strict_types=1);
require __DIR__.'/common.php';
require __DIR__.'/referrals.php';
if (PHP_SAPI !== 'cli' || getenv('DEMO_MODE') !== '1') {
exit(1);
}
$db = database();
$now = time();
$code = joinProgram($db, 1001, null, $now);
joinProgram($db, 1002, $code, $now);
sql($db, "INSERT INTO orders(id,user_id,amount,paid_at,status) VALUES('demo-order',1002,150000,?,'paid')
ON CONFLICT(id) DO NOTHING", [$now]);
awardOrder($db, 'demo-order', $now);
awardOrder($db, 'demo-order', $now);
echo rewardHistory($db, 1001);
refundOrder($db, 'demo-order', $now);
refundOrder($db, 'demo-order', $now);
echo rewardHistory($db, 1001);
DEMO_MODE=1 php demo.php
В первом выводе баланс должен быть 100 и одна операция начисления, во втором — 0 и ровно две операции: +100 и −100. Повтор demo.php не даст новую награду, поскольку тот же заказ уже возвращён. Для повторения исходного сценария создайте новую тестовую базу, а не очищайте рабочую.
Существующий пользователь открывает собственную ссылку: referrals не пополняется.
Новый пользователь приходит по коду A, затем по коду B: пригласивший остаётся A.
Два обработчика одновременно вызывают awardOrder для одного заказа: появляется одна награда и одна строка +100.
Два разных заказа одного приглашённого проходят обработку: в этой программе награда всё равно одна.
Сбой сразу после сохранения orders исправляется запуском reconcile.php.
Заказ со статусом refunded и заказ меньше 100000 копеек не увеличивают баланс.
Telegram ID обозначает аккаунт, а не уникального человека. Запрет самоприглашения одного ID не остановит владельца нескольких аккаунтов. Для ценных вознаграждений полезны проверяемое полезное действие, ограничения программы и ручная проверка подозрительных серий; не обещайте абсолютную защиту от накрутки одной проверкой /start.
Где здесь помогает BotGate
Связи пользователей и журнал баллов остаются в вашей БД; BotGate может использоваться для обмена сообщениями с Telegram. Если после начисления добавите уведомление, сбой отправки не должен отменять уже зафиксированный бонус или приводить к повторному начислению. Разделяйте награду и её доставку по руководству о дублях.
Первичные источники: deep linking Telegram, транзакции SQLite. Для источников без бонусной программы есть отдельная статья про start-параметры; для подключения транспорта — документация BotGate.