Telegram-заказ не создаётся дважды в Smartup: 5 проверок

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

Поэтому принимать такой проект нужно по всей цепочке: Telegram → интеграционный сервис → Smartup → передача статуса обратно в Telegram. Ниже не список функций бота, а проверки этой цепочки.

Сначала договоритесь, что считать одним заказом

Событие Telegram, платёж и документ Smartup — разные сущности. Покупатель может дважды нажать кнопку. Запрос может повториться после обрыва сети. Подтверждение оплаты может прийти позже создания заказа.

Зафиксируйте в техническом задании три идентификатора:

• идентификатор события или сессии на стороне Telegram;
• внутренний номер заказа магазина;
• идентификатор документа Smartup или другая ссылка на подтверждение, которую вернул доступный клиенту интерфейс интеграции.

Если они записываются рядом в журнале, фраза "заказ потерялся" превращается в конкретную точку сбоя.

Разделите и сам путь данных. Сообщение или callback бота приходит через webhook Telegram; Mini App может отправлять заказ напрямую в backend проекта; затем backend обращается к Smartup. Если POST-запрос Telegram к webhook получает от endpoint ответ не из диапазона 2xx, Telegram может повторить доставку того же обновления. update_id помогает распознать такую повторную доставку, но два настоящих нажатия покупателя обычно создают два разных обновления.

Поэтому ключ идемпотентности создают в начале checkout или сессии корзины и повторно используют для одного логического заказа при ретраях и двойном нажатии. Backend применяет к ключу атомарное ограничение уникальности до создания документа Smartup. Новый order_id для каждого HTTP-запроса не остановит дубликаты; update_id служит только для корреляции. Технические поля описаны в Telegram Bot API.

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

1. Обычный заказ

Заранее запишите тестовый товар, количество, цену, телефон и адрес доставки. Оформите заказ в Telegram, затем сравните все поля с документом Smartup. Проверки "документ появился" недостаточно: цена или количество могут передаться неверно.

2. Повторное нажатие

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

3. Smartup временно недоступен

Смоделируйте ситуацию, когда интеграционный сервис не может подключиться к Smartup. Если backend надёжно сохранил заказ, покупателю можно честно сообщить: "заказ получен и поставлен в очередь". Но до подтверждения Smartup нельзя говорить, что заказ записан в ERP. Заранее определите очередь, лимит попыток, экспоненциальную задержку, очередь окончательных ошибок и получателя уведомления.

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

4. Цена или остаток изменились

Что будет, если после открытия корзины в Smartup изменилась цена или товар закончился? Система отклонит заказ, покажет новую сумму или отправит его менеджеру на проверку? Это бизнес-решение. Разработчик не должен угадывать его по ходу работы.

5. Сервис перезапущен

Перезапустите сервер или интеграционный сервис в тестовой среде. Заказы в очереди не должны исчезнуть, а уже обработанные — создаться заново. Проверьте и неопределённый исход, когда Smartup создал документ, но backend упал до записи ответа: используйте downstream-ключ идемпотентности, если интерфейс Smartup его поддерживает; иначе сохраняйте sync_unknown и сверяйтесь со Smartup до повторного создания.

Что отслеживать после запуска

Одной фразы "при ошибке придёт сообщение в Telegram" недостаточно. В уведомлении нужны номер заказа, этап, время и понятное действие. Например: "Заказ T-1042 не записан в Smartup; третья попытка; нужна проверка оператора".

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

Для активной торговли нужны близкие к реальному времени оповещения об ошибках и ежедневная сверка; еженедельный отчёт можно оставить для руководства:

• сколько заказов создано в Telegram;
• сколько соответствующих документов создано в Smartup;
• сколько было повторных попыток и дубликатов;
• какие заказы исправляли вручную.

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

Чек-лист приёмки для заказчика

До подписания приёмки получите в письменном виде:

1. Какая система является источником для каждого типа данных.
2. Карту полей: SKU или ID товара, склад, единица, количество, валюта, скидка, налог, доставка, ID или телефон клиента, статус оплаты и часовой пояс.
3. Правило определения дубликатов.
4. Лимит попыток, экспоненциальную задержку, очередь окончательных ошибок, ручной повтор и порог оповещения.
5. Доступ к журналу и список получателей уведомлений.
6. Тестовые заказы с ожидаемыми результатами.
7. Владельцев токена, сервера, кода и учётных данных Smartup.

Отдельно примите статусы, оплату и безопасность

Согласуйте карту состояний как минимум для received, queued, created_in_smartup, sync_unknown, payment_pending, paid, cancelled, refunded и manual_review. До статуса paid или refunded проверьте подпись либо аутентификацию callback провайдера, заказ, сумму, валюту и авторитетный статус у провайдера. Повторный или несвоевременный callback не должен проводить платёж дважды.

В проверку безопасности включите сравнение значения параметра secret_token из setWebhook с заголовком Telegram X-Telegram-Bot-Api-Secret-Token сравнением с постоянным временем выполнения, серверную проверку initData Mini App, ротацию токенов и учётных данных Smartup, минимальные права, маскирование персональных данных в журналах и ограниченный доступ к ручному повтору.

Общие способы обмена разобраны в статье об интеграции 1С и Smartup. Вопросы владения ботом, токеном и кодом есть в руководстве о том, как заказать Telegram-бота. Проект Wallner показывает пример, где Telegram-магазин, ERP и Smartup связаны в одной системе.

Если нужно связать заказы из Telegram со Smartup, посмотрите направления разработки CRM/ERP и Telegram-ботов. Результатом технической сессии могут стать карта потока и полей, матрица ошибок, пакет приёмочных тестов и оценка ограниченного объёма; точный проект станет понятен после проверки настроек Smartup.

Частые вопросы