REST API — TELEGA-SOFT.RU

BASE URL

https://telega-soft.ru/api/v1

Все ответы в формате JSON. Формат дат: ISO 8601 (UTC).

🔐 Аутентификация

Публичные эндпоинты (список товаров, карточки) работают без авторизации. Для отзывов нужен Bearer-токен или API-ключ.

POST /auth/login

Получить JWT-токен

Тело запроса

{ "login": "[email protected]", // email или username "password": "your_password" }

Ответ

{
  "ok": true,
  "redirect": "/dashboard"
}
// access_token устанавливается в cookie httpOnly

GET Заголовок: Authorization: Bearer <token>

Или использовать API-ключ из личного кабинета:

X-API-Key: ваш_ключ_из_кабинета

📁 Категории

GET /api/v1/categories

Список всех активных категорий

Пример ответа

[
  { "id": 1, "name": "Боты", "slug": "bots", "icon": "🤖" },
  { "id": 2, "name": "Скрипты", "slug": "scripts", "icon": "📜" }
]

GET /api/v1/categories/{slug}/availability

Проверить доступность категории для текущего IP (геоблокировка)

// Доступно
{ "available": true }

// Заблокировано
{
  "available": false,
  "reason": "Данный раздел недоступен в вашем регионе",
  "country": "US"
}

📦 Товары

GET /api/v1/products

Список товаров с фильтрацией и сортировкой

Параметры

Параметр	Тип	По умолчанию	Описание
`category`	string	all	slug категории или `all`
`q`	string	—	Поиск по названию
`sort`	string	date	`date` / `rating` / `views` / `price`
`order`	string	desc	`asc` / `desc`
`limit`	int	10	Максимум 100
`offset`	int	0	Смещение для пагинации

Пример запроса

GET /api/v1/products?category=bots&sort=rating&limit=20

Пример ответа

{
  "total": 42,
  "limit": 20,
  "offset": 0,
  "items": [
    {
      "id": 1,
      "title": "Telegram Bot для магазина",
      "slug": "telegram-bot-dlya-magazina",
      "price": "1500.00",
      "price_unit": "руб/шт",
      "rating": 4.8,
      "views": 312,
      "badges": ["hot"],
      "created_at": "2025-01-15T10:30:00"
    }
  ]
}

GET /api/v1/products/{id}

Полная карточка товара

{
  "id": 1,
  "title": "Telegram Bot для магазина",
  "slug": "telegram-bot-dlya-magazina",
  "description": "Полное описание...",
  "price": "1500.00",
  "price_unit": "руб/шт",
  "contact": "@seller_username",
  "rating": 4.8,
  "reviews_count": 12,
  "views": 313,
  "badges": ["hot"],
  "custom_badge": null,
  "is_featured": false,
  "category": { "id": 1, "name": "Боты", "slug": "bots" },
  "seller": { "id": 5, "username": "seller1", "is_verified": true },
  "images": [
    { "path": "5_abc123.jpg", "is_primary": true }
  ],
  "created_at": "2025-01-15T10:30:00"
}

💬 Отзывы

GET /api/v1/products/{id}/reviews

Одобренные отзывы товара

Параметры

Параметр	Тип	Описание
`sort`	string	`date` / `rating` / `helpful`
`rating`	int	Фильтр по оценке (1–5), 0 = все
`limit`	int	Максимум 50
`offset`	int	Смещение

GET /api/v1/products/{id}/reviews/summary

Сводка рейтинга товара

{
  "count": 12,
  "average": 4.8,
  "distribution": { "1": 0, "2": 0, "3": 1, "4": 2, "5": 9 }
}

POST /api/v1/products/{id}/reviews Auth required

Оставить отзыв (требуется авторизация)

{
  "rating": 5,           // 1–5, обязательно
  "title": "Отличный!",  // необязательно
  "text": "Всё работает отлично, рекомендую!"
}

⚠️ Коды ошибок

Код	Значение
`400`	Неверный запрос (валидация)
`401`	Не авторизован
`403`	Доступ запрещён
`404`	Не найдено
`409`	Конфликт (например, уже оставляли отзыв)
`429`	Слишком много запросов
`500`	Внутренняя ошибка сервера

// Формат ошибки всегда:
{ "detail": "Текст ошибки" }

💡 Примеры кода

Python (requests)

import requests

BASE = "https://telega-soft.ru/api/v1"

# Получить категории
cats = requests.get(f"{BASE}/categories").json()

# Товары по категории
products = requests.get(f"{BASE}/products", params={
    "category": "bots",
    "sort": "rating",
    "limit": 20
}).json()

# Оставить отзыв с API-ключом
resp = requests.post(
    f"{BASE}/products/1/reviews",
    json={"rating": 5, "text": "Отличный товар!"},
    headers={"X-API-Key": "ваш_ключ"}
).json()

JavaScript (fetch)

const BASE = 'https://telega-soft.ru/api/v1';

// Товары по категории с пагинацией
const res = await fetch(`${BASE}/products?category=bots&limit=20&offset=0`);
const data = await res.json();
console.log(data.total, data.items);

// Карточка товара
const product = await fetch(`${BASE}/products/1`).then(r => r.json());

// Отзыв с API-ключом
await fetch(`${BASE}/products/1/reviews`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'ваш_ключ'
  },
  body: JSON.stringify({ rating: 5, text: 'Отлично!' })
});

