# Товары

Операции с товарами. Товары существуют трех типов:

* `digital` - [Цифровой товар](https://wiki.tribute.tg/ru/for-content-creators/digital-product). Любое сообщение в Telegram с опциональными вложениями
* `custom` - [Товар на заказ](https://wiki.tribute.tg/ru/for-content-creators/digital-product/digital-custom-product). Контент по запросу, например, персонализированное видео-поздравление
* `physical` - [Физический товар](https://wiki.tribute.tg/ru/for-content-creators/fizicheskie-tovary). Мерч с доставкой, например, футболка с принтом

Все суммы указаны в минимальных единицах валюты (центы/копейки)

## Получить список товаров

> Возвращает постраничный список товаров

```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"}}}}}}}}}
```

## Получить товар по 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"}}}}}}}}}
```

## Отменить покупку цифрового товара

> Отменяет покупку цифрового товара и выполняет возврат платежа.\
> \
> \*\*Важно:\*\* Этот эндпоинт поддерживает возврат только для покупок, оплаченных Telegram Stars.\
> Покупки, оплаченные другими способами, не могут быть возвращены через этот эндпоинт.<br>

```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"}}}}}}}}}
```