Как обработать Telegram BotSubscriptionUpdated со state=canceled, не отключив уже оплаченный доступ раньше срока: разделяем событие автопродления и paid-through time.
Отмена продления не равна истечению
Сначала разделите два факта: разрешено ли следующее автоматическое списание и до какого момента подтверждена текущая оплата. State canceled сообщает об отмене продолжения, но в BotSubscriptionUpdated нет самостоятельной paid-through даты. Поэтому обработчик не должен превращать canceled в revoke-now. Пользователь мог отменить будущий цикл сразу после успешной оплаты и сохранять право доступа до конца текущего периода. Точный срок получают только из доверенной записи платежа или документированной subscription surface, а при отсутствии срока устанавливают UNKNOWN и не сокращают доступ односторонним предположением.
Состояние-машина entitlement
Храните независимо subscription_state, last_successful_payment_id, paid_through_at, last_event_at и entitlement_state. active разрешает ожидать продление, но не заменяет подтверждение платежа. canceled выключает будущую попытку продления, сохраняя доступ до paid_through_at. failed означает неуспешный платёжный переход и тоже не должен стирать ранее подтверждённый период. expired вычисляется только после достижения доверенной даты с учётом часов и идемпотентной сверки. Любое событие без ключа дедупликации обрабатывают повторяемо, чтобы повторная доставка webhook не меняла срок дважды.
Порядок событий и часы
Сеть может доставить canceled раньше записи об успешной оплате или повторить старое active после нового состояния. Сравнивайте event timestamp, идентификатор подписки и монотонную paid-through дату; устаревшее событие пишется в журнал, но не откатывает более новое право. Серверные часы синхронизируют, а дату сохраняют в UTC. Не используйте время получения webhook как дату окончания и не прибавляйте период повторно при каждом active. Если источники расходятся, сохраните уже подтверждённый доступ и переведите запись в review вместо преждевременного revoke.
Обратимые тесты
В тестовой среде проиграйте последовательности success→canceled, success→failed, canceled→duplicate canceled, delayed success после canceled и rejoin до окончания периода. В каждом сценарии проверяйте только счётчик entitlement transitions и paid-through value; реальные Stars и пользовательские аккаунты не нужны. PASS: отмена запрещает новое продление, но доступ остаётся до срока; повтор не создаёт второй переход; rejoin корректно меняет будущий статус. Stop-rule: тест требует рабочий payment token, ручное редактирование production balance или удаление платежной истории.
Минимальная телеметрия
Для расследования достаточно хешированного subscription key, event type, provider event id, event time, предыдущее и новое state, paid-through time, причина решения и версия обработчика. Не журналируйте Telegram user ID в открытом виде, invoice payload, токены бота, платёжные данные и полный update. Метрики отдельно считают отмену автопродления, failed renewal и фактическое истечение; смешивать их в один churn нельзя. Алерт нужен, когда paid-through уменьшается, один event вызывает несколько переходов или canceled немедленно снимает доступ.
Критерии решения
PASS — Bot API событие идемпотентно сохранено, future renewal отключено, ранее подтверждённый срок не уменьшен и доступ прекращается только после него. FAIL — canceled вызывает немедленный revoke, paid-through переписывается временем webhook или повтор увеличивает срок. UNKNOWN — нет доверенного payment record или нельзя сопоставить подписку; тогда доступ не расширяют бесконечно, но перед отключением отправляют запись на контролируемую сверку. Документация определяет поля протокола, а не бизнес-право возврата или конкретные договорные сроки.
Материал подготовлен редакцией VOne с помощью автоматизированного черновика. Факты и границы вывода сверены 4 сентября 2026 года по указанным прямым официальным и первичным источникам. Текст написан самостоятельно, опасные действия и реальные пользовательские данные в проверку не включены.
Источники и проверка
- Telegram Bot API проверено 2026-09-04
- Telegram API — subscriptions проверено 2026-09-04
Информация актуальна на дату публикации. Правила сервисов, приложений и сетей могут меняться.