Перейти к содержанию
24 минут чтения
Тема: Практика Mini Apps · Интернет-магазин · Заказы

Как сделать корзину и оформление заказа в Telegram Mini App

Для примера возьмём магазин чая с самовывозом. Покупатель добавляет товары, закрывает Mini App и позже возвращается к корзине. При оформлении сервер проверяет цену и наличие. Если связь пропадёт после сохранения, повторный запрос вернёт номер уже созданного заказа.

Храним корзину на сервере

После запуска отправьте исходную строку Telegram.WebApp.initData на свой сервер, проверьте её подпись и срок действия, затем создайте сессию. Сервер находит корзину по владельцу из сессии. Если у магазина уже есть аккаунты, используйте подтверждённую привязку Telegram ID к аккаунту. Пример есть в руководстве по авторизации Mini App.

  • В carts храните ID корзины, владельца и номер ревизии. Сервер должен однозначно выбирать активную корзину владельца.

  • В cart_items храните ID корзины, ID товарного варианта и количество. Ограничение UNIQUE(cart_id, variant_id) оставляет одну строку для каждого варианта.

  • В orders храните владельца, ID и ревизию исходной корзины, итог и статус. В order_items сохраните снимок названия, цены и количества, чтобы изменения каталога не переписывали старый заказ.

При открытии приложения загрузите корзину с сервера. Браузер может показать ранее загруженный список, пока идёт запрос. Возможность оформить заказ определяет сервер. Добавление товара само по себе не резервирует остаток.

Добавляем товар и меняем количество

Карточка товара отправляет ID варианта и итоговое количество. Кнопки «+» и «−» меняют это число, а «Удалить» устанавливает ноль. Например, если в корзине две пачки, «+» отправляет три. Повтор той же команды не прибавит четвёртую.

HTTP · количество товара
PUT /api/carts/c42/items/tea-250
Content-Type: application/json

{ "quantity": 3, "revision": 7 }

Проверьте владельца корзины и допустимый диапазон целого количества. Для ненулевого количества проверьте доступность варианта для продажи. В транзакции заблокируйте строку корзины и сравните ревизию из запроса с текущей. Если ревизии совпадают, обновите позицию и увеличьте номер ревизии при фактическом изменении. Верните корзину с пересчитанной суммой.

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

Показываем сумму перед оформлением

Перед оформлением запросите у сервера расчёт для текущей ревизии. Покажите позиции, цену за единицу, сумму и способ получения. Денежные значения в этом примере хранятся целыми числами в копейках.

Корзина с одной пачкой зелёного чая за 450 ₽; после изменения цены заказ не создан, новый итог 480 ₽ требует подтверждения.
Корзина с одной пачкой зелёного чая за 450 ₽; после изменения цены заказ не создан, новый итог 480 ₽ требует подтверждения.
Пример интерфейса, а не результат готовой HTML-формы. Статья описывает серверную логику. Цена 480 ₽ — демонстрационное изменение.

Сохраните на сервере короткоживущий расчёт с ID, привязкой к корзине и ревизии и ценами по позициям. По нажатию «Оформить» клиент отправляет ID корзины, ревизию и ID расчёта. Если предусмотрены варианты доставки или промокод, включите их в расчёт и повышайте ревизию при их изменении. В примере способ получения фиксированный.

HTTP · оформление заказа
POST /api/carts/c42/checkout
Content-Type: application/json

{ "revision": 8, "quote_id": "q9f8a" }

Разместите страницу и API на одном HTTPS-origin. При входе через cookie-сессию включите CSRF-защиту изменяющих запросов. При повторе запроса сохраняйте те же ревизию и ID расчёта.

Проверяем цены и остатки в транзакции

