Платформа
Решения
Кто использует Directual и почему?
Что можно сделать на платформе?
Какие отрасли подходят для Directual?
Материалы
Простое руководство о том, как интегрировать платежи TON в ваше приложение на Directual.
Здравствуйте и добро пожаловать! Сегодня мы покажем вам, как интегрировать платежи TON в ваше приложение на Directual. И кстати, вы можете также посмотреть наш видеоурок.
TON — это невероятный новый блокчейн, построенный на инфраструктуре Telegram. Он спроектирован как распределённый суперкомпьютер, или «суперсервер», предназначенный для предоставления различных продуктов и сервисов, способствующих развитию децентрализованного видения нового интернета. Подробнее о TON можно узнать здесь.
Чтобы показать, как это выглядит на практике, рассмотрим простое приложение с обычными пользователями и администратором. Администратор создаёт счета, а пользователи их оплачивают.
Войдём как администратор и посмотрим на страницу My Bills. Здесь вы найдёте счета, которые нужно оплатить, а также те, что уже оплачены или отменены. У счетов есть три статуса: New, Paid и Canceled. Вот как это выглядит на странице.
Интерфейс приложения My Bills
На странице администратора отображаются все счета. Их можно сортировать по статусу или даже создать новый счёт.
Администратор также может задать сумму в TON и указать, для кого предназначен счёт.
Давайте посмотрим на структуры данных нашего приложения. Их можно найти на вкладке Database.
Теперь посмотрим на меню. Здесь вы найдёте ссылку на страницу My Bills, которая доступна всем. Также есть папка со страницами, доступными только администратору.
Помимо стандартных веб-страниц, у нас есть две пользовательские страницы: All Bills и My Bills. У страницы All Bills есть две вкладки. На первой — компонент табличного представления, связанный с эндпоинтом, доступным только администратору.
На второй вкладке — компонент многошаговой формы, также связанный с эндпоинтом только для администратора. Эта форма используется для создания счетов. Посмотрим на поля. Их всего три: сумма в TON, клиент — выпадающий список, связанный с эндпоинтом, и скрытое поле статуса со значением по умолчанию New. По умолчанию все новые счета получают статус New.
На странице My Bills вы найдёте компонент Cards view вместе с эндпоинтом.
У этого эндпоинта, через который карточки получают данные, есть два фильтра: Bill User ID равен ID пользователя, и Status равен параметру, передаваемому компонентом, что позволяет использовать один эндпоинт для обоих компонентов карточек.
Для самой карточки мы используем обычный HTML. При клике на неё вы попадаете на подстраницу страницы My Bills. Эта страница также установлена как домашняя.
Теперь давайте настроим платежи TON. Сначала нам нужен кошелёк. Вы можете использовать любой кошелёк, но я буду использовать Wallet от Telegram.
В приложении перейдите в раздел плагинов и установите бесплатный плагин TON из маркетплейса. Этот плагин включает компоненты для веб-страниц и дополнительные шаги для различных сценариев. Всю необходимую информацию об этом плагине можно найти в официальной документации.
Начнём с веб-части и добавим плагин на страницу. Перейдём на подстраницу, которая является страницей счёта. Этот раздел отображается только если статус счёта New. Если статус Paid, появится другой раздел.
Нам нужно беспокоиться о компоненте оплаты только для новых счетов, поэтому мы поместили его в этот раздел. Он работает с эндпоинтом, который получает единственный объект счёта с этой подстраницы. Мы просто вставляем кошелёк, на который будем получать платежи, и берём данные из эндпоинта. Это также включает сумму в нано TON и номер заказа.
Небольшое уточнение: все счета мы создаём в TON. Для заполнения поля нано TON мы используем сценарий.
Этот сценарий запускается для всех новых объектов и при изменении суммы в поле TON. Сумма в нано TON — это просто сумма в TON, умноженная на глобальную константу.
В качестве номера заказа мы используем ID счёта. Именно так мы будем идентифицировать платёж. Также нам нужно настроить вебхук для получения уведомлений. Просто создайте новый вебхук и включите опцию CORS, чтобы избежать ошибок.
Просто скопируйте URL этого вебхука в компонент. Теперь сохраните и протестируйте.
В нашем приложении просто нажмите на любой новый счёт, чтобы увидеть кнопку Connect wallet.
Небольшое уточнение: эта кнопка недоступна для оплаченных или отменённых счетов.
Давайте подключим кошелёк. Мы будем использовать Telegram Wallet.
Кошелёк сообщает, что приложение My Bills хочет подключиться и что все транзакции всё равно будут подтверждаться нами.
Небольшое уточнение: вы можете настроить иконку или название в настройках веб-приложения на вкладках Icons и General Settings.
Мы подключили кошелёк, отлично! Мы также можем отключить его или подтвердить транзакцию.
Теперь выбранный кошелёк снова готов к работе, поэтому нажимаем Confirm. Сумма будет списана с кошелька. Готово! Транзакция прошла успешно.
Теперь давайте посмотрим на структуру вебхука. Здесь мы видим, что получили уведомление, но нужно помнить, что это уведомление — не то же самое, что подтверждение транзакции.
В любом случае, стоит проверить блокчейн. Вы можете использовать Tonscan, чтобы проверить свой кошелёк и убедиться, что транзакция с нужной суммой и комментариями действительно прошла.
Теперь давайте автоматизируем получение транзакций. Для этого просто создайте новую структуру данных — назовём её TON Transactions — и добавьте нужные поля. Нам понадобятся ID пользователя, сумма, связь со счётом и флаг обработки транзакции, который должен быть булевого типа.
Также нам нужна структура, которая будет служить триггером, состоящая всего из одного объекта. Этот объект будет запускать сценарий по расписанию.
Хорошо, давайте соберём несколько сценариев. Просто поместим их в папку под названием TON. Первый сценарий называется Get TON Transactions. Этот сценарий будет использовать единственный объект-триггер, который будет запускаться по ежедневному расписанию. Такие типы сценариев извлекают все объекты структуры, а затем обрабатывают их. В нашем случае это всего лишь один объект с ID равным одному.
Добавим шаг Get TON Transactions. Этот шаг возвращает нам ответ в формате JSON, который нам нужно сохранить. Для этого просто добавьте ещё одно поле JSON в триггер и вернитесь к сценарию.
В этом шаге вам нужно указать адрес, на который вы хотите получать транзакции, и поле для ответа.
Вы можете проверить панель отладки, чтобы увидеть, что сервис TON API вернул нам JSON со всеми транзакциями.
Чтобы разобрать их, нам нужен массив связей на будущие транзакции. Нужно просто добавить поле массива связей в структуру TON Transactions. Вернёмся к сценарию и добавим шаг JSON для разбора ответа.
Если вы добавите комментарии, сценарии будет проще понимать. Далее настроим шаг JSON и определимся со структурой ответа. Вот как структурирован JSON, который мы будем разбирать. Теперь настроим правила разбора.
Данные хранятся в поле API response. Мы разбили массив JSON Transactions на объекты, которые сохранили в массиве Transactions.
В документации указано, на какие поля стоит обращать внимание: в основном value и comment.
Мы берём значение из этого JSON и добавляем его в поле Amount nano TONS будущих объектов транзакций. Также мы берём комментарий из объекта Decoded Body.
Нам просто нужно добавить текстовое поле в поле comment. Теперь сохраните. Далее нам нужно обработать транзакции, которые хранятся в поле Array link. Мы сделаем это в другом сценарии, поэтому добавим шаг Link scenario и настроим сам сценарий обработки транзакций. Этот сценарий работает со структурой TON Transactions без каких-либо триггеров, потому что мы будем вызывать его шагом Link scenario.
Сначала мы проверяем, была ли транзакция уже обработана. Небольшое уточнение: мы добавили поле Is Processed. Если это поле true, мы просто выходим из сценария. Это означает, что транзакция уже обработана. Если ещё нет — обработаем её.
Для наглядности запустим этот сценарий и посмотрим, что произойдёт. Шаг Link scenario может работать с массивом связанных объектов и отправлять их в другой сценарий.
Запустим его и посмотрим, как он работает. Просто отправим объект-триггер через панель отладки, и посмотрим. Логи показывают, что всё работает как надо, и мы видим все транзакции в структуре данных.
Вот последняя — та, которую мы только что сделали. В списке есть и более старые транзакции. Можно отфильтровать некоторые старые записи, если поле comment пустое. Либо транзакция обрабатывается, либо комментарий пуст.
Далее мы получим ID счёта из этого комментария. Как это сделать, можно узнать в документации. Это немного сложный момент, но по сути это просто регулярное выражение. Его можно скопировать прямо из официальной документации. Это самый простой способ получить номер заказа. Мы используем поле Comment и включаем режим Coding, что позволяет нам обрабатывать данные с помощью JavaScript.
Получив ID счёта, мы можем открыть его как связанный объект, изменить статус на Paid и установить флаг Is Processed в True.
Теперь сохраните и опубликуйте сценарий. Давайте посмотрим на шаг получения транзакций. Протестируем сценарий с помощью панели отладки. Отправим объект и посмотрим. Статус счёта меняется на Paid. Сработало!
Теперь давайте поговорим об уведомлениях, которые мы получаем от вебхука. Они в основном используются для своевременного получения транзакций из блокчейна. Чтобы запускать сценарий по триггеру, нам нужна связь с этим триггером. Поэтому мы добавляем контекстную переменную типа Link в структуру Trigger.
Далее нам нужно заполнить эту контекстную переменную.
Небольшое уточнение: у нас есть ID в поле Link, и оно равно одному.
После получения уведомления может пройти несколько минут, прежде чем транзакция появится в блокчейне. Установим задержку в три минуты. После этого мы отправим объект-триггер — связанный объект из контекстной переменной — в наш сценарий Get TON Transactions.
Вполне возможно, что блокчейн не успеет справиться за три минуты, поэтому проверим дважды. Через три минуты и через шесть минут.
Таким образом, цепочка из двух запусков сценария Get TON Transactions гарантирует, что пользователь увидит свою транзакцию практически в реальном времени.
Если вы выполните эти шаги, вам удастся успешно интегрировать платежи TON в ваше приложение на Directual. Присоединяйтесь к нашему no-code сообществу, делитесь своими идеями и задавайте вопросы. До встречи в следующий раз!
