API Reference v1.0

REST API для интеграции GID Bot с вашими системами

Обзор

GID Bot API предоставляет программный доступ к функциям управления каналами, публикации контента, аналитике и AI-функциям.

Base URL

URL 
https://api.gid.bot/v1

Формат данных

API принимает и возвращает данные в формате JSON. Все запросы должны содержать заголовок:

Header 
Content-Type: application/json

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

Все запросы к API должны быть аутентифицированы с помощью API-ключа.

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

API-ключ можно получить в настройках бота командой /api или в личном кабинете.

Использование

Передавайте ключ в заголовке Authorization:

Header 
Authorization: Bearer YOUR_API_KEY

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

cURL 
curl -X GET "https://api.gid.bot/v1/channels" \
  -H "Authorization: Bearer gid_sk_live_abc123..." \
  -H "Content-Type: application/json"
⚠️

Безопасность

Никогда не передавайте API-ключ в клиентском коде или публичных репозиториях

Rate Limits

API имеет ограничения на количество запросов для обеспечения стабильности сервиса.

Тариф Запросов/минуту Запросов/день
Free 60 1,000
Starter 120 10,000
Pro 300 100,000
Enterprise 1,000+ Unlimited

Заголовки с информацией о лимитах:

Response Headers 
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Reset: 1701936000

Ошибки

API использует стандартные HTTP-коды состояния и возвращает детали ошибки в JSON.

Код Значение Описание
200 OK Успешный запрос
400 Bad Request Некорректные параметры
401 Unauthorized Неверный API-ключ
403 Forbidden Нет доступа к ресурсу
404 Not Found Ресурс не найден
429 Too Many Requests Превышен лимит запросов
500 Server Error Внутренняя ошибка сервера

Формат ошибки

JSON 
{
  "error": {
    "code": "invalid_request",
    "message": "The channel_id parameter is required",
    "details": {
      "field": "channel_id",
      "reason": "missing"
    }
  }
}

Channels

GET /channels

Получить список всех каналов пользователя

Query Parameters

Параметр Тип Описание
limit integer Количество записей (1-100, default: 20)
offset integer Смещение для пагинации
Response 200
JSON 
{
  "data": [
    {
      "id": "ch_123456",
      "telegram_id": -1001234567890,
      "title": "My Channel",
      "username": "mychannel",
      "subscribers": 15420,
      "settings": {
        "moderation_enabled": true,
        "ai_enabled": true
      },
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 5,
    "limit": 20,
    "offset": 0
  }
}

Posts

POST /posts

Создать новую публикацию или запланировать отложенный пост

Body Parameters

Параметр Тип Описание
channel_id required string ID канала
text required string Текст публикации (до 4096 символов)
media array Массив URL медиафайлов
schedule_at datetime Время публикации (ISO 8601)
buttons array Inline-кнопки

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

cURL 
curl -X POST "https://api.gid.bot/v1/posts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "ch_123456",
    "text": "Hello, world! 🚀",
    "schedule_at": "2024-12-08T10:00:00Z",
    "buttons": [
      [{"text": "Visit", "url": "https://gid.bot"}]
    ]
  }'
Response 201
JSON 
{
  "data": {
    "id": "post_789",
    "channel_id": "ch_123456",
    "status": "scheduled",
    "schedule_at": "2024-12-08T10:00:00Z",
    "created_at": "2024-12-07T15:30:00Z"
  }
}

AI

POST /ai/generate

Генерация контента с помощью AI

Body Parameters

Параметр Тип Описание
prompt required string Промпт для генерации
model string Модель AI (gpt-4o, claude-3.5, gemini-pro)
max_tokens integer Максимальная длина ответа
temperature float Креативность (0-1)
Response 200
JSON 
{
  "data": {
    "content": "Generated content here...",
    "model": "gpt-4o",
    "tokens_used": 150,
    "finish_reason": "stop"
  }
}

Webhooks

Webhooks позволяют получать уведомления о событиях в реальном времени.

Настройка

Укажите URL вашего сервера для получения событий:

cURL 
curl -X POST "https://api.gid.bot/v1/webhooks" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["post.published", "channel.updated", "moderation.action"]
  }'

События

Событие Описание
post.published Пост опубликован
post.scheduled Пост запланирован
channel.updated Настройки канала изменены
moderation.action Выполнено действие модерации
subscriber.joined Новый подписчик
💡

Верификация

Каждый webhook содержит подпись в заголовке X-Signature для проверки подлинности