Схема рассчитана на БД с блокировками строк, например MySQL с InnoDB. Все операции, меняющие корзину, начинают с блокировки её строки. Изменения цен и остатков записываются в те же товарные строки, которые блокирует оформление.

  1. Найдите принадлежащую пользователю корзину и заблокируйте её строку через SELECT … FOR UPDATE внутри транзакции.

  2. Сначала найдите заказ по паре (cart_id, cart_revision). Если заказ уже существует и ID расчёта совпадает, верните его. Для той же ревизии с другим ID расчёта верните конфликт. Сделайте это до проверки срока расчёта и актуальности ревизии.

  3. Проверьте, что корзина активна и непуста, ревизия актуальна, а расчёт относится к ней и ещё действует. Заблокируйте товарные варианты в одном порядке, например по ID. Сверьте доступный остаток с количеством в корзине и текущую цену каждой позиции с расчётом, который видел покупатель.

  4. Если товар закончился, снят с продажи или изменился в цене, завершите операцию без записи заказа и списания. Верните 409 с причиной. Клиент заново загружает корзину и расчёт, а покупатель подтверждает новую сумму.

  5. Если проверки прошли, уменьшите доступный остаток, создайте заказ со снимком позиций и очистите корзину, увеличив её ревизию. Зафиксируйте все изменения одной транзакцией. Уведомление отправляйте после фиксации, используя ID созданного заказа.

Ограничение UNIQUE(cart_id, cart_revision) закрепляет правило «одна ревизия — один заказ» в БД. Сохраняйте строку корзины и ссылку на неё, пока нужны повторы. Придерживайтесь общего порядка блокировок и предусмотрите ограниченный повтор всей транзакции при взаимной блокировке.

Такой заказ фиксирует покупку с самовывозом. Если добавите онлайн-оплату, храните её состояние отдельно и меняйте его после серверного подтверждения платёжного события.

Обрабатываем повторное нажатие и потерю связи

Пока идёт запрос, отключите кнопку «Оформить». Если ответ потерялся или сервер вернул временную ошибку, предложите повторить тот же запрос. Сервер может вернуть 201 при создании и 200 при повторе с тем же ID заказа. Если сессия истекла, сначала восстановите вход.

Если Mini App закрыли посреди запроса, покажите недавние заказы из серверного списка. Для перехода из сообщения с номером заказа используйте прямую ссылку с параметром startapp.

Собираем рабочее ядро корзины на Laravel

Для примера возьмём новый Laravel-проект с MySQL/InnoDB или PostgreSQL и одним магазином. Подключите вход по initData из руководства об авторизации: он сохраняет в сессии mini_user_id и mini_expires_at. Ниже одна активная корзина на Telegram ID, самовывоз и цены в копейках. Сохранение корзины, расчёт и оформление используют одну БД.

Создайте миграцию php artisan make:migration create_shop_tables. Следующий код — импорты и тело её метода up(). Имена таблиц рассчитаны на учебный проект: перед переносом в существующий магазин согласуйте их с его моделями. Товары не удаляются физически, а снимаются с продажи через active.

PHP · миграция таблиц магазина
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

Schema::create('variants', function (Blueprint $t) {
    $t->id(); $t->string('title'); $t->unsignedInteger('price_minor');
    $t->unsignedInteger('stock'); $t->boolean('active')->default(true);
});
Schema::create('carts', function (Blueprint $t) {
    $t->id(); $t->unsignedBigInteger('telegram_user_id')->unique();
    $t->unsignedInteger('revision')->default(1);
});
Schema::create('cart_items', function (Blueprint $t) {
    $t->foreignId('cart_id')->constrained('carts');
    $t->foreignId('variant_id')->constrained('variants');
    $t->unsignedInteger('quantity'); $t->primary(['cart_id', 'variant_id']);
});
Schema::create('cart_quotes', function (Blueprint $t) {
    $t->string('id', 32)->primary(); $t->foreignId('cart_id')->constrained('carts');
    $t->unsignedInteger('revision'); $t->json('items'); $t->unsignedBigInteger('expires_at');
});
Schema::create('orders', function (Blueprint $t) {
    $t->id(); $t->string('public_id', 24)->unique(); $t->unsignedBigInteger('telegram_user_id');
    $t->foreignId('cart_id')->constrained('carts'); $t->unsignedInteger('cart_revision');
    $t->string('quote_id', 32); $t->unsignedBigInteger('total_minor'); $t->string('status');
    $t->unique(['cart_id', 'cart_revision']);
});
Schema::create('order_items', function (Blueprint $t) {
    $t->foreignId('order_id')->constrained('orders');
    $t->foreignId('variant_id')->constrained('variants');
    $t->string('title'); $t->unsignedInteger('price_minor'); $t->unsignedInteger('quantity');
    $t->primary(['order_id', 'variant_id']);
});

