External API

Rekla External API позволяет внешним партнёрам создавать публикации в Telegram-каналах пользователей Rekla, проверять доступ и отслеживать статусы. Base URL: https://api.rek.la

Подключение

Запросите доступ

Напишите в @rekla_support:

«Хочу подключиться как партнёр к Rekla External API»

Вам выдадут:

Partner ID — для заголовка X-Partner-Id
Webhook Secret — для проверки подписи вебхуков
Start-команда — для создания API-ключей пользователями

Получите API-ключ пользователя

Пользователь вводит команду в боте @rekla:

/start createapikey-<partner_name>

Бот создаёт ключ и показывает его пользователю. Одновременно Rekla отправит вебхук api_key.created на ваш сервер с данными ключа.

Делайте запросы

curl -H "X-API-Key: rekla_api:xxx" \
     -H "X-Partner-Id: your_partner_id" \
     https://api.rek.la/external-api/me

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

Заголовок	Описание
`X-API-Key`	API-ключ пользователя Rekla
`X-Partner-Id`	Ваш идентификатор партнёра

API-ключ показывается пользователю один раз. Повторно получить его невозможно.

Эндпоинты

GET /external-api/me

Получить информацию о владельце API-ключа.

curl -H "X-API-Key: rekla_api:xxx" \
     -H "X-Partner-Id: your_partner_id" \
     https://api.rek.la/external-api/me

Ответ 200:

{
  "id": 753967249,
  "name": "Максим",
  "username": "m5286606"
}

GET /external-api/channels//can-post

Проверить, может ли пользователь публиковать в указанный канал. Проверяется два условия:

У пользователя есть права автопостинга в канале
Бот Rekla является администратором канала с правами на публикацию

curl -H "X-API-Key: rekla_api:xxx" \
     -H "X-Partner-Id: your_partner_id" \
     https://api.rek.la/external-api/channels/-1001568992973/can-post

Ответ 200:

{
  "autoposting_access": true
}

Ответ 403:

{
  "detail": "Access denied. You do not have permission in Rekla to post into this channel."
}

channel_id — это числовой Telegram ID канала (обычно начинается с -100).

POST /external-api/publications

Создать одну или несколько публикаций. Принимает массив объектов.

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-API-Key: rekla_api:xxx" \
     -H "X-Partner-Id: your_partner_id" \
     -d '[{
       "external_id": "pub-001",
       "channel_id": -1001568992973,
       "text": "Текст публикации",
       "text_len": 16,
       "media_type": "text",
       "price": 1500,
       "publish_date": "2030-03-01T12:00:00Z",
       "payment_status": "not_paid",
       "allow_comments": true
     }]' \
     https://api.rek.la/external-api/publications

Ответ 201:

{
  "publications": [
    {
      "id": 11607,
      "external_id": "pub-001"
    }
  ]
}

Поля PublicationCreateRequest

Поле	Тип	Обязательно	Описание
`external_id`	`string`	✅	Ваш внутренний ID публикации
`channel_id`	`integer`	✅	Telegram ID канала
`text`	`string`	—	Текст публикации (HTML-разметка Telegram)
`text_len`	`integer`	—	Длина текста
`media_type`	`string`	—	Тип: `text`, `photo`, `video`, `animation`, `document`, `audio`, `voice`, `video_note`, `album`, `poll`, `rich_message`
`rich_message`	`object`	—	Статья: обязательна при `media_type: rich_message`
`file_id`	`string`	—	Устаревшее внешнее поле; `file_id` другого бота использовать нельзя
`file_url`	`string`	—	HTTP(S) URL обычного медиа; Rekla сразу получит собственный `file_id`
`album`	`object`	—	Конфигурация альбома (обязательно при `media_type: album`)
`poll`	`object`	—	Конфигурация опроса (при `media_type: poll`)
`inline_buttons`	`object`	—	Инлайн-кнопки
`price`	`number`	✅	Цена публикации
`publish_date`	`string`	✅	Дата публикации (ISO 8601)
`payment_status`	`string`	—	`not_paid` (по умолчанию), `paid`, `partial_paid`, `overpaid`, `refund`, `refund_partial`
`auto_delete`	`integer`	—	Автоудаление через N минут
`with_sound_notification`	`boolean`	—	Звуковое уведомление (`false` по умолчанию)
`wp_preview`	`boolean`	—	Предпросмотр ссылок
`wp_preview_config`	`object`	—	Настройки предпросмотра: `is_disabled`, `url`, `prefer_small_media`, `show_above_text`
`allow_comments`	`boolean`	—	Разрешить комментарии (`true` по умолчанию)
`has_spoiler`	`boolean`	—	Спойлер на медиа
`protect_content`	`boolean`	—	Защита от копирования
`comment`	`string`	—	Комментарий к публикации

