SDK

Для удобной интеграции с API доступны официальные SDK на трёх языках.

TypeScript / JavaScript

Полнофункциональный клиент с поддержкой TypeScript, автодополнением и типизацией всех ответов.

Установка:

npm install @tgio-analytics/sdk

Быстрый старт:

import { TgioClient } from '@tgio-analytics/sdk';

const client = new TgioClient({
  token: 'tgio_sk_ваш_токен',
});

// Создать короткую ссылку
const link = await client.links.create({
  url: 'https://example.com/product/123',
  title: 'Продвижение товара',
  utm_source: 'telegram',
});

console.log(link.trackingUrl); // https://tgio.app/abc123

// Статистика
const stats = await client.links.getStats(link.id, '30d');
console.log(`Клики: ${stats.totalClicks}, Уникальные: ${stats.uniqueClicks}`);

Совместимость: Node.js ≥ 18, все современные браузеры, Bun, Deno.

• npm
• GitHub

PHP

SDK для PHP 7.4+ без внешних зависимостей (только ext-curl и ext-json). PSR-4 автозагрузка, подробные PHPDoc-комментарии.

Установка:

composer require tgio/sdk

Быстрый старт:

use Tgio\Sdk\TgioClient;

$client = new TgioClient('tgio_sk_ваш_токен');

// Создать ссылку
$link = $client->links->create(['url' => 'https://example.com']);
echo $link['trackingUrl'];

// Получить статистику
$stats = $client->links->getStats($link['id'], '30d');
echo "Клики: {$stats['totalClicks']}";

Python

SDK для Python 3.8+ на базе httpx.

Установка:

pip install tgio-sdk

Быстрый старт:

from tgio_sdk import TgioClient

client = TgioClient(token="tgio_sk_ваш_токен")

# Создать ссылку
link = client.links.create(url="https://example.com", title="Моя ссылка")
print(link["trackingUrl"])

# Статистика
stats = client.links.get_stats(link["id"], period="30d")
print(f"Клики: {stats['totalClicks']}")

Доступные модули

Все SDK имеют одинаковый набор модулей:

Модуль	Описание
auth	Аутентификация через Telegram
links	Создание, редактирование ссылок + аналитика
pixels	Пиксели отслеживания + аналитика
channels	Telegram-каналы, подписчики, посты, бенчмарки
tags	Организация ссылок и пикселей по тегам
tokens	Управление API-токенами
account	Подписка, тарифы, настройки
domains	Кастомные домены для коротких ссылок
tracking	Мониторинг ключевых слов в Telegram
secure	Защищённый обмен файлами
catalog	Каталог публичных каналов

Обработка ошибок

Все SDK выбрасывают типизированное исключение при HTTP-ошибках:

TypeScript

import { TgioApiError } from '@tgio-analytics/sdk';

try {
  await client.links.create({ url: 'invalid' });
} catch (err) {
  if (err instanceof TgioApiError) {
    console.error(`HTTP ${err.status}: ${err.message}`);
  }
}

PHP

try {
    $client->links->create(['url' => 'invalid']);
} catch (\Tgio\Sdk\TgioApiError $e) {
    echo "HTTP {$e->getStatus()}: {$e->getMessage()}";
}

Python

from tgio_sdk import TgioApiError

try:
    client.links.create(url="invalid")
except TgioApiError as e:
    print(f"HTTP {e.status}: {e.message}")

Получение API-токена

1. Откройте @tgio_app_bot или веб-дашборд
2. Перейдите в Настройки → API-токены
3. Создайте токен с нужными правами доступа (scope)
4. Используйте токен в формате tgio_sk_...

Подробнее: API-токены, Аутентификация.