Production · версия 2.0

API OEM-каталогов Vinalfa

Серверный REST API для VIN и FRAME, параметров автомобиля, структуры каталога, схем, каталожных номеров, быстрого отбора и поиска по деталям.

Получить API-токен OpenAPI 3.1 JSON

Базовый URL https://api.vinalfa.com/oem/v2

API V2.0 работает

REST + JSONЕдиный формат ответов и предсказуемые HTTP-статусы.

OpenAPI 3.1Схема для Postman, SDK и генерации клиентов.

VIN + FRAMEVIN, последние 7 символов BMW/MINI и японский FRAME.

Привязка к подпискеТокен видит только каталоги своей активной подписки.

Быстрый старт

Выпустите отдельный серверный токен в личном кабинете. Публичный токен виджета для API не подходит.

curl --request GET \
  --url "https://api.vinalfa.com/oem/v2/catalogs" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer YOUR_API_TOKEN"

Авторизация

Передавайте токен в стандартном заголовке Bearer. Каждый токен принадлежит одной подписке.

Храните API-токен только на backend. Не размещайте его в HTML, frontend JavaScript или публичном репозитории.

Authorization: Bearer YOUR_API_TOKEN
Accept: application/json
Content-Type: application/json
X-Request-ID: your-trace-id

Методы API V2.0

Hash непрозрачен: сохраняйте полученное значение и передавайте его без изменения.

GET/catalogs

Каталоги активной подписки.

POST/vehicles/resolve

Автомобиль по VIN, последним 7 символам или FRAME.

GET/vehicles/{vehicleHash}/groups

Основные группы выбранного автомобиля.

GET/vehicles/{vehicleHash}/quick-selection

Классы деталей и быстрый отбор.

GET/sections/{sectionHash}/children

Подразделы и доступные схемы.

GET/sections/{sectionHash}/parts

Схема, координаты, позиции и артикулы.

GET/vehicles/{vehicleHash}/search?q=...

Поиск по названию или артикулу с учётом автомобиля.

POST/article-schemes/search

Поиск схем по артикулу и бренду. Успешный результат учитывается в лимите переходов к схемам.

POST/article-schemes/availability

Проверка до 100 пар «артикул + бренд» без списания лимита переходов к схемам.

POST/article-relations/resolve

Определение текущих, старых и заменённых артикулов с указанием источника связи.

curl --request POST \
  --url "https://api.vinalfa.com/oem/v2/article-schemes/availability" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"items":[{"article":"5K0698151H8","brand":"VAG"},{"article":"A6421800010","brand":"Mercedes-Benz"}]}'

Рабочий сценарий

Не перебирайте каталоги самостоятельно: resolve применяет WMI, второй VIN, последние 7 символов, FRAME и приоритеты источников.

01Определение

Передайте VIN или FRAME.

02Группы

Выберите модификацию и используйте её hash.

03Разделы

Перейдите по hash разделов до схемы.

04Детали

Получите изображение, hotspot-точки и артикулы.

curl --request POST \
  --url "https://api.vinalfa.com/oem/v2/vehicles/resolve" \
  --header "Authorization: Bearer YOUR_API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"identifier":"TMBJF25LXC6071337"}'

Ответы и ошибки

Успешный ответ содержит data и meta. Ошибка содержит машинный code, message и request_id.

200 OK

{
  "data": { "catalogs": [] },
  "meta": {
    "api_version": "2.0",
    "request_id": "..."
  }
}

4xx / 429

{
  "error": {
    "code": "validation_failed",
    "message": "..."
  },
  "meta": { "request_id": "..." }
}

Лимиты и безопасность

Лимиты защищают подписку и инфраструктуру, не мешая обычной навигации по уже открытому каталогу.

Частота запросов	До 120 серверных запросов в минуту на один API-токен.
VIN / FRAME	Один идентификатор учитывается один раз за календарные сутки в рамках одной подписки.
Навигация	Открытие разделов, схем и деталей найденного автомобиля повторно VIN не списывает.
Токен	При компрометации перевыпустите токен в кабинете — предыдущий будет отозван сразу.