Правила валидации

Альбомы (media_type: album): поле album обязательно и не может быть пустым. Только последний элемент альбома может содержать caption. Поле text должно совпадать с caption последнего элемента.Обычные медиа: для одиночного медиа и каждого элемента альбома обязателен публично доступный file_url. file_id, полученный другим Telegram-ботом, бот Rekla использовать не может.Статья (media_type: rich_message): передайте точные blocks и is_rtl из message.rich_message, полученного ботом партнёра. Для каждого встроенного фото, видео, аудио, animation или voice note добавьте в media_urls соответствие file_unique_id → временный HTTP(S) URL.Rekla загрузит все медиа своим ботом прямо во время создания публикации. К моменту сохранения Статья уже содержит наши Telegram file_id; переданные URL не нужны крону и паблишеру.URL вида https://api.telegram.org/file/bot<TOKEN>/... запрещён, потому что раскрывает токен партнёрского бота. Сначала скачайте файл своим ботом и разместите его по безопасному временному URL.Дата публикации: принимается в формате ISO 8601. Таймзона автоматически удаляется (хранится как naive datetime).

Пример с фото

[{
  "external_id": "pub-photo-001",
  "channel_id": -1001568992973,
  "text": "Подпись к фото",
  "text_len": 14,
  "media_type": "photo",
  "file_url": "https://example.com/image.jpg",
  "album": null,
  "poll": null,
  "inline_buttons": {
    "inline_keyboard": [[
      {"text": "Подробнее", "url": "https://example.com"}
    ]]
  },
  "price": 2000,
  "publish_date": "2030-03-01T14:00:00Z",
  "payment_status": "paid",
  "auto_delete": 1440,
  "with_sound_notification": false,
  "wp_preview": false,
  "allow_comments": false,
  "has_spoiler": false,
  "protect_content": true,
  "wp_preview_config": null,
  "comment": "Рекламная кампания #1"
}]

Пример Статьи с фото и кнопкой

[{
  "external_id": "article-001",
  "channel_id": -1001568992973,
  "media_type": "rich_message",
  "rich_message": {
    "blocks": [
      {
        "type": "heading",
        "text": "Новая функция",
        "size": 2
      },
      {
        "type": "paragraph",
        "text": "Теперь в Rekla можно публиковать Статьи."
      },
      {
        "type": "photo",
        "photo": [{
          "file_id": "partner-bot-file-id",
          "file_unique_id": "AQAD-example-photo",
          "width": 1280,
          "height": 720
        }],
        "caption": {
          "text": "Подпись к фотографии"
        }
      }
    ],
    "is_rtl": false,
    "media_urls": {
      "AQAD-example-photo": "https://partner.example/media/article-photo.jpg"
    }
  },
  "inline_buttons": {
    "inline_keyboard": [[
      {"text": "Подробнее", "url": "https://example.com"}
    ]]
  },
  "price": 2000,
  "publish_date": "2030-03-01T14:00:00Z"
}]

