# Интеграция цифровых товаров в свой продукт
### Преимущества интеграции цифровых товаров Tribute
#### Для вас как владельца сервиса:
* **Приём платежей** - СБП и Telegram Stars
* **Простая интеграция** - создайте товар, получите ссылку, настройте вебхук
* **Готовая инфраструктура** - не нужно самостоятельно интегрировать платёжные провайдеры
* **Автоматические выводы** - получайте деньги в USDT
#### Для ваших пользователей:
* **Удобная оплата** - покупка в один клик через Telegram
* **Доступные способы оплаты** - СБП, Telegram Stars
### Как это работает: общая схема
#### 1. Вы [создаёте цифровой товар](https://wiki.tribute.tg/ru/for-content-creators/digital-product/how-to-create-a-digital-product) в Tribute
Например, для AI-ассистента это может быть "Доступ к AI-ассистенту на 1 месяц"
#### 2. Получаете уникальную ссылку на оплату
Каждый товар имеет свою ссылку вида:
* Для Telegram: `https://t.me/tribute/app?startapp=p123`
* Для браузера: `https://web.tribute.tg/p/123`
#### 3. Направляете пользователей на эту ссылку
В вашем боте или другом сервисе добавляете кнопку "Оплатить", которая ведёт на ссылку товара
#### 4. Пользователь оплачивает
Покупатель может:
* Оплатить напрямую Telegram Stars (если есть на балансе)
* Купить Stars через СБП и сразу обменять их на товар
#### 5. Вы получаете вебхук об успешной оплате
После оплаты на ваш сервер приходит POST-запрос с информацией о покупке. Подробнее о формате вебхуков в [документации по вебхукам](https://wiki.tribute.tg/ru/api-dokumentaciya/vebkhuki)
#### 6. Предоставляете доступ пользователю
По Telegram ID из вебхука активируете услугу для пользователя
### Пошаговая инструкция по настройке
#### Шаг 1: Регистрация в Tribute
1. Откройте [@tribute](https://t.me/tribute) в Telegram
2. Нажмите "Начать" и следуйте инструкциям
3. Перейдите в раздел "Дашборд автора"
#### Шаг 2: Создание цифрового товара
1. **В дашборде выберите "Цифровые товары" → "Создать готовый товар"**
2. **Вы будете перенаправлены в чат с ботом**
Отправьте боту сообщение, которое станет вашим цифровым товаром. Это может быть любое ваше сообщение - например, фотография с описанием, видео, файл или даже кружочек.
**Пример текстового сообщения для интеграции:**
```о
✅ Спасибо за покупку доступа к AI-ассистенту на 1 месяц!
Доступ будет предоставлен автоматически.
Для активации подписки вернитесь в @YourAIBot
```
> **Важно:** Именно это сообщение получит покупатель после оплаты. Добавьте инструкции для пользователя, чтобы он понимал, что делать дальше. После создания товара отредактировать это сообщение будет нельзя (но вы всегда сможете создать новый цифровой товар с другим сообщением).
3. **После отправки сообщения нажмите кнопку "Создать товар" из сообщения бота**
4. **Заполните обязательные поля:**
* **Валюта** - выберите валюту для оплаты
* **Название** - что увидит покупатель (например: "AI-ассистент на 1 месяц")
* **Описание** - краткое описание товара
* **Цена** - стоимость в выбранной валюте
5. **Сохраните товар**
После сохранения вы получите уникальную ссылку для оплаты, которую можно использовать в вашей интеграции
#### Шаг 3: Получение API-ключа
1. В дашборде откройте меню (три точки) → "Настройки"
2. Перейдите в раздел "API-ключи"
3. Нажмите "Сгенерировать новый ключ"
4. Сохраните ключ в безопасном месте - он понадобится для проверки вебхуков
#### Шаг 4: Настройка вебхуков
1. В разделе "API-ключи" найдите поле "URL вебхука"
2. Укажите адрес вашего сервера для приёма вебхуков:
```
https://your-server.com/webhook/tribute
```
3. Сохраните настройки
#### Шаг 5: Обработка вебхуков на вашем сервере
После успешной оплаты цифрового товара Tribute отправит POST-запрос на ваш URL:
Формат вебхука
```json
{
"name": "new_digital_product",
"created_at": "2025-03-20T01:15:58.332Z",
"sent_at": "2025-03-20T01:15:58.542Z",
"payload": {
"product_id": 456,
"amount": 500,
"currency": "usd",
"user_id": 31326,
"telegram_user_id": 12321321
}
}
```
**Проверка подписи вебхука**
Каждый запрос содержит заголовок `trbt-signature` с HMAC-SHA256 подписью тела запроса. Примеры проверки подписи и обработки вебхуков доступны в [документации по вебхукам](https://wiki.tribute.tg/for-content-creators/api-documentation/webhooks)
#### Шаг 6: Интеграция в вашего бота
В вашем Telegram-боте добавьте кнопку оплаты
Пример кода на Python
```python
# Python + python-telegram-bot
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
def send_payment_button(update, context):
keyboard = [[
InlineKeyboardButton(
"💳 Оплатить (499₽)",
url="https://t.me/tribute/app?startapp=p456"
)
]]
reply_markup = InlineKeyboardMarkup(keyboard)
update.message.reply_text(
"AI-ассистент на 1 месяц - 499₽",
reply_markup=reply_markup
)
```
### Работа с API
## Получить товар по ID
> Возвращает отдельный товар по его ID
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Операции с товарами. Товары существуют трех типов:\n\n- `digital` - [Цифровой товар](https://wiki.tribute.tg/ru/for-content-creators/digital-product). Любое сообщение в Telegram с опциональными вложениями\n- `custom` - [Товар на заказ](https://wiki.tribute.tg/ru/for-content-creators/digital-product/digital-custom-product). Контент по запросу, например, персонализированное видео-поздравление\n- `physical` - [Физический товар](https://wiki.tribute.tg/ru/for-content-creators/fizicheskie-tovary). Мерч с доставкой, например, футболка с принтом\n\nВсе суммы указаны в минимальных единицах валюты (центы/копейки)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API ключ для аутентификации."}},"schemas":{"Product":{"type":"object","required":["id","type","name","amount","currency","status","isCustom","acceptCards","acceptWalletPay","protectContent","created","updated","link","webLink"],"properties":{"id":{"type":"integer","description":"ID товара"},"type":{"type":"string","description":"Тип товара","enum":["digital","custom","physical"]},"name":{"type":"string","description":"Название товара"},"description":{"type":"string","description":"Описание товара"},"amount":{"type":"integer","format":"int64","description":"Цена товара в минимальных единицах валюты (центах для USD/EUR, копейках для RUB). Для физических товаров это стартовая цена — берётся по самому дешёвому варианту."},"currency":{"type":"string","description":"Код валюты","enum":["USD","EUR","RUB"]},"starsAmount":{"type":"integer","description":"Цена в Telegram Stars"},"starsAmountEnabled":{"type":"boolean","description":"Включена ли оплата через Stars"},"status":{"type":"string","description":"Статус товара","enum":["pending","approved","rejected"]},"isCustom":{"type":"boolean","description":"Является ли товар кастомным"},"acceptCards":{"type":"boolean","description":"Принимается ли оплата картой"},"acceptWalletPay":{"type":"boolean","description":"Принимается ли оплата через кошелек"},"protectContent":{"type":"boolean","description":"Включена ли защита контента"},"created":{"type":"string","format":"date-time","description":"Дата создания товара"},"updated":{"type":"string","format":"date-time","description":"Дата последнего обновления товара"},"pendingOrders":{"type":"integer","description":"Количество ожидающих заказов (для кастомных товаров)"},"imageUrl":{"type":"string","format":"uri","description":"URL изображения товара"},"link":{"type":"string","format":"uri","description":"Прямая ссылка на товар в приложении Telegram"},"webLink":{"type":"string","format":"uri","description":"Веб-ссылка на товар"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Код ошибки","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Описание ошибки"}}}}},"paths":{"/products/{id}":{"get":{"summary":"Получить товар по ID","description":"Возвращает отдельный товар по его ID","tags":["Products"],"parameters":[{"name":"id","in":"path","description":"ID товара","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Успешный ответ","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Некорректный запрос (неверный формат ID товара)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Неавторизован (неверный API ключ)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Доступ запрещен","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Товар не найден","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Получить список товаров
> Возвращает постраничный список товаров
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Операции с товарами. Товары существуют трех типов:\n\n- `digital` - [Цифровой товар](https://wiki.tribute.tg/ru/for-content-creators/digital-product). Любое сообщение в Telegram с опциональными вложениями\n- `custom` - [Товар на заказ](https://wiki.tribute.tg/ru/for-content-creators/digital-product/digital-custom-product). Контент по запросу, например, персонализированное видео-поздравление\n- `physical` - [Физический товар](https://wiki.tribute.tg/ru/for-content-creators/fizicheskie-tovary). Мерч с доставкой, например, футболка с принтом\n\nВсе суммы указаны в минимальных единицах валюты (центы/копейки)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API ключ для аутентификации."}},"schemas":{"Product":{"type":"object","required":["id","type","name","amount","currency","status","isCustom","acceptCards","acceptWalletPay","protectContent","created","updated","link","webLink"],"properties":{"id":{"type":"integer","description":"ID товара"},"type":{"type":"string","description":"Тип товара","enum":["digital","custom","physical"]},"name":{"type":"string","description":"Название товара"},"description":{"type":"string","description":"Описание товара"},"amount":{"type":"integer","format":"int64","description":"Цена товара в минимальных единицах валюты (центах для USD/EUR, копейках для RUB). Для физических товаров это стартовая цена — берётся по самому дешёвому варианту."},"currency":{"type":"string","description":"Код валюты","enum":["USD","EUR","RUB"]},"starsAmount":{"type":"integer","description":"Цена в Telegram Stars"},"starsAmountEnabled":{"type":"boolean","description":"Включена ли оплата через Stars"},"status":{"type":"string","description":"Статус товара","enum":["pending","approved","rejected"]},"isCustom":{"type":"boolean","description":"Является ли товар кастомным"},"acceptCards":{"type":"boolean","description":"Принимается ли оплата картой"},"acceptWalletPay":{"type":"boolean","description":"Принимается ли оплата через кошелек"},"protectContent":{"type":"boolean","description":"Включена ли защита контента"},"created":{"type":"string","format":"date-time","description":"Дата создания товара"},"updated":{"type":"string","format":"date-time","description":"Дата последнего обновления товара"},"pendingOrders":{"type":"integer","description":"Количество ожидающих заказов (для кастомных товаров)"},"imageUrl":{"type":"string","format":"uri","description":"URL изображения товара"},"link":{"type":"string","format":"uri","description":"Прямая ссылка на товар в приложении Telegram"},"webLink":{"type":"string","format":"uri","description":"Веб-ссылка на товар"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Код ошибки","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Описание ошибки"}}}}},"paths":{"/products":{"get":{"summary":"Получить список товаров","description":"Возвращает постраничный список товаров","tags":["Products"],"parameters":[{"name":"page","in":"query","description":"Номер страницы","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","description":"Количество элементов на странице","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"type","in":"query","description":"Фильтр по типу товара","required":false,"schema":{"type":"string","enum":["digital","custom","physical"]}},{"name":"desc","in":"query","description":"Сортировка по ID в убывающем порядке","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Успешный ответ","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer","format":"int64","description":"Общее количество элементов"},"offset":{"type":"integer","format":"int64","description":"Текущий номер страницы"},"limit":{"type":"integer","format":"int64","description":"Размер страницы"}}}}}}}},"400":{"description":"Некорректный запрос","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Неавторизован (неверный API ключ)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Отменить покупку цифрового товара
> Отменяет покупку цифрового товара и выполняет возврат платежа.\
> \
> \*\*Важно:\*\* Этот эндпоинт поддерживает возврат только для покупок, оплаченных Telegram Stars.\
> Покупки, оплаченные другими способами, не могут быть возвращены через этот эндпоинт.
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Операции с товарами. Товары существуют трех типов:\n\n- `digital` - [Цифровой товар](https://wiki.tribute.tg/ru/for-content-creators/digital-product). Любое сообщение в Telegram с опциональными вложениями\n- `custom` - [Товар на заказ](https://wiki.tribute.tg/ru/for-content-creators/digital-product/digital-custom-product). Контент по запросу, например, персонализированное видео-поздравление\n- `physical` - [Физический товар](https://wiki.tribute.tg/ru/for-content-creators/fizicheskie-tovary). Мерч с доставкой, например, футболка с принтом\n\nВсе суммы указаны в минимальных единицах валюты (центы/копейки)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API ключ для аутентификации."}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Код ошибки","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Описание ошибки"}}}}},"paths":{"/products/purchases/{purchaseId}/cancel":{"post":{"summary":"Отменить покупку цифрового товара","description":"Отменяет покупку цифрового товара и выполняет возврат платежа.\n\n**Важно:** Этот эндпоинт поддерживает возврат только для покупок, оплаченных Telegram Stars.\nПокупки, оплаченные другими способами, не могут быть возвращены через этот эндпоинт.\n","tags":["Products"],"parameters":[{"name":"purchaseId","in":"path","description":"ID покупки цифрового товара (ProductPurchase.ID)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Покупка успешно отменена, платёж возвращён","content":{"application/json":{"schema":{"type":"object","required":["success","purchaseId","message"],"properties":{"success":{"type":"boolean","description":"Статус успешности операции"},"purchaseId":{"type":"integer","description":"ID отменённой покупки"},"message":{"type":"string","description":"Сообщение об успехе"}}}}}},"400":{"description":"Некорректный запрос","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Неавторизован (неверный API ключ)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Доступ запрещён (не владелец товара)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Покупка или пользователь не найден","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Внутренняя ошибка сервера","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
{% openapi-webhook spec="api-ru" name="newDigitalProduct" method="post" %}
[Broken link](https://wiki.tribute.tg/ru/for-content-creators/digital-product/broken-reference)
{% endopenapi-webhook %}
{% openapi-webhook spec="api-ru" name="digitalProductRefund" method="post" %}
[Broken link](https://wiki.tribute.tg/ru/for-content-creators/digital-product/broken-reference)
{% endopenapi-webhook %}
### Создание разных тарифов
Для разных тарифов создайте несколько цифровых товаров:
1. **AI-ассистент - 1 месяц** (ID: 456) - 499₽
2. **AI-ассистент - 3 месяца** (ID: 457) - 1299₽
3. **AI-ассистент - 1 год** (ID: 458) - 3999₽
### Обработка повторных попыток
При ошибке доставки вебхука Tribute повторяет попытки через:
* 5 минут
* 15 минут
* 30 минут
* 1 час
* 10 часов
Убедитесь, что ваш обработчик идемпотентен (повторная обработка того же платежа не создаст дубликаты).
### Выводы средств
Заработанные средства вы можете выводить в USDT (вывод на банковские карты будет добавлен в будущем). Настройте автоматические выводы в разделе "Кошелек".
### Часто задаваемые вопросы
Как быстро приходят вебхуки?
Обычно в течение 1-2 секунд после успешной оплаты.
Можно ли отменить платёж?
Цифровой товар можно отменить через поддержку Tribute.
***