API лицензий для разработчиков

Если ваш продукт продаётся с лицензионными ключами, при старте проверяйте ключ через эти эндпоинты. Ответ содержит подпись HMAC-SHA256, которую можно проверить тем же ключом.

Эндпоинты

МетодАдресНазначение
POSThttps://www.cifora.ru/api/license/activateАктивация ключа на установке
POSThttps://www.cifora.ru/api/license/verifyПериодическая проверка ключа

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

Тело: JSON или application/x-www-form-urlencoded.

ПолеОбязательноОписание
keyдаЛицензионный ключ вида XXXXX-XXXXX-XXXXX-XXXXX
site_idдаID установки / сайта / сервера, указанный при покупке
domainтолько для типа «Сайт»Домен без схемы и пути, например example.ru

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

curl -X POST https://www.cifora.ru/api/license/verify \
  -H "Content-Type: application/json" \
  -d '{"key":"ABCDE-FGHJK-LMNPQ-RSTUV","site_id":"A1B2C3D4","domain":"example.ru"}'

PHP

$payload = [
    'key' => $licenseKey,
    'site_id' => $siteId,
    'domain' => $domain,
];
$ch = curl_init('https://www.cifora.ru/api/license/verify');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($payload),
    CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 10,
]);
$response = json_decode((string) curl_exec($ch), true);

if (!empty($response['valid'])) {
    $expected = hash_hmac('sha256', json_encode(array_diff_key($response, ['signature' => 1]), JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES), $licenseKey);
    if (hash_equals($expected, (string) $response['signature'])) {
        // лицензия подтверждена
    }
}

Ответ

{
  "ok": true,
  "valid": true,
  "product": "plugin-slug",
  "kind": "site",
  "status": "active",
  "domain": "example.ru",
  "site_id": "A1B2C3D4",
  "issued_at": "2026-11-16 21:00:00",
  "expires_at": null,
  "checked_at": "2026-11-16 21:10:00",
  "signature": "…"
}

При ошибке: ok=false, valid=false и код в error: key_required, key_not_found, domain_mismatch, site_mismatch, expired, rate_limited.

Лимит: 120 запросов в минуту с одного IP. Ответы не кэшируются. Подпись считается по JSON без поля signature.

Типы лицензий

ТипЧто указывает покупатель
Сайт (site) домен и ID сайта
Приложение (app) ID установки
Бот (bot) ID бота
Игровой сервер (game) ID сервера
Плагин (plugin) ID установки
Другое (other) Идентификатор

Как это работает

  1. Покупатель приобретает лицензию в карточке товара: указывает ID и, для сайтов, домен.
  2. Ключ приходит на e-mail и хранится в разделе «Лицензии».
  3. Ваш продукт отправляет ключ и идентификаторы на /api/license/activate, затем периодически — на /api/license/verify.
  4. При смене домена или ID продавец перевыпускает ключ (не чаще раза в 30 дней) — старый ключ перестаёт работать.

Версия и совместимость

Текущая версия API — v1 (пути /api/license/*). Обратно совместимые изменения (новые поля в ответе) возможны без смены версии; несовместимые — только через новый префикс /api/v2/ с периодом поддержки старой версии не менее 6 месяцев.

Машиночитаемая спецификация: OpenAPI 3.0 (JSON). Её можно импортировать в Postman, Insomnia или Swagger UI.

Безопасность и хранение ключа

  • Ключ — секрет. Храните его только на сервере продукта, не в JS, мобильном клиенте и не в публичном репозитории.
  • Всегда проверяйте valid и подпись signature перед разблокировкой функций. Подпись — HMAC-SHA256 по JSON без поля signature, ключ подписи — сам лицензионный ключ.
  • Используйте HTTPS: по HTTP ответ можно подменить, и подпись не спасёт, если её не проверять.
  • На нашей стороне ключи хранятся в зашифрованном виде.
  • Не логируйте ключ в открытых логах и не показывайте его в интерфейсе продукта.

Кэширование и офлайн

Рекомендуемая схема: проверять ключ при старте и затем раз в 24 часа. Ответ можно кэшировать локально до 24 часов.

При недоступности API (таймаут, 5xx) используйте «мягкую» деградацию: разрешите работу ещё 3–7 дней с последнего успешного ответа, затем блокируйте. Жёсткая блокировка при каждом сетевом сбое приведёт к отказам у клиентов.

Ответы API не кэшируются на нашей стороне, каждый запрос учитывается в лимите.

Site ID и идентификаторы

site_id — 3–64 символа: латиница, цифры, точка, дефис, двоеточие, подчёркивание. Генерируйте его на стороне продукта при установке (например, случайные 16 hex-символов) и храните в конфигурации. Не используйте серийные номера, MAC-адреса и другие персональные данные.

Для типа «Сайт» дополнительно передаётся домен без схемы и пути. Для остальных типов домен не нужен и игнорируется.

Перенос, деактивация, перевыпуск

Отдельного эндпоинта деактивации нет: ключ не «занимает» установку, а привязан к паре домен/ID. При переносе на новый домен или сервер покупатель запрашивает перевыпуск у продавца — старый ключ сразу перестаёт работать, новый приходит на e-mail. Перевыпуск доступен не чаще одного раза в 30 дней (администрация площадки может перевыпустить без ограничений).

Лимиты

120 запросов в минуту с одного IP. В ответах есть заголовки X-RateLimit-Limit и X-RateLimit-Window; при превышении — HTTP 429 и Retry-After: 60.

Песочница и тестовый ключ

Отдельного sandbox-режима нет. Для интеграции можно выпустить тестовый товар с минимальной ценой лицензии и купить его вторым аккаунтом — ключ будет вести себя как обычный. Тестовые лицензии не отличаются от обычных, поэтому не публикуйте их.

Примеры на других языках

Python

import json, urllib.request

payload = json.dumps({"key": key, "site_id": site_id, "domain": domain}).encode()
req = urllib.request.Request(
    base_url + "/api/license/verify",
    data=payload,
    headers={"Content-Type": "application/json"},
)
with urllib.request.urlopen(req, timeout=10) as resp:
    data = json.load(resp)

if data.get("valid"):
    signature = data.pop("signature", "")
    # проверьте HMAC-SHA256 по json.dumps(data) с ключом key
    unlocked = True

Node.js

const res = await fetch(`${baseUrl}/api/license/verify`, {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({key, site_id: siteId, domain}),
});
const data = await res.json();
if (data.valid) {
  // проверьте data.signature через crypto.createHmac('sha256', key)
  unlock();
}

Частые ошибки

КодПричинаЧто делать
key_requiredПустой ключПередайте key
key_not_foundКлюч не существует или перевыпущенПроверьте ключ, запросите новый у продавца
domain_mismatchДомен не совпадает с привязкойПередайте правильный домен или запросите перевыпуск
site_mismatchID не совпадаетПроверьте site_id
expiredИстёк срок лицензииПродлите или купите новую
rate_limitedБольше 120 запросов в минутуПовторите после Retry-After