inline_buttons остаётся верхнеуровневым полем. Если партнёр получил публикацию от своего бота, сюда передаётся message.reply_markup, а в rich_message — message.rich_message.

Коды ответов:

Код	Описание
`201`	Публикации созданы
`403`	Нет доступа к одному или нескольким каналам
`422`	Семантическая ошибка Статьи: отсутствует URL медиа или получен неверный тип файла
`400`	Структурная ошибка JSON/Pydantic или другая ошибка запроса

Создание атомарно: если одна публикация из массива не пройдёт валидацию, ни одна не будет создана.

POST /external-api/publications/cancel

Отменить публикацию.

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-API-Key: rekla_api:xxx" \
     -H "X-Partner-Id: your_partner_id" \
     -d '{"publication_id": 11607, "channel_id": -1001568992973}' \
     https://api.rek.la/external-api/publications/cancel

Ответ 204: пустое тело (успешная отмена).

Отменить можно только публикацию, созданную через вашего партнёра. Попытка отменить чужую публикацию вернёт 404.

POST /external-api/publications/status

Проверить статус публикации.

curl -X POST \
     -H "Content-Type: application/json" \
     -H "X-API-Key: rekla_api:xxx" \
     -H "X-Partner-Id: your_partner_id" \
     -d '{"publication_id": 11607, "channel_id": -1001568992973}' \
     https://api.rek.la/external-api/publications/status

Ответ 200:

{
  "publication_id": 11607,
  "publication_link": "https://t.me/c/1568992973/42",
  "publish_date": "2030-03-01T12:00:00",
  "auto_delete": null,
  "publish_status": "published",
  "payment_status": "not_paid",
  "delete_date": null
}

Возможные значения publish_status

Статус	Описание
`created`	Публикация создана, ожидает отправки
`published`	Опубликована в канале
`canceled`	Отменена
`deleted`	Удалена из канала
`error`	Ошибка при публикации

Вебхуки

При определённых событиях Rekla отправляет POST-запрос на ваш webhook_url.

Событие `api_key.created`

Отправляется когда пользователь создаёт API-ключ через команду /start createapikey-<partner>. Тело запроса:

{
  "user_id": 753967249,
  "raw_api_key": "rekla_api:fb27e09cd41f8a2e3dd93a..."
}

Заголовки:

Заголовок	Описание
`X-Webhook-Event`	Тип события (`api_key.created`)
`X-Webhook-Id`	Уникальный UUID события
`X-Webhook-Timestamp`	UNIX timestamp отправки
`X-Webhook-Signature`	Подпись HMAC SHA256

Проверка подписи

import hmac, hashlib

def verify_webhook(body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    expected = hmac.new(
        key=secret.encode(),
        msg=f"{timestamp}.{body.decode()}".encode(),
        digestmod=hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

const crypto = require('crypto');

function verifyWebhook(body, timestamp, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${body}`)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Контакты

Поддержка интеграций: @rekla_support Версия API: 1.0.0 | Формат: application/json

Используя API, вы принимаете условия оферты.

Начало работы

Автопостинг

Закупы

Вспомогательные функции

Лучшие практики

Справочная информация

Туториалы

Дополнительные сервисы

External API

Подключение

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

Эндпоинты

GET /external-api/me

GET /external-api/channels//can-post

POST /external-api/publications

POST /external-api/publications/cancel

POST /external-api/publications/status

Вебхуки

Событие `api_key.created`

Проверка подписи

Контакты

​Подключение

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

​Эндпоинты

​GET /external-api/me

​GET /external-api/channels//can-post

​POST /external-api/publications

​POST /external-api/publications/cancel

​POST /external-api/publications/status

​Вебхуки

​Событие api_key.created

​Проверка подписи

​Контакты

Подключение

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

Эндпоинты

GET /external-api/me

GET /external-api/channels//can-post

POST /external-api/publications

POST /external-api/publications/cancel

POST /external-api/publications/status

Вебхуки

Событие `api_key.created`

Проверка подписи

Контакты