cURL

# Список товаров категории "bots", сортировка по рейтингу
curl "https://telega-soft.ru/api/v1/products?category=bots&sort=rating&limit=10"

# Карточка товара
curl "https://telega-soft.ru/api/v1/products/1"

# Отзыв с API-ключом
curl -X POST "https://telega-soft.ru/api/v1/products/1/reviews" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: ваш_ключ" \
  -d '{"rating": 5, "text": "Отличный товар!"}'

🔑 API Продавца v1

Управляйте своими товарами автоматически — создавайте, редактируйте и удаляйте без браузера. Все эндпоинты требуют API-ключ с соответствующими разрешениями.

Разрешение

read

Просмотр своих товаров

Разрешение

write

Создание и изменение

Разрешение

delete

Удаление товаров

Лимит

30 / мин

POST / PUT запросы

Как получить API-ключ

Войдите в Личный кабинет → API-ключи
Нажмите «Создать ключ», укажите название
Выберите разрешения: read, write, delete
Скопируйте ключ — он показывается только один раз

Передача ключа в запросах

X-API-Key: your_api_key_here

🧪 API-ключ для тестирования эндпоинтов на этой странице

📋 Список своих товаров

GET /api/v1/me/products X-API-Key · read

Возвращает все ваши товары в любом статусе.

Пример ответа

{
  "total": 2,
  "items": [
    {
      "id": 1,
      "title": "Мой товар",
      "slug": "moy-tovar",
      "status": "approved",
      "payment_status": "paid",
      "publish_until": "2025-06-15T00:00:00",
      "views": 142,
      "rating": 4.8,
      "created_at": "2025-01-15T10:30:00"
    },
    {
      "id": 2,
      "title": "На модерации",
      "slug": "na-moderatsii",
      "status": "pending",
      "payment_status": "free",
      "publish_until": null,
      "views": 0,
      "rating": 0.0,
      "created_at": "2025-05-10T08:00:00"
    }
  ]
}

➕ Создать товар

POST /api/v1/me/products X-API-Key · write

Товар создаётся со статусом pending и отправляется на модерацию. Лимит: 30 запросов / минуту.

Тело запроса (JSON)

Поле	Тип	Обяз.	Описание
`title`	string	✅	Название товара (3–200 символов)
`category_slug`	string	✅	Slug категории из `GET /api/v1/categories`
`description`	string	✅	Описание (10–5000 символов)
`contact`	string	✅	Контакт продавца (@username, ссылка)
`price`	number\|null	—	Цена (null = Бесплатно)
`price_unit`	string	—	Единица: руб/шт, руб/мес, USD/шт… (по умолч. руб/шт)
`badges`	array	—	Плашки: `"hot"`, `"sale"`, `"new"`, `"promo"`
`custom_badge`	string\|null	—	Кастомная плашка (до 20 символов)
`publish_days`	int	—	Дней размещения (1–365, по умолч. 7)
`currency`	string	—	`RUB` или `USD` (по умолч. RUB)
`boost_search`	bool	—	Продвижение в поиске (+доп. оплата)
`boost_listing`	bool	—	Продвижение в выдаче (+доп. оплата)
`auto_renew`	bool	—	Автопродление за 24ч до истечения

Пример запроса

{
  "title": "Telegram бот для автопродаж",
  "category_slug": "bots",
  "description": "Полностью автоматизированный бот для продаж в Telegram. Поддерживает оплату, уведомления и статистику.",
  "contact": "@my_telegram",
  "price": 2500.00,
  "price_unit": "руб/шт",
  "badges": ["hot"],
  "publish_days": 30,
  "currency": "RUB",
  "boost_search": false,
  "boost_listing": false,
  "auto_renew": true
}

Пример ответа

{
  "ok": true,
  "id": 42,
  "status": "pending",
  "cost": {
    "total_rub": 310.0,
    "total_usd": 3.44,
    "total": 310.0,
    "currency": "RUB",
    "breakdown": {
      "placement": 300.0,
      "badge_hot": 50.0
    }
  }
}

Интерактивный тест

✏️ Изменить товар

PUT /api/v1/me/products/{id} X-API-Key · write

Обновляет товар. После изменения статус меняется на pending (товар снова идёт на модерацию). Тело запроса — те же поля что и при создании.

Пример запроса

PUT /api/v1/me/products/42

{
  "title": "Обновлённое название",
  "category_slug": "bots",
  "description": "Обновлённое описание товара.",
  "contact": "@my_telegram",
  "price": 3000,
  "price_unit": "руб/шт",
  "badges": ["hot", "sale"],
  "publish_days": 14,
  "currency": "RUB"
}

Ответ

{ "ok": true, "id": 42, "status": "pending" }

Интерактивный тест

ID товара:

🗑 Удалить товар

DELETE /api/v1/me/products/{id} X-API-Key · delete

Безвозвратно удаляет товар и все его изображения. Требует разрешение delete.

Ответ

{ "ok": true }

💡 Примеры кода — API Продавца

Python (requests)

import requests

BASE   = "https://telega-soft.ru/api/v1"
APIKEY = "your_api_key_here"
HEADERS = {"X-API-Key": APIKEY, "Content-Type": "application/json"}

# Получить список своих товаров
my = requests.get(f"{BASE}/me/products", headers=HEADERS).json()
print(my["total"], "товаров")

# Создать товар
new = requests.post(f"{BASE}/me/products", headers=HEADERS, json={
    "title":         "Telegram бот для магазина",
    "category_slug": "bots",
    "description":   "Полностью рабочий бот с оплатой и статистикой.",
    "contact":       "@my_telegram",
    "price":         2500,
    "price_unit":    "руб/шт",
    "badges":        ["hot"],
    "publish_days":  30,
    "currency":      "RUB",
}).json()
print("Создан:", new["id"], "статус:", new["status"])

# Изменить товар
upd = requests.put(f"{BASE}/me/products/{new['id']}", headers=HEADERS, json={
    "title":         "Обновлённое название",
    "category_slug": "bots",
    "description":   "Обновлённое описание.",
    "contact":       "@my_telegram",
    "price":         3000,
    "price_unit":    "руб/шт",
    "publish_days":  14,
    "currency":      "RUB",
}).json()
print("Обновлён:", upd)

# Удалить товар
requests.delete(f"{BASE}/me/products/{new['id']}", headers=HEADERS)

JavaScript (fetch)

const BASE = 'https://telega-soft.ru/api/v1';
const API_KEY = 'your_api_key_here';
const headers = {
  'Content-Type': 'application/json',
  'X-API-Key': API_KEY
};

// Список своих товаров
const myProducts = await fetch(`${BASE}/me/products`, { headers })
  .then(r => r.json());

// Создать товар
const created = await fetch(`${BASE}/me/products`, {
  method: 'POST', headers,
  body: JSON.stringify({
    title:         'Telegram бот для магазина',
    category_slug: 'bots',
    description:   'Описание товара.',
    contact:       '@my_telegram',
    price:         2500,
    price_unit:    'руб/шт',
    publish_days:  30,
    currency:      'RUB',
  })
}).then(r => r.json());

console.log('Создан ID:', created.id, 'Стоимость:', created.cost.total_rub, '₽');

// Изменить товар
await fetch(`${BASE}/me/products/${created.id}`, {
  method: 'PUT', headers,
  body: JSON.stringify({ title: 'Новое название', /* ... */ })
});

// Удалить
await fetch(`${BASE}/me/products/${created.id}`, {
  method: 'DELETE', headers
});

cURL

# Список своих товаров
curl -H "X-API-Key: your_key" https://telega-soft.ru/api/v1/me/products

# Создать товар
curl -X POST https://telega-soft.ru/api/v1/me/products \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Мой товар",
    "category_slug": "bots",
    "description": "Описание товара минимум 10 символов.",
    "contact": "@my_telegram",
    "price": 1500,
    "price_unit": "руб/шт",
    "publish_days": 7,
    "currency": "RUB"
  }'

# Изменить товар (ID=42)
curl -X PUT https://telega-soft.ru/api/v1/me/products/42 \
  -H "X-API-Key: your_key" \
  -H "Content-Type: application/json" \
  -d '{"title": "Новое название", "category_slug": "bots", ...}'

# Удалить товар (ID=42)
curl -X DELETE https://telega-soft.ru/api/v1/me/products/42 \
  -H "X-API-Key: your_key"

📡 REST API

🔐 Аутентификация

📁 Категории

📦 Товары

💬 Отзывы

⚠️ Коды ошибок

💡 Примеры кода

🔑 API Продавца v1

📋 Список своих товаров

➕ Создать товар

✏️ Изменить товар

🗑 Удалить товар

💡 Примеры кода — API Продавца