Создайте или войдите в аккаунт
Откройте личный кабинет. В аккаунте хранятся подписки, токены, настройки виджета, платежные документы, статистика VIN и лимиты.
Vinalfa Docs
Документация по OEM-каталогам и виджету
Здесь собраны инструкции для владельца сайта, менеджера и разработчика: как оформить подключение, установить виджет, работать с VIN и FRAME, искать запчасти, открывать схемы, настраивать ссылки на цены и контролировать статистику.
1. Быстрый старт
Минимальный путь от регистрации до рабочего каталога на сайте занимает несколько шагов. Сначала создается подключение, затем выпускается публичный токен и вставляется код установки.
Оформите подключение для сайта
На странице новой подписки укажите домен, выберите тариф, период и плательщика. Подписка связывает сайт, тариф, токен, документы и статистику.
Получите код установки
После оплаты или активации Trial в кабинете появится публичный токен. Код можно скопировать из разделов подписки и “Виджет и API”.
Вставьте код на страницу сайта
Разместите контейнер и скрипт на странице, где должны открываться оригинальные каталоги. Обычно это страница вида /original-catalogs/.
Проверьте VIN и поиск
Введите тестовый VIN, откройте раздел, проверьте схему, кнопку цены и быстрый поиск по названию или артикулу.
2. Подписка и доступы
Подписка должна восприниматься как текущее подключение сайта к Vinalfa: “сайт -> тариф -> плательщик -> токен -> документы”.
Сайт / домен
Указывается домен, на котором будет работать виджет. Это нужно для контроля origin, выдачи публичного токена и корректной статистики.
Тариф
Тариф определяет набор возможностей, лимит VIN-пробивок, лимит переходов “Показать на схеме”, доступ к API и уровень поддержки.
Плательщик
Для документов выбирается физическое или юридическое лицо. Юрлицо используется для счета, актов и корпоративной оплаты.
Публичный токен
Токен нужен виджету на сайте. Если подписка не оплачена или не активна, публичный токен пользователю не показывается.
Если у одного клиента несколько сайтов, для каждого сайта лучше создавать отдельную подписку. Так проще видеть статистику, лимиты, ошибки и управлять токенами.
3. Установка виджета на сайт
Основной вариант установки не требует iframe. На страницу добавляется контейнер и скрипт, а параметры подключения берутся из кабинета.
Базовый код
Подходит для страницы каталога, например https://site.com/original-catalogs/.
Где взять значения
data-config и data-token копируются из личного кабинета. data-base должен совпадать с адресом страницы, где установлен каталог.
<div id="vinalfa-catalog"></div> <script src="https://vinalfa.com/oem/install.js" data-container="#vinalfa-catalog" data-config="ВАШ_CONFIG_ID" data-token="ВАШ_PUBLIC_WIDGET_TOKEN" data-base="/original-catalogs" data-api="/oem-api" data-theme="default" defer> </script>
| Параметр | Что означает | Пример |
|---|---|---|
data-container |
CSS-селектор блока, в который будет загружен каталог. | #vinalfa-catalog |
data-config |
ID конфигурации внешнего вида и поведения виджета. | 5f81bb0b95c51 |
data-token |
Публичный токен активной подписки. | eyJ0eXAiOi... |
data-base |
Базовый путь страницы каталога на сайте клиента. | /original-catalogs |
data-api |
Путь API. Можно использовать прокси на стороне сайта клиента. | /oem-api |
data-theme |
Тема оформления, если она настроена для сайта. | default |
Важно: после установки проверьте прямой URL с VIN без завершающего слеша, например
/original-catalogs/WAUZZZF16KD032574. Лишний слеш в конце может мешать маршрутизации некоторых сайтов.4. VIN, короткий BMW/MINI VIN и FRAME
Виджет умеет работать с разными форматами идентификаторов автомобиля. Главное - дать пользователю отдельные понятные поля и не заставлять его угадывать формат.
| Формат | Для чего используется | Пример |
|---|---|---|
| VIN 17 символов | Основной формат для большинства каталогов. Допустимы латинские буквы и цифры без I, O и Q. | WAUZZZF16KD032574 |
| BMW/MINI 7 знаков | Для BMW и MINI может использоваться пробивка по последним 7 знакам VIN. | TH89931 |
| FRAME | Используется для японских каталогов: Toyota, Nissan, Honda, Mitsubishi, Mazda, Subaru, Suzuki и близких баз. | A200A-0000061 |
VIN не найден
Если VIN не пробился, виджет показывает понятное сообщение, данные из декодера и кнопку обращения к менеджеру.
Второй VIN
Для некоторых автомобилей декодер может найти связанный второй VIN. В таком случае система может попробовать открыть каталог по найденному значению.
FRAME-поле
FRAME лучше показывать отдельным полем, чтобы пользователь не видел ошибку “нужно 17 символов VIN” при вводе японского номера кузова.
5. Как работать с каталогом
После пробивки автомобиля пользователь попадает в рабочий каталог: параметры авто, дерево разделов, схемы, маркеры, список деталей и действия с артикулами.
Верхний блок автомобиля
Показывает марку, модель, год, двигатель, КПП и дополнительные параметры, если они есть в базе каталога.
Левое меню разделов
Используется для перехода по основным узлам автомобиля: двигатель, тормоза, подвеска, кузов, электрика и другие группы.
Схемы и маркеры
На изображении можно выбирать позиции. Выбранная позиция подсвечивается, а список справа показывает артикулы, количество и примечания.
REF и SEC-переходы
Если оригинальный каталог содержит ссылку на другой узел или секцию, виджет должен показывать заметную ссылку и вести пользователя в связанный раздел.
Кнопка цены
Кнопка открывает поиск артикула на сайте клиента. Шаблон ссылки настраивается в кабинете.
Копирование артикула
Рядом с номером детали может быть иконка копирования, чтобы менеджер или покупатель быстро перенес артикул в поиск или заявку.
6. Поиск запчастей внутри каталога
Поиск нужен, чтобы пользователь не открывал десятки разделов вручную. Он должен искать по названию детали, синонимам, морфологии и каталожному номеру.
Поиск по названию
Примеры запросов: колодки, масляный фильтр, амортизатор, датчик холла. Для пользователя важны русские и английские названия.
Поиск по артикулу
Каталожный номер должен находить разделы, где этот номер присутствует на схеме, например 1K0698151F или 5208V7.
Фильтрация по VIN
Результаты поиска должны соответствовать открытому автомобилю. Если VIN известен, пользователь не должен видеть лишние схемы от других комплектаций.
Поведение результата
Карточка результата показывает превью схемы, название раздела, применимые артикулы, кнопку цены и переход внутрь раздела.
Если поиск ничего не нашел, это не должно выглядеть как сбой. Покажите сообщение “Разделы не найдены”, предложите изменить запрос или оставить заявку менеджеру.
7. Ссылки на цены, заявки и схемы
В кабинете есть раздел “Расширение”. Там настраиваются ссылки, которые связывают Vinalfa с сайтом клиента.
| Настройка | Зачем нужна | Пример |
|---|---|---|
| Ссылка цены | Кнопка “Цены” открывает поиск артикула на сайте клиента. | https://site.com/search-article/?query={article} |
| Ссылка VIN-заявки | Если VIN не найден, пользователь может отправить заявку менеджеру с уже заполненными данными. | https://site.com/poisk-po-vin/ |
| Показать на схеме | Внешняя карточка товара может отправить пользователя в подходящие схемы по бренду и артикулу. | /original-catalogs/article?brand=VW&article=1K0698151F |
| Словоформы брендов | На сайтах бренды могут называться по-разному: VW, Volkswagen, VAG. Эти варианты надо приводить к понятному каталогу. | VW = Volkswagen = VAG |
Для ссылок используйте переменные
{article}, {brand}, {vin}, если они поддерживаются конкретной настройкой. Сначала проверьте ссылку на одном артикуле, затем включайте ее для пользователей.8. Статистика, лимиты и контроль качества
Статистика нужна не только для учета лимита. Она показывает реальные проблемы пользователей: какие VIN вводят, что не пробилось, где не нашлись группы и какие каталоги требуют доработки.
Успешные VIN
Показывают, какие автомобили открывались, по какой подписке и в какой день.
Ошибки VIN
Считаются по уникальным VIN и помогают быстро найти проблемы: VIN not found, Groups not found, Subgroups not found, Catalog unavailable.
Данные декодера
Если VIN не пробился, в журнале полезно видеть марку, модель и год из декодера, чтобы менеджер понимал, что искал пользователь.
Лимиты
Один VIN списывает лимит один раз за календарный день для одной подписки. Повторное открытие разделов внутри уже найденного авто не списывает VIN-лимит повторно.
Статистика доступна в разделе “Статистика VIN”. Пользователь видит свои активные подписки, администратор может смотреть общую картину и отдельные подписки.
9. Частые ошибки и что делать
Ошибка должна помогать пользователю, а не пугать его. Ниже - расшифровка типовых сообщений и первый шаг диагностики.
| Сообщение | Что означает | Что проверить |
|---|---|---|
VIN not found |
Автомобиль не найден в подключенных каталогах. | Проверить VIN, WMI, год, второй VIN из декодера и наличие нужной базы. |
Catalog unavailable |
Каталог не подключен, не активен или нет доступа по подписке. | Проверить тариф, список каталогов, активность подписки и токен. |
Groups not found |
Автомобиль найден, но не удалось получить основные разделы. | Проверить API каталога, фильтрацию по VIN и связку модели с группами. |
Subgroups not found |
Основная группа открылась, но подразделы не найдены. | Проверить ID раздела, применимость, перевод и данные подгрупп. |
Origin unavailable for public widget token |
Токен не разрешен для текущего домена. | Проверить домен подписки, public token и адрес страницы установки. |
| Пустой экран после перехода | URL раздела сформирован неверно или страница клиента перехватывает маршрут. | Проверить data-base, отсутствие лишнего слеша и работу soft-route. |
10. FAQ
Короткие ответы на вопросы, которые чаще всего возникают перед запуском и в первые дни работы.
Можно ли менять внешний вид виджета?
Да. В разделе “Виджет и API” можно работать с конфигурациями оформления, а в настройках подписки и расширения - задать ссылки и поведение кнопок.
Нужно ли пользователю выбирать каталог вручную?
Обычно нет. Пользователь вводит VIN или FRAME, а система выбирает подходящий каталог. Если по VIN найдено несколько вариантов, виджет может показать выбор.
Что делать, если VIN старше каталога или не пробивается?
Показывайте данные декодера и кнопку заявки менеджеру. Так пользователь не упирается в ошибку, а менеджер получает VIN, марку, модель, год и возможный второй VIN.
Можно ли открыть схему из карточки товара на сайте?
Да. Для этого нужен поиск по артикулу и бренду, настроенные словоформы брендов и лимит переходов “Показать на схеме” в подписке.
Что считается повторной VIN-пробивкой?
Если тот же VIN открывается повторно в тот же календарный день в рамках одной подписки, VIN-лимит повторно не списывается. Новый день или другая подписка считаются отдельно.
Куда обращаться, если каталог показывает не все детали?
Напишите на info@vinalfa.com и приложите VIN, ссылку на раздел, ожидаемые артикулы и скрин из оригинального каталога, если он есть.