КорочеКороче
Личный кабинет

Разработчикам

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

REST API для создания коротких ссылок и получения статистики. Аутентификация через API-ключ — получите его в настройках организации.

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

Все запросы к API требуют API-ключа. Передавайте его в заголовке Authorization в формате Bearer krc_.... Ключ привязан к организации — все операции выполняются от её имени.

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

  1. 1. Откройте Настройки → вкладка «API-ключи»
  2. 2. Нажмите «Создать ключ», укажите название
  3. 3. Скопируйте ключ сразу — он показывается только один раз
bash
# Проверка ключа — создать тестовую ссылку
curl -X POST https://koroche.site/api/public/v1/links \
  -H "Authorization: Bearer krc_aBcDeFgHiJkL..." \
  -H "Content-Type: application/json" \
  -d '{"destinationUrl": "https://example.com"}'

# Все запросы используют один и тот же заголовок:
# -H "Authorization: Bearer <ваш-ключ>"

Лимиты запросов

Запросы ограничены по IP-адресу. При превышении лимита сервер возвращает 429 Too Many Requests с заголовком Retry-After: 1. Повторите запрос через 1 секунду.

ЛимитЗначение
Запросов в секунду (на IP)100

Каждый ответ содержит заголовки для отслеживания лимита:

ЗаголовокОписание
X-RateLimit-LimitМаксимум запросов в секунду
X-RateLimit-RemainingОставшиеся запросы в текущем окне
X-RateLimit-WindowДлина окна (всегда 1s)
Retry-AfterСекунды до сброса лимита (только при 429)

Вебхуки

Вебхуки позволяют получать уведомления о событиях в реальном времени — на ваш сервер. Подписки настраиваются в Настройках → «Вебхуки». Каждый запрос содержит HMAC-SHA256 подпись для верификации подлинности.

События

СобытиеКогда срабатывает
link.createdСоздана новая ссылка (через UI или API)
link.deletedСсылка удалена

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

Каждый запрос содержит заголовок X-Koroche-Signature: sha256=<hex>. Вычислите HMAC-SHA256 от тела запроса, используя secret из настроек подписки, и сравните с полученным значением. Также приходит заголовок X-Koroche-Event с именем события.

python
import hmac, hashlib

def verify(secret: str, body: bytes, signature_header: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)
javascript
const crypto = require("crypto");

function verify(secret, rawBody, signatureHeader) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Формат payload

Все события имеют одинаковую обёртку. Поле data содержит объект события.

json
// link.created
{
  "event": "link.created",
  "timestamp": 1749816000000,
  "data": {
    "id": "018f4a2b-1c3d-7e8f-9a0b-c1d2e3f4a5b6",
    "slug": "summer-sale",
    "shortUrl": "https://koroche.site/summer-sale",
    "destinationUrl": "https://example.com/landing-page",
    "title": "Летняя распродажа",
    "clickCount": 0,
    "createdAt": "2026-06-13T12:00:00"
  }
}

// link.deleted
{
  "event": "link.deleted",
  "timestamp": 1749816000000,
  "data": {
    "id": "018f4a2b-1c3d-7e8f-9a0b-c1d2e3f4a5b6",
    "slug": "summer-sale"
  }
}

Повторные попытки

Если ваш сервер вернул не 2xx, доставка повторяется с экспоненциальной задержкой: 1 мин → 5 мин → 15 мин → 60 мин. После 5 неудачных попыток доставка помечается как FAILED. Ваш эндпоинт должен отвечать в течение 10 секунд.

Коды ошибок

КодПричина
400Неверный формат запроса — проверьте обязательные поля и типы данных
401API-ключ отсутствует, неверен или отозван
403Недостаточно прав — ключ не имеет доступа к этому ресурсу
404Ресурс не найден
409Конфликт — например, слаг уже занят
422Ошибка валидации — поле не прошло проверку (см. поле error в ответе)
429Превышен лимит запросов — повторите через минуту
500Внутренняя ошибка сервера

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

json
{
  "error": "Слаг 'summer-sale' уже занят",
  "status": 409
}