Seed-Key API v1

Программный доступ к калькулятору Seed → Key. Доступ выдаётся на аккаунт и использует дневной лимит и срок действия подписки Seed-Key этого аккаунта. Дневной счётчик сбрасывается в 00:00 UTC.

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

Каждый запрос несёт API-ключ в заголовке — подходит любой вариант:

Authorization: Bearer mbseed_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978
X-API-Key: mbseed_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978

Ключ показывается один раз при создании. Храните его надёжно — восстановить нельзя.
Один активный ключ на аккаунт. Создание нового ключа сразу отзывает предыдущий.
Один тип ключа — он вызывает все эндпоинты. Используйте /benchmark для замера задержки без расхода квоты.
Ключ можно привязать к списку разрешённых IP-адресов. Запрос с другого адреса получит 403 ip_not_allowed.
Только HTTPS. Отправляйте Content-Type: application/json на каждом запросе — включая GET /catalog и GET /benchmark без тела; без него часть запросов отклоняется.

2. Базовый URL и эндпоинты

https://mbcare.ru/api/v1/seed/{endpoint}

Эндпоинт	Метод	Назначение	Списывает квоту
`/quota`	GET	Текущий срок доступа и расход за сутки	нет
`/catalog`	GET / POST	Каталог ЭБУ + текущая версия каталога	нет
`/calculate`	POST	Расчёт ключа по seed	да — 1 за успех
`/benchmark`	GET / POST	Замер задержки (возвращает нулевой ключ)	нет

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

Header	Значение
`X-Request-Id`	Уникальный идентификатор запроса — указывайте его в обращениях в поддержку.
`X-Seed-Quota-Limit`	Дневной лимит расчётов для аккаунта.
`X-Seed-Quota-Remaining`	Осталось расчётов до 00:00 UTC.
`X-Seed-Quota-Reset`	Unix-время следующего сброса квоты.
`Retry-After`	При `429` — сколько секунд ждать до повтора.

4. GET /quota

GEThttps://mbcare.ru/api/v1/seed/quota

curl -s https://mbcare.ru/api/v1/seed/quota \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "allowed": true,
  "code": "ok",
  "quota": {
    "dailyLimit": 200,
    "used": 4,
    "remaining": 196,
    "accessUntil": "2026-12-31T20:00:00Z",
    "resetAt": "2026-09-05T00:00:00Z"
  },
  "requestId": "req_1a2b3c4d5e6f7a8b90"
}

5. GET /catalog

GEThttps://mbcare.ru/api/v1/seed/catalog

Возвращает все поддерживаемые алгоритмы ЭБУ и хэш version всего каталога. Передайте последний известный хэш в knownVersion — при отсутствии изменений придёт {"unchanged": true} без items.

curl -s https://mbcare.ru/api/v1/seed/catalog \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

# условный запрос:
curl -s -X POST https://mbcare.ru/api/v1/seed/catalog \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"knownVersion":"<64-hex>"}'

{
  "ok": true,
  "schemaVersion": 1,
  "version": "9c1f...<64-hex>",
  "count": 4445,
  "unchanged": false,
  "items": [
    {
      "definitionId": "3f8a...<64-hex>",
      "ecuName": "IC_204",
      "accessLevel": 1,
      "seedLength": 8,
      "keyLength": 8,
      "software": "1979021500"
    }
  ],
  "requestId": "req_…"
}

Поле элемента	Значение
`definitionId`	Непрозрачный 64-hex идентификатор. Стабилен, но может отсутствовать для строк из файлового резерва — надёжнее сопоставлять по параметрам ЭБУ.
`ecuName`	Имя ЭБУ / блока управления.
`accessLevel`	Уровень доступа (целое число).
`seedLength` / `keyLength`	Длины seed и результирующего ключа в байтах.
`software`	Номер прошивки для семейств IC204/IC213/…; иначе `null`.

Чтобы снова найти алгоритм после обновления каталога, сопоставляйте локально по ecuName + accessLevel + software + seedLength + keyLength — и передавайте именно их в /calculate.

6. POST /calculate

POSThttps://mbcare.ru/api/v1/seed/calculate

Два способа указать алгоритм. Рекомендуется по параметрам ЭБУ — он не зависит от definitionId и продолжает работать после обновлений каталога.

6a. По параметрам ЭБУ

Поле	Обязательно	Описание
`ecuName`	да	1–64 печатных ASCII-символа, из `/catalog` (на сервере приводится к верхнему регистру).
`accessLevel`	да	Целое число 0–1024.
`seedLength`	да	1–512; должно совпадать с длиной `seed` в байтах.
`keyLength`	да	1–512.
`seed`	да	Hex-строка (чётной длины, ≤ 512 символов). Пробелы, `-`, `:` удаляются.
`software`	нет	1–32 цифры. Опустите, чтобы сопоставить строки без привязки к прошивке.
`catalogVersion`	нет	Версия каталога `version`, под которую собран запрос — при несовпадении `409 catalog_outdated`.

Если под параметры подходит несколько строк, возвращается основная с candidates > 1 — при неоднозначном ЭБУ обратитесь в поддержку.

curl -s -X POST https://mbcare.ru/api/v1/seed/calculate \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ecuName":"IC_204","accessLevel":1,"seedLength":8,"keyLength":8,
       "software":"1979021500","seed":"A1B2C3D4A1B2C3D4"}'

