Create or open your account
Open the customer account. It stores subscriptions, public tokens, widget settings, payment documents, VIN statistics and usage limits.
Vinalfa Docs
OEM catalog and widget documentation
This guide explains how to connect OEM catalogs to a website, install the widget, work with VIN and FRAME lookup, open diagrams, search by part name or part number, configure price links and monitor lookup statistics.
1. Quick start
The shortest path from registration to a working OEM catalog is simple: create a subscription, get a public token, embed the widget code and test VIN lookup.
Create a website subscription
On the new subscription page, enter the website domain, choose a plan, select a billing profile and period. A subscription connects website, plan, token, documents and statistics.
Get the installation code
After Trial activation or payment, the account shows a public widget token. Copy the code from the subscription page or from the Widget and API section.
Embed the code on your website
Place a container and the script on the page where the OEM catalog should open. Usually this is a page like /original-catalogs/.
Test VIN, section and price button
Enter a test VIN, open a catalog section, check the diagram, part list, part search and the price button URL.
2. Subscription and access
A subscription is the active connection between a website and Vinalfa: website, plan, billing profile, public token, payment documents and lookup statistics.
Website / domain
The domain where the widget will work. It is used for origin control, token permissions and clean statistics per website.
Plan
The plan defines available features, VIN lookup limit, “Show on diagram” clicks, API access and support level.
Billing profile
A billing profile contains individual or company details. It is used for invoices, acts and payment documents.
Public token
The widget uses the public token on the website. If the subscription is unpaid or inactive, the public token is not shown to the user.
If one client has several websites, create a separate subscription for each website. This keeps limits, errors and statistics clear.
3. Widget installation
The main installation method does not require an iframe. Add a container and one script to the catalog page, then pass the connection parameters from your account.
Basic embed code
Use it on a catalog page, for example https://site.com/original-catalogs/.
Where to get values
data-config and data-token are copied from the account. data-base must match the catalog page path on the client website.
<div id="vinalfa-catalog"></div> <script src="https://vinalfa.com/oem/install.js" data-container="#vinalfa-catalog" data-config="YOUR_CONFIG_ID" data-token="YOUR_PUBLIC_WIDGET_TOKEN" data-base="/original-catalogs" data-api="/oem-api" data-theme="default" defer> </script>
| Parameter | Meaning | Example |
|---|---|---|
data-container |
CSS selector of the block where the catalog will be rendered. | #vinalfa-catalog |
data-config |
Widget configuration ID for appearance and behavior. | 5f81bb0b95c51 |
data-token |
Public token of an active subscription. | eyJ0eXAiOi... |
data-base |
Base path of the catalog page on the client website. | /original-catalogs |
data-api |
API path. It can be proxied through the client website. | /oem-api |
data-theme |
Theme name, if a custom theme is configured. | default |
Important: test a direct VIN URL without a trailing slash, for example
/original-catalogs/WAUZZZF16KD032574. On some websites an extra trailing slash can break routing.4. VIN, BMW 7 characters and FRAME
The widget supports several vehicle identifier formats. The interface should make the format clear and should not force the user to guess where to enter a Japanese FRAME number.
| Format | Use case | Example |
|---|---|---|
| 17-character VIN | Main format for most catalogs. Latin letters and digits are allowed, excluding I, O and Q. | WAUZZZF16KD032574 |
| BMW/MINI 7 characters | BMW and MINI can be looked up by the last 7 VIN characters. | TH89931 |
| FRAME | Used by Japanese catalogs such as Toyota, Nissan, Honda, Mitsubishi, Mazda, Subaru and Suzuki. | A200A-0000061 |
VIN not found
If the VIN is not found, show a clear message, decoded vehicle data and a manager request button.
Second VIN
For some vehicles the decoder can find a related second VIN. The system can then try to open the catalog using that value.
Separate FRAME field
FRAME should be shown as a separate input so users do not see a “17 VIN characters required” validation message.
5. Catalog workflow
After the vehicle is found, the user works with vehicle data, catalog tree, diagrams, hotspots, part list and article actions.
Vehicle block
Shows make, model, year, engine, gearbox and additional vehicle parameters when they exist in the catalog database.
Left catalog tree
Used to navigate main vehicle groups: engine, brakes, suspension, body, electrical equipment and other sections.
Diagrams and hotspots
The diagram lets users select positions. The selected position highlights related parts in the list.
REF and SEC links
If the original catalog contains a reference to another node or section, the widget should display a visible link and open the related section.
Price button
The price button opens article search on the client website. The URL template is configured in the account.
Copy article
A copy icon near the part number helps buyers and managers quickly move the article to search or a request form.
6. Part search inside the catalog
Search helps users avoid opening many sections manually. It should search by part name, synonym, morphology and catalog number.
Name search
Examples: brake pads, oil filter, shock absorber, hall sensor. Both English and Russian names are important.
Article search
A part number should find diagrams where this number exists, for example 1K0698151F or 5208V7.
VIN filtering
Search results should match the opened vehicle. If VIN is known, users should not see unrelated schemes from other configurations.
Search result card
A result card shows diagram preview, section name, applicable part numbers, price button and a link to open the section.
If search returns no results, it should not look like a failure. Show a “No sections found” message and offer to change the query or contact a manager.
7. Price, request and diagram links
The Extension section connects Vinalfa with the client website: price search, VIN request links and product-page “Show on diagram” links.
| Setting | Purpose | Example |
|---|---|---|
| Price URL | The “Prices” button opens part search on the client website. | https://site.com/search-article/?query={article} |
| VIN request URL | If the VIN is not found, the user can send a manager request with prefilled data. | https://site.com/poisk-po-vin/ |
| Show on diagram | An external product page can send the user to matching OEM diagrams by brand and article. | /original-catalogs/article?brand=VW&article=1K0698151F |
| Brand aliases | Websites can use different brand names: VW, Volkswagen, VAG. These variants should point to the right catalog. | VW = Volkswagen = VAG |
Use variables such as
{article}, {brand} and {vin} where a specific setting supports them. Test the URL on one article before enabling it for users.8. Statistics, limits and quality control
Statistics are not only about limits. They show real user issues: which VINs were entered, what failed, where groups were not found and which catalogs need improvement.
Successful VINs
Shows which vehicles were opened, under which subscription and on which date.
VIN errors
Counted by unique VINs and useful for finding problems: VIN not found, Groups not found, Subgroups not found, Catalog unavailable.
Decoder data
If VIN was not found, the log should still show make, model and year from the decoder when available.
Limits
One VIN consumes the limit once per calendar day for one subscription. Reopening sections inside an already opened catalog does not consume VIN limit again.
Statistics are available in VIN Statistics. Users see their active subscriptions; administrators can review all subscriptions and specific ones.
9. Common errors and diagnostics
An error should help the user, not scare them. These are the common messages and the first diagnostic step.
| Message | Meaning | What to check |
|---|---|---|
VIN not found |
The vehicle was not found in connected catalogs. | Check VIN, WMI, year, second VIN from decoder and availability of the required database. |
Catalog unavailable |
The catalog is not connected, not active or not allowed by subscription. | Check plan, catalog availability, subscription status and public token. |
Groups not found |
The vehicle was found, but main catalog groups were not loaded. | Check catalog API, VIN filtering and model-to-group mapping. |
Subgroups not found |
The main group opened, but subgroups were not found. | Check section ID, applicability, translation and subgroup data. |
Origin unavailable for public widget token |
The token is not allowed for the current domain. | Check subscription domain, public token and installation page URL. |
| Blank screen after navigation | The section URL is wrong or the client website intercepts routing. | Check data-base, missing trailing slash and soft-route behavior. |
10. FAQ
Short answers to questions that usually appear before launch and during the first days of operation.
Can the widget design be customized?
Yes. The Widget and API section manages appearance configurations. Subscription and Extension settings define links and button behavior.
Does the user need to choose a catalog manually?
Usually no. The user enters VIN or FRAME, and the system selects the matching catalog. If several variants are found, the widget can show a choice.
What if the VIN is older than the catalog or not found?
Show decoder data and a manager request button. This gives the manager VIN, make, model, year and possible second VIN instead of leaving the user with a dead error.
Can a product page open the matching diagram?
Yes. This requires part-number lookup by article and brand, configured brand aliases and available “Show on diagram” limit in the subscription.
What counts as a repeated VIN lookup?
If the same VIN is opened again on the same calendar day within the same subscription, the VIN limit is not charged again. A new day or another subscription is counted separately.
Where should I report missing catalog data?
Email info@vinalfa.com and include VIN, section link, expected part numbers and a screenshot from the original catalog if available.