Telegram-бот с записью и оплатой через ЮKassa: ТЗ и проверки

01

Как устроен мой бот для записи

У меня клиент оставляет заявку, время назначаю я, оплату подтверждает бот. Он принимает деньги через ЮKassa или bePaid, ставит назначенный созвон в Google Календарь и присылает ссылку на встречу. Бот написан на Go, данные хранятся в Postgres.

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

02

Что решить до первого запроса агенту

Сначала определите условия услуги: продолжительность, цену, валюту, порядок назначения, переноса и возврата. Для студии с несколькими мастерами добавьте исполнителя, рабочие часы и перерывы. Эти ответы станут правилами бота.

• Кто назначает встречу и сколько держится неподтверждённая запись?
• Что происходит сначала: согласование времени или предоплата?
• Кто разбирает спорные платежи и куда пишет клиент?

В моём процессе назначение и отметка «оплачено» разделены. У вашей услуги может быть другой порядок: сначала предоплата, затем подтверждение записи. Укажите его в ТЗ, чтобы агент реализовал нужные переходы.

Владелец подключает магазин, подтверждает реквизиты и согласует условия с провайдером. Бухгалтер определяет налоговые параметры. Агент получает эти решения и проверяет их передачу программе.

Запишите также, что клиент получает после оплаты и кто вправе менять цену заявки. Встреча может быть назначена, но ещё не оплачена; деньги могут быть возвращены, а история обращения сохранена. Агенту нужна таблица этих переходов, чтобы одно действие случайно не отменяло другое.

03

Что подготовить для разработки

Для работы нужны тестовый Telegram-бот, папка проекта, Claude Code или Codex, сервер и база данных. Бота создают через BotFather. Если выбираете инструмент впервые, посмотрите сравнение Claude Code и Codex и вернитесь сюда с выбранным агентом.

Токен бота и ключи магазина передавайте через предусмотренное для секретов хранилище. В отчёте агент показывает имена настроек и факт подключения, скрывая значения. Проверьте, что ключи отсутствуют в истории git, логах и скачиваемых файлах.

До подключения денег попросите инструкцию запуска: команды проверки и остановки, адрес состояния сервиса, запуск после перезагрузки. Сервер должен принимать платёжные уведомления и при закрытом терминале на вашем ноутбуке. Первым результатом работы агента пусть станет схема заявки с состояниями и проверками.

Секретный ключ API ЮKassa и токен провайдера встроенной оплаты Telegram относятся к разным схемам. Назовите агенту выбранную до настройки. Для первого проекта заведите отдельного тестового бота: так пробные сообщения и кнопки будут отделены от переписки с клиентами.

04

Как подключить ЮKassa к телеграм-боту

Мой бот использует redirect: сервер создаёт платёж по API, получает адрес подтверждения и отправляет ссылку клиенту. Человек вводит данные карты на странице ЮKassa. Такая схема появилась у клуба в сентябре 2026 года, затем у консультаций.

1. Сохранить заявку с внутренним номером.
2. Записать попытку оплаты; сумму и валюту рассчитать на сервере.
3. Создать платёж с ключом идемпотентности и ссылкой возврата.
4. Отправить клиенту полученную ссылку подтверждения.
5. После уведомления проверить платёж по API и обновить заявку.

В быстром старте ЮKassa описаны поля запроса и получение результата. Передайте агенту документацию вместе с выбранной схемой. У встроенной оплаты Telegram другое подключение через BotFather и другой токен провайдера.

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

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

05

Как бот узнаёт, что деньги пришли

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

ЮKassa ожидает HTTP 200 после принятия уведомления; при другом коде повторяет доставку в течение суток. Это описано в документации webhook. Повтор и параллельная доставка входят в приёмку.

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

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

Настоящий платёж другого заказа не оплачивает текущую заявку. Попросите агента показать автоматическую проверку на чужом идентификаторе, другой сумме и валюте. Одного поля succeeded в пришедшем JSON недостаточно: состояние должен подтвердить API, а принадлежность операции проверяет ваш сервер.

06

Как выбрать валюту и провайдера

Для первой версии я бы оставил одного провайдера и одну валюту. У моего бота с ноября 2026 года несколько вариантов, доступных при соответствующем подключении:

