Сократитель.рф

 На главную

API Документация

REST API для интеграции сервиса сокращения ссылок в ваши приложения

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

API Сократитель.рф позволяет программно создавать короткие ссылки, управлять ими и получать статистику переходов.

Базовый URL

https://api.сократитель.рф/v1

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

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

API ключ передается в заголовке Authorization:

Authorization: Bearer YOUR_API_KEY

💡 Важно

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

📎 Создание короткой ссылки

POST /links

Параметры запроса

Параметр Тип Обязательный Описание
url string Да Оригинальная ссылка для сокращения
alias string Нет Кастомный алиас для короткой ссылки
title string Нет Название ссылки для удобства
expires_at string Нет Дата истечения (ISO 8601)

Пример запроса (cURL)

curl -X POST https://api.сократитель.рф/v1/links \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/very/long/url",
    "alias": "my-link",
    "title": "Моя ссылка"
  }'

Пример запроса (Python)

import requests

api_key = "YOUR_API_KEY"
url = "https://api.сократитель.рф/v1/links"

headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

data = {
    "url": "https://example.com/very/long/url",
    "alias": "my-link",
    "title": "Моя ссылка"
}

response = requests.post(url, json=data, headers=headers)
result = response.json()

print(f"Короткая ссылка: {result['short_url']}")

Пример запроса (JavaScript)

const apiKey = "YOUR_API_KEY";
const url = "https://api.сократитель.рф/v1/links";

const data = {
  url: "https://example.com/very/long/url",
  alias: "my-link",
  title: "Моя ссылка"
};

fetch(url, {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(result => {
    console.log("Короткая ссылка:", result.short_url);
  });

Пример ответа

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://сократитель.рф/my-link",
    "original_url": "https://example.com/very/long/url",
    "title": "Моя ссылка",
    "clicks": 0,
    "created_at": "2025-01-28T10:30:00Z"
  }
}

📊 Получение статистики

GET /links/{id}/stats

Получить детальную статистику по конкретной ссылке.

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

curl -X GET https://api.сократитель.рф/v1/links/abc123/stats \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа

{
  "success": true,
  "data": {
    "id": "abc123",
    "short_url": "https://сократитель.рф/my-link",
    "clicks": 1523,
    "unique_clicks": 892,
    "countries": {
      "RU": 45.2,
      "US": 23.1,
      "DE": 12.5
    },
    "referrers": {
      "direct": 38.5,
      "google.com": 25.3,
      "facebook.com": 15.2
    },
    "devices": {
      "mobile": 62.3,
      "desktop": 32.1,
      "tablet": 5.6
    }
  }
}

📋 Список ссылок

GET /links

Получить список всех ваших ссылок с пагинацией.

Query параметры

Параметр Тип По умолчанию Описание
page integer 1 Номер страницы
per_page integer 50 Количество на странице (макс. 100)
sort string created_at Сортировка: created_at, clicks, title

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

curl -X GET "https://api.сократитель.рф/v1/links?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

🗑️ Удаление ссылки

DELETE /links/{id}

Удалить короткую ссылку. После удаления она станет недоступна.

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

curl -X DELETE https://api.сократитель.рф/v1/links/abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Пример ответа

{
  "success": true,
  "message": "Ссылка успешно удалена"
}

⚡ Лимиты и ограничения

При превышении лимита API вернет код 429 (Too Many Requests).

Заголовки ответа

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85
X-RateLimit-Reset: 1643385600

❌ Коды ошибок

Код Описание
400 Bad Request - неверный формат запроса
401 Unauthorized - неверный или отсутствующий API ключ
404 Not Found - ссылка не найдена
409 Conflict - алиас уже занят
429 Too Many Requests - превышен лимит запросов
500 Internal Server Error - ошибка сервера

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

{
  "success": false,
  "error": {
    "code": "INVALID_URL",
    "message": "Указан неверный формат URL"
  }
}

💬 Поддержка

Если у вас возникли вопросы по работе с API, свяжитесь с нами: