TGLift - API для реселлеров

Доступ

Ваш API-ключ

Проверяем авторизацию...

Полный ключ показывается только один раз

Храните ключ на сервере. Не добавляйте его в URL, браузерный JavaScript, репозиторий или аналитику.

Подключение

Базовые правила

Base URLhttps://tglift.ru/api/v1

АвторизацияX-API-Key: tgl_...

ФорматJSON или form-urlencoded; ответы всегда JSON

Новый заказОбязателен уникальный Idempotency-Key

Лимит120 запросов в минуту на аккаунт

Контракт

Методы API

HTTP	URL	Назначение	Основные параметры
GET	`/api/v1/services`	Каталог доступных услуг TGLift	`locale`, `currency`
GET	`/api/v1/balance`	Баланс аккаунта	`currency`
GET	`/api/v1/orders`	Заказы, сначала новые	`limit` 1-100, `offset`
POST	`/api/v1/orders`	Создать заказ	`service`, параметры из `orderRequirements`
GET	`/api/v1/orders/{RQ-ID}`	Получить один заказ	Только ID заказа TGLift
POST	`/api/v1/orders/{RQ-ID}/cancel`	Запросить отмену	Услуга должна поддерживать отмену
POST	`/api/v1/orders/{RQ-ID}/refill`	Запросить восстановление	Услуга должна поддерживать refill

Изменяющие операции работают только через POST. Вызов add, cancel или refill через GET возвращает 405 method_not_allowed.

GET /services

Контракт услуги

Получайте каталог перед созданием заказа. Поле rate содержит вашу публичную цену TGLift в выбранной валюте. pricingUnit=1000_units означает цену за 1000 единиц, package — фиксированную цену пакета.

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

[
  {
    "service": "631",
    "name": "Telegram подписчики",
    "type": "Обычный",
    "category": "Telegram - Подписчики",
    "rate": "250.00",
    "ratePer": 1000,
    "pricingUnit": "1000_units",
    "currency": "RUB",
    "min": 100,
    "max": 100000,
    "refill": true,
    "cancel": false,
    "orderRequirements": {
      "type": "default",
      "requiresLink": true,
      "requiresQuantity": true,
      "quantityFrom": null,
      "fields": []
    }
  }
]

orderRequirements

Специальные типы услуг

Не определяйте поля по названию услуги. Используйте orderRequirements конкретной услуги: он показывает обязательность ссылки, количества и специальных полей.

type	Поля	Как определяется количество
`default`	`link`, `quantity`	`quantity`
`package`	`link`	Фиксированный пакет
`custom_comments`, `custom_replies`	`link`, `fields.comments`	Число непустых строк
`seo`	`link`, `quantity`, `fields.keywords`	`quantity`
`poll`	`link`, `quantity`, `fields.pollAnswer`	`quantity`
`invites_from_groups`	`link`, `quantity`, `fields.groups`	`quantity`
`comment_likes`, `comment_replies`	`link`, `quantity`, `fields.username`	`quantity`
`mentions_*`	`username`, `usernames`, `hashtag`, `hashtags` или `mediaUrl` согласно `fields`	Согласно `quantityFrom`
`subscriptions`	`username`, `min`, `max`, `delay`; опционально `posts`, `oldPosts`, `expiry`	`max`

В JSON специальные поля передаются внутри fields. При application/x-www-form-urlencoded передавайте их на верхнем уровне.

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

curl -X POST "https://tglift.ru/api/v1/orders" \
  -H "X-API-Key: tgl_xxx" \
  -H "Idempotency-Key: order-20260722-0001" \
  -H "Content-Type: application/json" \
  --data '{
    "service": "631",
    "link": "https://t.me/example_channel/10",
    "quantity": 1000,
    "locale": "ru",
    "currency": "RUB"
  }'

Ответ 201

{
  "order": "RQ-MRX1ABC2-12AB34",
  "status": "pending",
  "idempotentReplay": false
}

При сетевом повторе отправляйте тот же запрос с тем же ключом. API вернёт тот же заказ и idempotentReplay: true.