После php artisan migrate добавьте через php artisan tinker тестовый товар: DB::table('variants')->insert(['title' => 'Зелёный чай', 'price_minor' => 45000, 'stock' => 2, 'active' => true]);. Запомните его ID. Сервис ниже возвращает состав корзины и проверяет заказ внутри транзакции. Даже если ошибка обнаружится на второй позиции, списание первой откатится.

PHP · app/Services/ShopCart.php
<?php
namespace App\Services;

use Illuminate\Support\Facades\DB;

final class ShopCart
{
    private function lockedCart(int $owner): object
    {
        DB::table('carts')->insertOrIgnore([
            'telegram_user_id' => $owner, 'revision' => 1,
        ]);
        return DB::table('carts')->where('telegram_user_id', $owner)
            ->lockForUpdate()->first();
    }

    private function lines(int $cartId): array
    {
        return DB::table('cart_items as i')->join('variants as v', 'v.id', '=', 'i.variant_id')
            ->where('i.cart_id', $cartId)->orderBy('v.id')
            ->get(['v.id', 'v.title', 'v.price_minor', 'i.quantity'])
            ->map(fn ($r) => [
                'variant_id' => (int) $r->id, 'title' => $r->title,
                'price_minor' => (int) $r->price_minor, 'quantity' => (int) $r->quantity,
            ])->all();
    }

    public function read(int $owner): array
    {
        return DB::transaction(function () use ($owner) {
            $cart = $this->lockedCart($owner);
            return ['revision' => (int) $cart->revision, 'items' => $this->lines($cart->id)];
        }, 3);
    }

    public function quantity(int $owner, int $variantId, int $quantity, int $revision): array
    {
        return DB::transaction(function () use ($owner, $variantId, $quantity, $revision) {
            $cart = $this->lockedCart($owner);
            abort_unless((int) $cart->revision === $revision, 409, 'Корзина изменилась');
            if ($quantity > 0) {
                $variant = DB::table('variants')->where('id', $variantId)->lockForUpdate()->first();
                abort_unless($variant && $variant->active, 409, 'Товар недоступен');
            }
            $query = DB::table('cart_items')->where('cart_id', $cart->id)->where('variant_id', $variantId);
            $old = (int) ($query->value('quantity') ?? 0);
            if ($old !== $quantity) {
                if ($quantity === 0) {
                    $query->delete();
                } else {
                    DB::table('cart_items')->updateOrInsert(
                        ['cart_id' => $cart->id, 'variant_id' => $variantId], ['quantity' => $quantity]
                    );
                }
                DB::table('carts')->where('id', $cart->id)->increment('revision');
            }
            return ['revision' => $revision + (int) ($old !== $quantity), 'items' => $this->lines($cart->id)];
        }, 3);
    }

    public function quote(int $owner, int $revision): array
    {
        return DB::transaction(function () use ($owner, $revision) {
            $cart = $this->lockedCart($owner);
            abort_unless((int) $cart->revision === $revision, 409, 'Корзина изменилась');
            $items = $this->lines($cart->id);
            abort_if($items === [], 409, 'Корзина пуста');
            $id = bin2hex(random_bytes(16));
            $total = array_sum(array_map(fn ($i) => $i['price_minor'] * $i['quantity'], $items));
            $expires = time() + 300;
            DB::table('cart_quotes')->insert([
                'id' => $id, 'cart_id' => $cart->id, 'revision' => $revision,
                'items' => json_encode($items, JSON_THROW_ON_ERROR), 'expires_at' => $expires,
            ]);
            return ['quote_id' => $id, 'revision' => $revision, 'items' => $items,
                'total_minor' => $total, 'expires_at' => $expires];
        }, 3);
    }

