XUS Firmware API v1

Программный доступ к каталогу прошивок и их скачиванию. Доступ выдаётся на аккаунт и использует дневной лимит и срок действия подписки XUS API этого аккаунта. Дневной счётчик сбрасывается в 00:00 UTC.

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

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

Authorization: Bearer mbxus_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978
X-API-Key: mbxus_0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a6978

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

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

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

Эндпоинт	Метод	Назначение	Списывает квоту
`/list`	GET / POST	Каталог прошивок (имена) + total для детекции изменений	нет
`/download`	GET / POST	Получить временную ссылку на скачивание по имени прошивки	да — см. §5

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

Header	Значение
`X-Request-Id`	Уникальный идентификатор запроса, есть в каждом ответе — указывайте его в обращениях в поддержку. В теле ответов с ошибкой он также дублируется как `requestId`.
`Retry-After`	При `429` — сколько секунд ждать до повтора.

4. GET /list

GEThttps://mbcare.ru/api/v1/xus/list

Возвращает имена прошивок плоским массивом строк и total — сравните total с прошлой синхронизацией, чтобы понять, изменился ли каталог, не сравнивая список. Без limit весь каталог приходит одним ответом; для постраничной выборки используйте cursor.

Поле	Обязательно	Описание
`q`	нет	Фильтр по подстроке имени (≤ 255 символов).
`cursor`	нет	Последнее `name` из предыдущей страницы (не включая его). Повторяйте с прошлым `nextCursor`, пока `hasMore` = true.
`limit`	нет	Максимум строк в ответе. Опустите, чтобы получить весь каталог.

curl -s "https://mbcare.ru/api/v1/xus/list?q=2239020042&limit=10" \
  -H "Authorization: Bearer $MBXUS_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "total": 2,
  "count": 2,
  "hasMore": false,
  "nextCursor": null,
  "items": [ "2239020042_001-SMR-20260708_1212.zip", "2239020042_262509.bin" ]
}

5. GET /download

GEThttps://mbcare.ru/api/v1/xus/download

Поле	Обязательно	Описание
`name`	да	Точное имя прошивки, как в ответе `/list` (≤ 255 символов).
`ttl`	нет	Время жизни ссылки в секундах, `60`–`604800`. По умолчанию 86400 (24 часа).

curl -s "https://mbcare.ru/api/v1/xus/download?name=2239020042_001-SMR-20260708_1212.zip" \
  -H "Authorization: Bearer $MBXUS_KEY" \
  -H "Content-Type: application/json"

{
  "ok": true,
  "name": "2239020042_001-SMR-20260708_1212.zip",
  "downloadURL": "https://mbcare.ru/prod/symbolic/2239020042_001-SMR-20260708_1212.zip?…",
  "zipFileSize": 2492
}

downloadURL ведёт на ваш же домен и действует ttl секунд (по умолчанию 24 часа). Скачивайте её обычным GET — API-ключ на этой ссылке не нужен — и получаете файл. Адрес исходного хранилища клиенту не виден.

Как списывается квота

Один файл · один ключ · одни UTC-сутки. Выдача ссылки /download списывает 1 из дневного лимита.
Повторный запрос того же файла в те же сутки — повтор, докачка, новая ссылка — не списывает повторно.
/list не списывает никогда. Просмотр каталога бесплатен.

6. Ошибки

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

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

HTTP	code	Значение
401	`missing_api_key` / `invalid_api_key`	Нет ключа, либо ключ повреждён / неизвестен.
403	`key_disabled` / `key_revoked` / `customer_disabled`	Ключ или аккаунт неактивен.
403	`ip_not_allowed`	IP вызывающего не в списке разрешённых для ключа. В ответе есть `seenIp`.
403	`no_access` / `access_expired`	У аккаунта нет подписки XUS API / срок закончился.
403	`scope_missing`	Ключу не разрешён этот эндпоинт.
429	`daily_limit_reached`	Дневная квота на скачивания исчерпана. Сброс в 00:00 UTC.
429	`rate_limited` / `ip_rate_limited`	Больше 60 запросов в минуту для этого ключа / этого IP.
400	`missing_name` / `invalid_name` / `invalid_query` / `invalid_cursor`	Некорректные данные.
404	`file_not_found` / `no_download_link`	Ни одна прошивка не совпадает с `name`.
405	`method_not_allowed`	Используйте GET или POST.
500 / 503	`internal_error` / `service_unavailable`	Временная проблема на сервере — повторите с задержкой.

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

Дневная квота: 200 или 2000 скачиваний в сутки в зависимости от тарифа; сброс в 00:00 UTC.
Пиковый лимит: 60 запросов в минуту на ключ (и на IP). Соблюдайте Retry-After.
Кэшируйте /list; обновляйте только при изменении total или по расписанию.
Используйте ссылку весь её срок ttl, а не вызывайте /download заново — за тот же файл в те же сутки повторно не спишется, но так вы экономите запрос.
Повторяйте 500 / 503 с экспоненциальной задержкой; другие 4xx не повторяйте.
Сохраняйте X-Request-Id неудачных вызовов для поддержки.

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