API лицензий для разработчиков
Если ваш продукт продаётся с лицензионными ключами, при старте проверяйте ключ через эти эндпоинты. Ответ содержит подпись HMAC-SHA256, которую можно проверить тем же ключом.
Эндпоинты
| Метод | Адрес | Назначение |
|---|---|---|
| POST | https://www.cifora.ru/api/license/activate | Активация ключа на установке |
| POST | https://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) | Идентификатор |
Как это работает
- Покупатель приобретает лицензию в карточке товара: указывает ID и, для сайтов, домен.
- Ключ приходит на e-mail и хранится в разделе «Лицензии».
- Ваш продукт отправляет ключ и идентификаторы на
/api/license/activate, затем периодически — на/api/license/verify. - При смене домена или 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_mismatch | ID не совпадает | Проверьте site_id |
expired | Истёк срок лицензии | Продлите или купите новую |
rate_limited | Больше 120 запросов в минуту | Повторите после Retry-After |
Плагины Minecraft
Моды GTA V
Плагины Rust
Counter Strike
Моды DayZ
Прочее