API maxln

API для коротких ссылок и статистики

API помогает подключить maxln к вашему Telegram-боту, CRM, админке или собственному сервису. Через него можно создавать короткие ссылки для МАКС, Telegram, VK, YouTube и других поддерживаемых сервисов, получать статистику переходов и управлять адресами без ручной работы в личном кабинете. Доступ ограничен только данными вашего аккаунта.

Создание ссылок

До 30 ссылок в день на аккаунт по умолчанию. Администратор может изменить лимит конкретного ключа.

Статистика

Сегодня, вчера, 7, 30 и 90 дней, уникальные переходы, устройства, браузеры, источники и последние переходы.

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

Для проверки ключа хранится хэш, а для повторного копирования — зашифрованная копия токена. IP для антиспама учитывается как хэш.

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

  1. Войдите в личный кабинет.
  2. Нажмите кнопку API рядом со сменой пароля.
  3. Нажмите Выпустить ключ и скопируйте токен.
  4. Если есть риск, что токен стал доступен не только вам или вашей команде, нажмите Перевыпустить. Старый токен перестанет работать.
Токен можно повторно скопировать в личном кабинете. Храните его в закрытом месте: в переменных окружения, секретах хостинга или настройках вашего сервера. Не размещайте ключ в открытом коде сайта или публичных репозиториях.

Авторизация

Передавайте ключ в заголовке Authorization или X-API-Key.

Authorization: Bearer mxln_live_ваш_ключ
X-API-Key: mxln_live_ваш_ключ

Методы API

Метод Адрес Что делает
POST/api/v1/linksСоздаёт короткую ссылку для МАКС или выбранного поддерживаемого сервиса.
GET/api/servicesБез API-ключа возвращает актуальный список сервисов, допустимых доменов, примеров и доступности каталога.
GET/api/v1/linksВозвращает ваши ссылки от новых к старым и базовые счётчики.
GET/api/v1/links/{code}Возвращает одну вашу ссылку.
PATCH/api/v1/links/{code}Меняет исходный адрес и описание, если ссылка не опубликована в каталоге.
DELETE/api/v1/links/{code}Удаляет вашу ссылку, публикацию в каталоге и статистику по ней.
GET/api/v1/links/{code}/stats?range=todayВозвращает расширенную статистику по вашей ссылке.
GET/api/v1/account/limitsПоказывает лимиты аккаунта и использование API за сегодня.

Создать ссылку

Для создания ссылки передайте обязательный параметр url. Необязательный service выбирает сервис, custom_slug задаёт собственный адрес вида maxln.ru/myvideo, а description сохраняет описание ссылки.

custom_slug должен содержать от 4 до 20 английских букв или цифр. Регистр сохраняется, адрес должен быть свободен и не совпадать с системными разделами сайта.

Параметр service может принимать значения: max (по умолчанию), telegram, vk, ok, youtube, rutube, vk-video, dzen, tiktok, whatsapp, viber, discord, twitch, yandex-disk, google-drive. Адрес url должен соответствовать доменам выбранного сервиса. Актуальный машинно-читаемый список всегда доступен в GET /api/services.

curl -X POST https://maxln.ru/api/v1/links \
  -H "Authorization: Bearer mxln_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://youtube.com/watch?v=dQw4w9WgXcQ","custom_slug":"myvideo","service":"youtube"}'

Ответ:

{
  "slug": "myvideo",
  "short_url": "https://maxln.ru/myvideo",
  "long_url": "https://youtube.com/watch?v=dQw4w9WgXcQ",
  "service": "youtube"
}

Получить статистику

Параметр range принимает значения: today, yesterday, 7d, 30d, 90d.

curl "https://maxln.ru/api/v1/links/myvideo/stats?range=7d" \
  -H "Authorization: Bearer mxln_live_ваш_ключ"

В ответе есть общие цифры, графики по часам и дням, источники, устройства, браузеры, операционные системы и последние переходы.

Управление ссылками

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

# Получить список
curl "https://maxln.ru/api/v1/links" \
  -H "Authorization: Bearer mxln_live_ваш_ключ"

# Изменить адрес, сервис и описание
curl -X PATCH "https://maxln.ru/api/v1/links/myvideo" \
  -H "Authorization: Bearer mxln_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://vk.ru/team","service":"vk","description":"Страница VK"}'

# Удалить ссылку и её статистику
curl -X DELETE "https://maxln.ru/api/v1/links/myvideo" \
  -H "Authorization: Bearer mxln_live_ваш_ключ"

# Проверить лимиты
curl "https://maxln.ru/api/v1/account/limits" \
  -H "Authorization: Bearer mxln_live_ваш_ключ"
Ссылки внешних сервисов можно создавать с собственным коротким адресом и анализировать так же, как остальные. Возможность публикации в каталоге определяется полем catalog_allowed из GET /api/services. Сейчас каталог предназначен только для ссылок МАКС; API не публикует ссылки в каталоге.

Пример на JavaScript

const token = process.env.MAXLN_API_KEY;
 
const response = await fetch('https://maxln.ru/api/v1/links', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://youtube.com/watch?v=dQw4w9WgXcQ',
    custom_slug: 'myvideo',
    service: 'youtube'
  })
});
 
const link = await response.json();
console.log(link.short_url);

Лимиты и ошибки

По умолчанию аккаунт может создавать до 30 ссылок в день через API. Один ключ может делать до 1000 API-запросов в день и до 300 запросов статистики в день. Дополнительно действует минутная защита от резких всплесков и дневные лимиты по IP, чтобы один адрес не мог перегружать сервис пачкой аккаунтов.

Правила безопасности