Telegram-бот для выставления счетов через Halfin API

Кейс · Telegram-бот · платёжная интеграция · Python

Автоматизация создания платёжных ссылок для менеджеров с разграничением доступа и защитой от повторных операций. Сотрудник выставляет счёт прямо в Telegram, не открывая личный кабинет платёжного сервиса.

25автоматизированных тестов
FSMпошаговый сценарий
SQLiteлокальное хранение
Idempotency-Keyзащита от дублей

Принцип надёжности: повторное действие пользователя или повторная доставка события не должны создавать второй инвойс.

Схема создания платёжной ссылки через Telegram-бот и Halfin API
Схема процесса, а не скриншот пользовательского интерфейса.

Задача

Нужно было создать закрытого Telegram-бота, через которого менеджеры могут сформировать счёт и получить готовую ссылку на оплату. Бот собирает параметры по шагам, показывает их перед отправкой и обращается к Halfin API только после подтверждения.

Ключевое требование — платёжная операция не должна повторяться из-за двойного нажатия, задержки сети или повторной доставки обновления Telegram.

Как создаётся счёт

  1. Проверка доступа

    Бот принимает команды только от активированных сотрудников. Посторонним пользователям не раскрываются ни функции системы, ни рабочие данные.

    Закрытый контур · роли и разрешения

  2. Сбор параметров

    FSM в aiogram проводит менеджера через последовательный диалог и хранит состояние черновика до подтверждения.

    Telegram · aiogram 3.31 · FSM

  3. Подтверждение

    Перед запросом к платёжному сервису менеджер видит собранные параметры и осознанно запускает создание счёта.

    Проверка перед операцией

  4. Создание ссылки

    Отдельный сервисный слой отправляет запрос в Halfin API через httpx, сохраняет результат и возвращает готовую платёжную ссылку в чат.

    Halfin API · httpx

Защита от повторного создания

Каждый черновик получает собственный draft_id. При обращении к платёжному API он участвует в формировании Idempotency-Key. Повторное нажатие относится к той же операции, а не создаёт новый независимый инвойс.

Это надёжнее одной только блокировки кнопки: событие может прийти дважды, а сетевой ответ — потеряться. Идемпотентность связывает повторный запрос с уже начатой операцией.

Архитектура без лишней инфраструктуры

КомпонентРеализация
BackendPython 3.10, aiogram 3.31
Платёжная интеграцияHalfin API, httpx
Хранение данныхSQLite
ИнтерфейсTelegram, FSM
БезопасностьРазграничение ролей и контроль доступа
Надёжностьdraft_id, Idempotency-Key
Тестирование25 автоматизированных тестов
ИнфраструктураUbuntu, SSH, rsync; systemd unit подготовлен

Long polling позволяет обойтись без публичного IP, домена и веб-сервера для webhook. Для текущего объёма достаточно SQLite.

Доступ и возможность развития

Только для сотрудников

Доступ получают менеджеры, активированные администратором. Бот не проектировался как публичный платёжный сервис.

Логика отделена от интерфейса

Создание инвойса вынесено в отдельный слой, поэтому его можно повторно использовать при разработке Telegram Mini App.

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

Набор из 25 тестов покрывает ключевую логику, включая доступ и защиту от повторных операций.

Статус внедрения

Код, тесты и unit-файл systemd подготовлены. Автоматический запуск службы на целевом сервере зависит от действий администратора, поэтому кейс не утверждает, что бот уже работает в production под управлением systemd.

Результат

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

Telegram-боты и Mini AppsЗакрытые кабинеты, диалоги, уведомления и интеграции с backend.Т-Банк → amoCRMЕщё один платёжный кейс с идемпотентностью и защитой от повторной обработки.

По теме: API-интеграции и маркетплейсы

Python 3.10 · aiogram 3.31 · Halfin API · httpx · SQLite · Telegram FSM · Idempotency-Key · systemd