• Рубли: платёж через ЮKassa.
• Доллары: платёж через bePaid.
• BYN: bePaid выставляет доллары, банк списывает белорусские рубли по своему курсу.

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

Мой бот предупреждает о прямой оплате картой «Мир» и вариантах SberPay или T-Pay. Это условие моего подключения, зафиксированное после ответа ЮKassa. Для своего магазина подтвердите доступные способы у провайдера и покажите ограничения до перехода на оплату.

07

Как связать запись с Google Календарём

Источник времени у меня один: заявка. После назначения бот ставит часовое событие в отдельный Google Календарь: имя клиента, выдержка из заявки, ссылка встречи и переход в админку. Перенос двигает то же событие с постоянным идентификатором.

Отказ, откладывание и просьба о переносе убирают событие; проведённый созвон остаётся в истории дня. Ручная правка календаря обратно в заявку не переносится. Чтобы изменить время, я меняю заявку.

Синхронизация работает в фоне с повтором после сбоя и восстановлением будущих встреч при старте. Для создания Google Meet понадобилось отдельное согласие владельца через OAuth. Если его нет, подходит ручная ссылка. Бот присылает её клиенту в напоминании за полтора часа.

Если клиент должен сам выбирать слот

Добавьте рабочие часы, часовой пояс, длительность, перерывы и срок удержания места до оплаты. Проверьте две параллельные заявки на один час: подтвердиться должна одна. Для поздней оплаты истёкшей брони заранее выберите порядок переноса или возврата.

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

Сервисный аккаунт записывает события, но создать Meet от его имени в моём личном Gmail не получилось; это проверено 7 октября 2026 года. Отдельное согласие владельца решает эту задачу. Приглашение из календаря сервисный аккаунт клиенту не отправляет: ссылку доставляет бот.

08

Что проверить с чеками и 54-ФЗ

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

В «Чеках от ЮKassa» для регистрации передаются сведения об услуге, контакты покупателя и другие параметры. В этом решении чек доставляется на электронную почту. У моего клиента API параметры чека включаются настройкой; применимость требований к продавцу определяет человек.

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

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

09

Какие сбои проверить до запуска

Проверьте успешную оплату и четыре группы сбоев ниже. Используйте отдельное окружение и реквизиты из документации тестового магазина. Мой клиент сравнивает флаг тестового платежа с режимом конфигурации и останавливает проведение при несовпадении.

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

10

Как начать с ТЗ и чек-листом

Скачайте ТЗ на бота и чек-лист тестового платежа. В ТЗ есть вопросы владельцу, состояния заявки, первая версия и приёмка. Файлы Markdown открываются текстовым редактором.

Нажмите «Скопировать промпт» рядом с обложкой и приложите файлы к разговору с Claude Code или Codex. Начните с заявки без денег, затем подключите тестовую оплату, потом календарь. Если трудно сформулировать проверяемый результат первого участка, используйте постановку задачи с критериями приёмки.

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

11

Когда можно принимать настоящие заявки

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

Восстановите резервную копию в тестовую базу и запишите порядок временного закрытия новых оплат. Переход в боевой магазин сделайте отдельным шагом: сверка реквизитов, способов оплаты, webhook, чеков и сообщений клиенту. Зафиксируйте принятую версию и ответственного за запуск.

После запуска остаются обновления сервера, условия оплаты и доступ Google. Назначьте того, кто получает ошибки и помогает клиентам. Эта работа входит в обслуживание собственного бота.

12

Источники

Код personal-website и документация сверены 6 ноября 2026 года. Основа моего примера: решения 0093 об оплате клуба, 0128 о календаре, 0135 об оплате консультации и 0174 о выборе валюты.

• ЮKassa: быстрый старт API.
• ЮKassa: уведомления.
• ЮKassa: тестирование.
• ЮKassa: регистрация и доставка чеков.
• Telegram: платежи за товары и услуги. Для цифровых товаров и услуг внутри Telegram действуют отдельные правила Stars; согласуйте допустимый сценарий для своей категории.

13

Границы

Статья описывает устройство моего бота по коду и решениям, без аудита живых платежей и оценки сроков повторения. Самостоятельный выбор слотов предложен как расширение. ТЗ помогает поставить задачу агенту; условия приёма денег и запуск согласует владелец.