GET /orders/{RQ-ID}

Контракт заказа

{
  "order": "RQ-MRX1ABC2-12AB34",
  "service": "631",
  "status": "in_progress",
  "statusMessage": "",
  "charge": "250.00",
  "currency": "RUB",
  "link": "https://t.me/example_channel/10",
  "quantity": 1000,
  "remains": 420,
  "startCount": 15000,
  "refundedAmount": "0.00",
  "cancelRequestedAt": null,
  "refillRequestedAt": null,
  "createdAt": "2026-07-22T10:00:00.000Z",
  "updatedAt": "2026-07-22T10:05:00.000Z"
}

remains и startCount могут быть null, пока данные не появились. Все идентификаторы заказа в публичном API — идентификаторы TGLift.

OrderStatus

Значения статусов

Статус	Значение	Что делать интеграции
`pending`	Заказ принят и ожидает начала	Проверять статус с разумным интервалом
`in_progress`	Заказ выполняется	Продолжать проверку
`completed`	Выполнен полностью	Финальный статус
`partial`	Выполнен частично	Финальный; возможен автоматический возврат остатка
`canceled`	Отменён	Финальный; проверить `refundedAmount`
`failed`	Не удалось запустить или выполнить	Не повторять автоматически с новым ключом; проверить заказ
`cancel_requested`	Отмена запрошена	Ждать финального статуса
`payment_required`	Недостаточно средств для продолжения	Пополнить баланс
`under_review`	TGLift уточняет результат обработки	Не создавать дубликат; ждать обновления

Единый формат ошибки

{
  "ok": false,
  "error": "Описание ошибки",
  "code": "invalid_request",
  "requestId": "REQ-...",
  "details": {}
}

Сохраняйте requestId: он нужен поддержке для поиска конкретного запроса. Секретный ключ в обращение не отправляйте.

HTTP-коды

400Некорректные параметры или отсутствует Idempotency-Key

401Нет корректного X-API-Key

402Недостаточно средств

404Метод или заказ TGLift не найден

405Неверный HTTP-метод

409Конфликт идемпотентности или состояния заказа

429Превышен лимит; учитывайте Retry-After

5xxВременная ошибка TGLift; повторяйте с задержкой

Надёжность

Лимиты и повторы

Лимит: 120 запросов за 60 секунд на аккаунт. Ответы содержат X-RateLimit-Limit, X-RateLimit-Remaining и X-RateLimit-Reset.
После 429 используйте Retry-After. Для 5xx применяйте exponential backoff с jitter.
Новый логический заказ получает новый Idempotency-Key длиной 8-128 символов. Сетевой повтор того же заказа использует прежний ключ и те же параметры.
Не создавайте новый заказ после таймаута, пока не проверили прежний по его ID или идемпотентному повтору.

SDK examples

Примеры интеграции

Node.js

const response = await fetch("https://tglift.ru/api/v1/orders", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TGLIFT_API_KEY,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ service: "631", link, quantity: 1000 })
});
const data = await response.json();
if (!response.ok) throw new Error(`${data.code}: ${data.error}`);

Python

import os, uuid, requests

response = requests.post(
    "https://tglift.ru/api/v1/orders",
    headers={
        "X-API-Key": os.environ["TGLIFT_API_KEY"],
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={"service": "631", "link": link, "quantity": 1000},
    timeout=30,
)
response.raise_for_status()
print(response.json())

PHP

$payload = json_encode([
  "service" => "631",
  "link" => $link,
  "quantity" => 1000
]);
$ch = curl_init("https://tglift.ru/api/v1/orders");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "X-API-Key: " . getenv("TGLIFT_API_KEY"),
    "Idempotency-Key: " . bin2hex(random_bytes(16)),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => $payload,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_TIMEOUT => 30
]);
echo curl_exec($ch);

Совместимость

Legacy action API

Существующие интеграции могут продолжать отправлять POST /api/v1 с полем action: services, balance, orders, add, status, cancel или refill. Для новых интеграций используйте REST-маршруты выше. Изменяющие действия в legacy-режиме также разрешены только через POST.