    public function checkout(int $owner, int $revision, string $quoteId): array
    {
        return DB::transaction(function () use ($owner, $revision, $quoteId) {
            $cart = $this->lockedCart($owner);
            $existing = DB::table('orders')->where('cart_id', $cart->id)
                ->where('cart_revision', $revision)->first();
            if ($existing) {
                abort_unless($existing->quote_id === $quoteId, 409, 'Другой расчёт');
                return ['public_id' => $existing->public_id, 'created' => false];
            }
            abort_unless((int) $cart->revision === $revision, 409, 'Корзина изменилась');
            $quote = DB::table('cart_quotes')->where('id', $quoteId)->where('cart_id', $cart->id)
                ->where('revision', $revision)->first();
            abort_unless($quote && (int) $quote->expires_at > time(), 409, 'Обновите расчёт');
            $items = json_decode($quote->items, true, 32, JSON_THROW_ON_ERROR);
            $current = DB::table('cart_items')->where('cart_id', $cart->id)
                ->orderBy('variant_id')->get();
            abort_unless(count($items) > 0 && count($items) === $current->count(), 409);
            $total = 0;
            foreach ($items as $index => $item) {
                $line = $current[$index];
                abort_unless((int) $line->variant_id === $item['variant_id']
                    && (int) $line->quantity === $item['quantity'], 409, 'Состав изменился');
                $variant = DB::table('variants')->where('id', $item['variant_id'])->lockForUpdate()->first();
                abort_unless($variant && $variant->active && (int) $variant->stock >= $item['quantity'],
                    409, 'Недостаточно товара');
                abort_unless((int) $variant->price_minor === $item['price_minor'], 409, 'Цена изменилась');
                DB::table('variants')->where('id', $variant->id)->decrement('stock', $item['quantity']);
                $total += $item['price_minor'] * $item['quantity'];
            }
            $publicId = bin2hex(random_bytes(12));
            $orderId = DB::table('orders')->insertGetId([
                'public_id' => $publicId, 'telegram_user_id' => $owner,
                'cart_id' => $cart->id, 'cart_revision' => $revision, 'quote_id' => $quoteId,
                'total_minor' => $total, 'status' => 'created',
            ]);
            foreach ($items as $item) {
                DB::table('order_items')->insert(['order_id' => $orderId] + $item);
            }
            DB::table('cart_items')->where('cart_id', $cart->id)->delete();
            DB::table('carts')->where('id', $cart->id)->increment('revision');
            return ['public_id' => $publicId, 'created' => true];
        }, 3);
    }
}

Добавьте маршруты в routes/web.php, где уже действуют сессии и CSRF-защита. В этом варианте URL начинается с /mini/cart, а корзина выбирается по сессии; передавать её ID из браузера не требуется. На 409 клиент заново вызывает GET и показывает актуальный состав. Операции изменения количества посылайте последовательно, с ревизией последнего ответа.

PHP · маршруты корзины в routes/web.php
use App\Services\ShopCart;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Route;

