Seed-Key API v1

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

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

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

Authorization: Bearer mbseed_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978
X-API-Key: mbseed_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978

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

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

https://mb-solution.org/api/v1/seed/{endpoint}

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

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://mb-solution.org/api/v1/seed/quota

curl -s https://mb-solution.org/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://mb-solution.org/api/v1/seed/catalog

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

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

# условный запрос:
curl -s -X POST https://mb-solution.org/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",
      "SelectorMatch": null
    }
  ],
  "requestId": "req_…"
}

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

Указывайте алгоритм по ecuName, accessLevel, seedLength, keyLength и software (полное значение или номер прошивки). В SelectorMatch передавайте один код идентификации, прочитанный из ЭБУ, а не выражение из каталога.

6. POST /calculate

POSThttps://mb-solution.org/api/v1/seed/calculate

Рассчитайте ключ по параметрам ЭБУ: передайте имя блока, уровень доступа, длины seed/key, при наличии software и код идентификации, а также seed.

Поля запроса

Поле	Обязательно	Описание
`ecuName`	да	1–64 печатных ASCII-символа, из `/catalog` (на сервере приводится к верхнему регистру).
`accessLevel`	да	Целое число 0–1024.
`seedLength`	да	1–512; должно совпадать с длиной `seed` в байтах.
`keyLength`	да	1–512.
`seed`	да	Hex-строка (чётной длины, ≤ 512 символов). Пробелы, `-`, `:` удаляются.
`software`	нет	Полная строка из каталога или номер прошивки, например `"IC222_SW2_2059021304"`, `"2059021304"` или `"000A"`. Строка из 1–255 символов без управляющих символов. Опустите, передайте `null` или пустую строку для выбора строк без software.
`SelectorMatch`	нет	Один hex-код из 4 символов в виде строки, например `"8700"` или `"8600"`. Регистр не важен; сохраняйте ведущие нули. Без префикса и списка через запятую. Также принимается `selectorMatch`. Опустите, передайте `null` или пустую строку для выбора по умолчанию.
`catalogVersion`	нет	Версия каталога `version`, под которую собран запрос — при несовпадении `409 catalog_outdated`.

При поиске software регистр латинских букв не важен, ведущие нули сохраняются. Полное совпадение имеет приоритет. Иначе короткий HEX- или десятичный номер прошивки сопоставляется целиком с частью сразу после SW_, SW0_, SW1_, SW2_ и т. д.; совпадения по подстроке не используются. Затем среди найденных строк применяется выбор по селектору. В ответе возвращается полное сохранённое значение software.

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

curl -s -X POST https://mb-solution.org/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"}'

Если передан SelectorMatch, приоритет имеет строка, содержащая этот код. Для Identification=8700,8600 подойдёт как "8700", так и "8600". Если совпадения нет, используется строка с пустым селектором. Если её нет, выбирается строка с наименьшим числовым HEX-кодом среди всех кодов, перечисленных через запятую: 00FF меньше 1000. Во всех случаях должны совпадать ECU, уровень, длины и software. API вернёт 404 definition_not_found, только если нет подходящей строки. Без селектора выбирается основная строка по умолчанию.

Пример запроса с кодом идентификации (параметры ЭБУ возьмите из нужной строки каталога):

{
  "ecuName": "YOUR_ECU",
  "accessLevel": 17,
  "seedLength": 8,
  "keyLength": 8,
  "software": null,
  "SelectorMatch": "8700",
  "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": "groupPrimary",
  "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 в верхнем регистре.

matchedBy: selector при совпадении кода идентификации, selectorFallback для строки с пустым селектором, selectorLowest для наименьшего HEX-кода или groupPrimary при выборе по умолчанию.

7. GET /benchmark

GEThttps://mb-solution.org/api/v1/seed/benchmark

Выполняет реальный путь чтения из базы на расчётном сервере и возвращает нулевой ключ — можно измерить сквозную задержку без расхода квоты. Нужен API-ключ с активной подпиской Seed-Key. Лимит: 10 запросов в минуту на ключ; при превышении придёт 429 rate_limited с Retry-After.

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

curl -s https://mb-solution.org/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 запросов в минуту для этого ключа (10 для `/benchmark`).
401	`missing_api_key` / `invalid_api_key`	Нет ключа, либо ключ неверного формата или неизвестен. Двадцать таких ответов с одного IP за 5 минут блокируют IP.
429	`upstream_rate_limited`	Расчётный сервис кратковременно перегружен (лимит общий для всех клиентов API). Повторите чуть позже.
400	`invalid_json` / `invalid_seed` / `invalid_catalog_version`	Некорректные данные.
400	`invalid_ecu_name` / `invalid_access_level` / `invalid_length` / `invalid_software` / `invalid_selector_match`	Некорректное поле параметров ЭБУ.
400	`seed_length_mismatch`	Длина seed в байтах ≠ ожидаемой алгоритмом. В ответе есть `expectedLength`.
404	`definition_not_found`	Ни один алгоритм не подходит под параметры.
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 запросов в минуту на ключ (10 в минуту для /benchmark). Соблюдайте Retry-After.
У расчётного сервиса также есть небольшой общий бюджет на всех клиентов API; всплеск может дать 429 upstream_rate_limited — повторите с небольшой задержкой.
Кэшируйте /catalog; обновляйте только при 409 catalog_outdated или по расписанию (например, раз в сутки). Сопоставляйте алгоритмы по ecuName + accessLevel + software + SelectorMatch + seedLength + keyLength.
Повторяйте 502 / 503 / upstream_rate_limited с экспоненциальной задержкой; другие 4xx не повторяйте, кроме 409 (после перезагрузки каталога).
Сохраняйте X-Request-Id неудачных вызовов для поддержки.
schemaVersion в каждом успешном ответе растёт только при ломающем изменении (поле удалено, переименовано или сменило тип); новые поля могут появляться без роста версии, поэтому читайте поля по имени.

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