6b. По definitionId

Поле	Обязательно	Описание
`definitionId`	да	64-hex идентификатор из `/catalog` (не из одних нулей).
`seed`	да	Hex; длина в байтах должна совпадать с `seedLength` определения.
`catalogVersion`	нет	Как выше.

curl -s -X POST https://mbcare.ru/api/v1/seed/calculate \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json" \
  -d '{"definitionId":"3f8a...<64-hex>","seed":"A1B2C3D4A1B2C3D4"}'

Ответ

{
  "ok": true,
  "schemaVersion": 1,
  "catalogVersion": "9c1f...<64-hex>",
  "definitionId": "3f8a...<64-hex>",
  "ecuName": "IC_204",
  "accessLevel": 1,
  "seedLength": 8,
  "keyLength": 8,
  "software": "1979021500",
  "matchedBy": "definitionId",       // "definitionId" | "groupPrimary" | "benchmark"
  "candidates": 1,
  "key": "1122334455667788",
  "quota": { "dailyLimit": 200, "used": 5, "remaining": 195,
             "accessUntil": "2026-12-31T20:00:00Z", "resetAt": "2026-09-05T00:00:00Z" },
  "requestId": "req_…"
}

Дневной счётчик увеличивается только при успешном расчёте. key — hex в верхнем регистре.

7. GET /benchmark

GEThttps://mbcare.ru/api/v1/seed/benchmark

Выполняет реальный путь чтения из базы на расчётном сервере и возвращает нулевой ключ — можно измерить сквозную задержку без расхода квоты и без активной подписки. Доступно любому ключу.

Поле	Обязательно	Описание
`seed`	нет	Любой корректный hex; по умолчанию `A5A5A5A5A5A5A5A5`.
`keyLength`	нет	1–512; длина возвращаемого нулевого ключа.

curl -s https://mbcare.ru/api/v1/seed/benchmark \
  -H "Authorization: Bearer $MBSEED_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "matchedBy": "benchmark",
  "upstreamMs": 41.7,
  "catalogVersion": "9c1f...<64-hex>",
  "keyLength": 8,
  "key": "0000000000000000",
  "probe": { "ecuName": "IC_204", "accessLevel": 1, "seedLength": 8, "software": "1979021500" },
  "requestId": "req_…"
}

8. Ошибки

Каждая ошибка имеет вид:

{ "ok": false, "code": "invalid_seed", "error": "сообщение для человека", "requestId": "req_…" }

HTTP	code	Значение
401	`missing_api_key` / `invalid_api_key`	Нет ключа, либо ключ повреждён / неизвестен.
403	`key_revoked` / `key_disabled` / `customer_disabled`	Ключ или аккаунт неактивен.
403	`ip_not_allowed`	IP вызывающего не в списке разрешённых для ключа.
403	`access_expired` / `no_access`	Подписка закончилась / у аккаунта нет подписки Seed-Key.
403	`scope_missing`	Ключу не разрешён этот эндпоинт.
429	`daily_limit_reached`	Дневная квота исчерпана. `Retry-After` = секунды до 00:00 UTC.
429	`rate_limited`	Больше 60 запросов в минуту для этого ключа.
429	`upstream_rate_limited`	Расчётный сервис кратковременно перегружен (лимит общий для всех клиентов API). Повторите чуть позже.
400	`invalid_json` / `invalid_seed` / `invalid_definition` / `invalid_catalog_version`	Некорректные данные.
400	`invalid_ecu_name` / `invalid_access_level` / `invalid_length` / `invalid_software`	Некорректное поле параметров ЭБУ.
400	`seed_length_mismatch`	Длина seed в байтах ≠ ожидаемой алгоритмом. В ответе есть `expectedLength`.
404	`definition_not_found`	Ни один алгоритм не подходит под параметры / `definitionId`.
405	`method_not_allowed`	Неверный HTTP-метод для эндпоинта.
409	`catalog_outdated`	Перезагрузите `/catalog`; в ответе есть `currentVersion`.
502	`upstream_unavailable` / `upstream_auth_failed`	Расчётный сервис недоступен или неверно настроен шлюз.
503	`service_unavailable` / `resolve_unavailable` / `benchmark_unavailable`	Временная проблема на сервере / в базе каталога — повторите с задержкой.

9. Лимиты и рекомендации

Дневная квота общая со страницей Seed-Key на сайте — обе берут из одного счётчика, сброс в 00:00 UTC.
Пиковый лимит: 60 запросов в минуту на ключ. Соблюдайте Retry-After.
У расчётного сервиса также есть небольшой общий бюджет на всех клиентов API; всплеск может дать 429 upstream_rate_limited — повторите с небольшой задержкой.
Кэшируйте /catalog; обновляйте только при 409 catalog_outdated или по расписанию (например, раз в сутки). Сопоставляйте алгоритмы по ecuName + accessLevel + software + seedLength + keyLength.
Повторяйте 502 / 503 / upstream_rate_limited с экспоненциальной задержкой; другие 4xx не повторяйте, кроме 409 (после перезагрузки каталога).
Сохраняйте X-Request-Id неудачных вызовов для поддержки.
schemaVersion в каждом успешном ответе растёт только при ломающем изменении (поле удалено, переименовано или сменило тип); новые поля могут появляться без роста версии, поэтому читайте поля по имени.

Нужен ключ или больший лимит? Напишите в поддержку.