$cartOwner = static function (Request $request): int {
    abort_unless(is_int($request->session()->get('mini_user_id'))
        && (int) $request->session()->get('mini_expires_at', 0) > time(), 401);
    return $request->session()->get('mini_user_id');
};
Route::prefix('mini/cart')->middleware('throttle:60,1')->group(function () use ($cartOwner) {
    Route::get('/', fn (Request $r, ShopCart $cart) => response()->json(
        $cart->read($cartOwner($r))
    )->header('Cache-Control', 'private, no-store'));
    Route::put('/items/{variant}', function (Request $r, ShopCart $cart, string $variant) use ($cartOwner) {
        $owner = $cartOwner($r);
        $v = $r->validate(['quantity' => 'required|integer|min:0|max:99',
            'revision' => 'required|integer|min:1']);
        return response()->json($cart->quantity($owner,
            (int) $variant, (int) $v['quantity'], (int) $v['revision']))->header('Cache-Control', 'no-store');
    })->whereNumber('variant');
    Route::post('/quote', function (Request $r, ShopCart $cart) use ($cartOwner) {
        $owner = $cartOwner($r);
        $v = $r->validate(['revision' => 'required|integer|min:1']);
        return response()->json($cart->quote($owner, (int) $v['revision']))->header('Cache-Control', 'no-store');
    });
    Route::post('/checkout', function (Request $r, ShopCart $cart) use ($cartOwner) {
        $owner = $cartOwner($r);
        $v = $r->validate(['revision' => 'required|integer|min:1',
            'quote_id' => ['required', 'regex:/\A[a-f0-9]{32}\z/']]);
        $result = $cart->checkout($owner, (int) $v['revision'], $v['quote_id']);
        return response()->json($result, $result['created'] ? 201 : 200)->header('Cache-Control', 'no-store');
    });
});

После успешного loginMiniApp() выполните последовательность ниже на странице приложения. Метатег CSRF должен содержать новый токен, возвращённый входом. Подставьте ID добавленного товара вместо 1. В интерфейсе между расчётом и оформлением покажите покупателю offer.items и offer.total_minor; здесь остановка перед последней командой позволяет проверить результат в консоли.

JavaScript · пробуем добавление, расчёт и повтор оформления
async function cartRequest(path, method = 'GET', body) {
  const response = await fetch('/mini/cart' + path, {
    method, credentials: 'same-origin',
    headers: {'Accept': 'application/json', 'Content-Type': 'application/json',
      'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]').content},
    ...(body === undefined ? {} : {body: JSON.stringify(body)})
  });
  if (!response.ok) throw new Error('Запрос корзины: ' + response.status);
  return response.json();
}
const initial = await cartRequest('');
const changed = await cartRequest('/items/1', 'PUT', {quantity: 1, revision: initial.revision});
const offer = await cartRequest('/quote', 'POST', {revision: changed.revision});
console.log(offer); // Покажите эти цены покупателю до следующего действия.
const checkoutBody = {revision: offer.revision, quote_id: offer.quote_id};
// Выполнить после подтверждения покупателем:
const order = await cartRequest('/checkout', 'POST', checkoutBody);
const repeated = await cartRequest('/checkout', 'POST', checkoutBody);
console.assert(order.public_id === repeated.public_id);

В БД должен появиться один заказ, а запас уменьшиться на единицу. Повтор с прежним расчётом вернёт тот же заказ даже после истечения срока расчёта. Попробуйте изменить цену до оформления: получите 409, заказ не появится. Уведомление о заказе подключайте через отдельную исходящую очередь; HTTP-вызова Telegram внутри транзакции здесь нет. Для восстановления после закрытия Mini App добавьте список своих заказов с тем же ограничением по владельцу.

Транзакции и блокировки Laravel

Проверяем сценарии магазина

  • Закройте Mini App с двумя позициями и откройте снова с того же аккаунта. Корзина загрузится с сервера. С другого аккаунта откроется его собственная корзина.

  • Измените цену или остаток между расчётом и нажатием «Оформить». Сервер вернёт конфликт, остатки и число заказов останутся прежними.

  • Отправьте два одинаковых запроса параллельно и повторите один после имитации таймаута. Все успешные ответы содержат один ID заказа, остаток уменьшится один раз.

  • Два покупателя оформляют последнюю пачку одновременно. Один заказ сохраняется, второй покупатель получает сообщение о недостаточном остатке.

Авторизация Telegram Mini Apps · Блокирующее чтение InnoDB