MSHRT - API

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

ОБЗОР

MSHRT API — REST-интерфейс для создания и управления короткими ссылками. Все запросы и ответы используют формат JSON. Все защищённые эндпоинты требуют Bearer-токен в заголовке Authorization.

Все временные метки возвращаются в формате ISO 8601 (UTC). Для нумерации используются целые числа.

Base URL

https://mshrt.com/api/v1

# Все эндпоинты возвращают JSON
Content-Type: application/json

# Защищённые эндпоинты требуют:
Authorization: Bearer <access_token>

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

АУТЕНТИФИКАЦИЯ

API использует JWT Bearer-токены. После логина вы получаете два токена: access_token (живёт 24ч) и refresh_token (7 дней). Передавайте access_token в каждом запросе.

Header

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Обновление токена: когда access_token истекает, используйте POST /auth/refresh с refresh_token для получения новой пары. Хранить refresh_token в httpOnly Cookie — наилучшая практика.

Ошибки

КОДЫ ОТВЕТОВ

Код	Значение	Когда возникает
200	OK	Запрос выполнен успешно
201	Created	Ресурс создан (register, create link)
400	Bad Request	Невалидные данные, неверный URL
401	Unauthorized	Нет токена, токен истёк или неверный
403	Forbidden	Нет доступа к чужому ресурсу
404	Not Found	Ресурс не найден
409	Conflict	Email или алиас уже заняты
500	Server Error	Внутренняя ошибка сервера

Error Response

{
  "error": "email already registered"
}

Лимиты

RATE LIMITING

Лимиты применяются по IP-адресу. Заголовки ответа содержат информацию об оставшихся запросах.

Тариф	Запросов / час	Ссылок / месяц
Free	100	50
Pro	1 000	∞
Business	10 000	∞

429 Too Many Requests — при превышении лимита. Заголовок Retry-After укажет время ожидания в секундах.

Авторизация

AUTH

POST /auth/register Регистрация нового пользователя

Request Body

Поле	Тип	Обязательность	Описание
`name`	string	required	Имя пользователя (2–100 символов)
`email`	string	required	Email-адрес
`password`	string	required	Пароль, минимум 6 символов

curl

curl -X POST https://mshrt.com/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Петров",
    "email": "user@example.com",
    "password": "secret123"
  }'

Response 201

{
  "access_token":  "eyJhbGci...",
  "refresh_token": "a3f9c2...",
  "user": {
    "id":         1,
    "name":       "Иван Петров",
    "email":      "user@example.com",
    "plan":       "free",
    "created_at": "2025-01-15T10:00:00Z"
  }
}

POST /auth/login Вход в аккаунт

curl

curl -X POST https://mshrt.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"secret123"}'

POST /auth/refresh Обновить токены

Body

{ "refresh_token": "a3f9c2..." }

POST /auth/logout Выход (инвалидация refresh токенов) 🔒 AUTH

Передайте Bearer токен в заголовке. Тело запроса не нужно.

Пользователь

USER

GET /user/me Профиль текущего пользователя 🔒 AUTH

Response 200

{
  "id": 1, "name": "Иван",
  "email": "user@example.com",
  "plan": "free",
  "created_at": "2025-01-15T10:00:00Z"
}

PUT /user/password Сменить пароль 🔒 AUTH

Поле	Тип
`old_password`	string	required
`new_password`	string	required, min 6

DELETE /user Удалить аккаунт 🔒 AUTH

Необратимо. Удаляет пользователя и все его ссылки. Подтвердите действие на стороне клиента перед вызовом.

Ссылки

LINKS

POST /links Создать короткую ссылку 🔒 AUTH

Поле	Тип		Описание
`url`	string	required	Исходный URL (должен начинаться с http:// или https://)
`alias`	string	optional	Кастомный алиас. Если не указан — генерируется автоматически

Response 201

{
  "id":         42,
  "url":        "https://very-long-url.ru/path",
  "code":       "abc123",
  "short_url":  "https://mshrt.com/r/abc123",
  "clicks":     0,
  "created_at": "2025-01-15T12:00:00Z"
}

GET /links Список ссылок (пагинация) 🔒 AUTH

Query	Default	Значения
`page`	1	Номер страницы
`limit`	20	Размер страницы (макс. 100)
`search`	—	Поиск по URL или коду
`sort`	date	`date` · `clicks` · `alpha`

Response 200

{
  "data":  [/* LinkResponse[] */],
  "total": 47,
  "page":  1,
  "limit": 20
}

GET /links/stats Сводная статистика 🔒 AUTH

Response 200

{
  "total_links":  12,
  "total_clicks": 340,
  "avg_clicks":   28.3,
  "max_clicks":   120,
  "chart": [
    { "date": "2025-01-15", "label": "Wed", "clicks": 18 }
  ],
  "top_links": [/* LinkResponse[] */]
}

PUT /links/:id Обновить ссылку 🔒 AUTH

Поле	Тип
`url`	string	required
`code`	string	required

DELETE /links/:id Удалить ссылку 🔒 AUTH

Response 200

{ "message": "deleted" }

Редирект

REDIRECT

GET /r/:code Редирект на исходный URL

Возвращает 301 Moved Permanently. Клик фиксируется асинхронно — IP, User-Agent, Referer. Токен не нужен, эндпоинт публичный.

Example

GET /r/abc123

← 301 Moved Permanently
Location: https://original-very-long-url.ru/some/path

Интеграции

API ДЛЯ СОКРАЩЕНИЯ ССЫЛОК

MSHRT API подходит для сценариев, где нужно автоматически создавать короткие ссылки из CRM, CMS, рекламных кабинетов, внутренних админок и SaaS-продуктов. Вместо ручной работы команда получает единый REST API коротких ссылок с JWT-аутентификацией и понятной структурой ответов.

Через API можно регистрировать пользователей, выпускать короткие URL, получать список ссылок, редактировать алиасы, удалять записи и отслеживать статистику переходов. Это закрывает и продуктовые задачи, и SEO-задачи, когда нужен предсказуемый домен редиректа, контроль кликов и прозрачная аналитика по каждому short link.

Сценарий	Что дает API
Маркетинг и paid traffic	Быстрое создание коротких ссылок под кампании, UTM-метки и отдельные креативы.
Продукт и support	Генерация short URL из backoffice, писем, чат-ботов и dashboard без ручной рутины.
Партнерские сети	Контроль редиректов, алиасов и кликов по источникам в едином API.

Практический результат: один API для сокращения ссылок, брендированных URL и статистики переходов, который можно встроить в существующую инфраструктуру без отдельного сервиса-посредника.

APIDOCS

API
DOCS