Engleza
Romana
Un client comandă o plăcuță de frână marcată drept compatibilă cu mașina lui în magazinul tău, dar piesa nu se montează corect. Reflexul obișnuit este să cauți bug-ul în cod, dar de cele mai multe ori cauza reală este în felul în care a fost construit mapping-ul de compatibilitate vehicul-piesă, nu într-o eroare izolată de programare. Mapping-ul de compatibilitate în TecDoc se bazează pe KTYPE (identificatorul tehnic al unei configurații exacte de vehicul) și pe tabelele de linkage, care conectează fiecare articol din catalog la una sau mai multe KTYPE-uri, prin criterii suplimentare care pot fi condiționale sau valabile doar pe un interval (de exemplu, un cod de motor sau un an de fabricație).
Când un magazin online afișează o eroare de fitment, deși API-ul a răspuns inițial „compatibil", cauza este de obicei interpretarea greșită a câmpului linkageTargetType sau ignorarea criteriilor condiționale/interval atașate legăturii dintre articol și vehicul - nu un defect punctual de cod. În acest ghid explicăm exact ce este KTYPE, cum funcționează tabelele de linkage, ce criterii decid fitment-ul real și cum verifici dacă mapping-ul din magazinul tău este construit corect.
Ghidul completează articolul nostru despre identificarea piesei auto prin VIN cu TecDoc API , pentru că cele două subiecte sunt strâns legate, dar nu identice: VIN-ul identifică vehiculul, însă fitment-ul real al piesei depinde de mecanismul KTYPE și de criteriile din linkage descrise mai jos.
Ce este KTYPE (K-Type) și cum diferă de NTYPE
KTYPE este identificatorul numeric unic pe care TecAlliance îl alocă unei configurații tehnice exacte de vehicul - marcă, model, motorizare, an de fabricație și transmisie - pentru autoturisme și vehicule comerciale ușoare. Pentru vehiculele comerciale grele (camioane, utilitare de mare tonaj), TecDoc folosește un identificator echivalent numit NTYPE. Practic, fiecare variantă tehnică distinctă de model primește propriul KTYPE sau NTYPE, iar acesta este elementul central la care se leagă piesele compatibile.
Același concept tehnic circulă sub denumiri diferite în funcție de piață: KTYPE este cunoscut ca TSN în Germania, PR number în Marea Britanie și MMT în Elveția. Denumirile diferă, dar rolul este același - un cod numeric care reprezintă o configurație tehnică de vehicul, nu marca/modelul în sens comercial larg.
Un detaliu important pentru integratori: când un utilizator introduce numărul de înmatriculare sau VIN-ul într-un instrument de identificare a vehiculului, sistemul traduce intern acel cod tot într-un KTYPE, pentru a-l căuta apoi în aceeași bază de date de compatibilitate. Revenim asupra acestei legături în secțiunea despre KTYPE și VIN, pentru că are implicații directe asupra preciziei rezultatelor.
Cum leagă tabelele de linkage o piesă de un vehicul
Un articol din catalogul TecDoc (numit generic GenArt, articol generic, atunci când vorbim despre o categorie de piesă, nu despre un produs al unui producător specific) nu se leagă direct de un model de mașină, ci de unul sau mai multe KTYPE-uri, prin intermediul tabelelor de linkage. Conform specificației oficiale „TecDoc Data Format" publicate de TecAlliance, vehiculele de tip KTyp sunt descrise într-un tabel dedicat (tabelul 120), iar legăturile dintre articole și vehicule sunt stocate într-un set de tabele de linkage (tabelele numerotate de la 400 în sus), printr-un câmp de tip „țintă de linkage" (în documentația originală, VknZielArt) și un identificator al vehiculului țintă (VknZielNr).
Notă de transparență factuală: structura exactă de câmpuri din specificația „TecDoc Data Format" a fost confirmată prin fragmente indexate ale documentului oficial, nu prin citirea integrală a PDF-ului la data redactării - tratează denumirile de câmpuri de mai sus ca fiind corecte la nivel conceptual, dar confirmă-le în propria copie a specificației înainte de a le folosi ca referință de implementare exactă.
Sistemul clasic KTYPE/NTYPE acoperă bine autoturismele și vehiculele comerciale, dar are limite la clase de vehicule mai noi (electrice, hibride). TecAlliance a introdus o extensie - un nou tip de înregistrare pentru maparea KTYPE/NTYPE către o clasificare mai detaliată - exact pentru aceste cazuri, astfel încât tabelele de linkage să poată fi interpretate corect și pentru clasele de vehicule mai noi, nu doar pentru clasificarea istorică „autoturism/vehicul comercial".
La nivel de API, același mecanism este expus diferit, în funcție de generația de integrare. Contractul WSDL clasic Pegasus 3.0 (aceeași familie de webservice verificată și în articolul despre identificarea prin VIN) expune operațiuni dedicate pentru linkage, confirmate direct din schema publică a serviciului: getArticleLinkedAllLinkingTarget3, getArticleLinkedAllLinkingTarget4, getLinkedArticles și getVehicleIdsByKTypeNumber. API-ul REST/JSON mai nou, documentat de TecAlliance, expune conceptul similar prin parametrul carId (numărul KTYPE al vehiculului) combinat cu linkageTargetType, un cod care clasifică tipul de vehicul țintă.
Problema practică este că linkageTargetType nu are o codificare unică, universală, valabilă identic în toate contractele și toate generațiile de API. Tabelul de mai jos sintetizează diferența, pe baza documentației publice disponibile azi:
| Aspect | Sistem clasic (linkage tables 400ff, WSDL) | API REST/JSON nou (documentat de TecAlliance) |
|---|---|---|
| Codificare tip vehicul țintă | Coduri numerice (ex. 2 = autoturisme, 16 = vehicule comerciale) | Coduri litere (ex. „P" autoturisme, „O" comercial, „M" motor) |
| Identificator de vehicul | VknZielNr / KTYPE-NTYPE, în structura de tabele internă | carId (numărul KTYPE), trimis ca parametru de filtrare |
| Acoperire clase noi de vehicule (electrice/hibride) | Necesită maparea extinsă, separată de clasificarea de bază | Depinde de versiunea de API și de cataloagele puse la dispoziție |
| Disponibilitate reală pentru proiectul tău | Depinde de contractul/licența activă cu TecAlliance | Depinde de contractul/licența activă cu TecAlliance |
Concluzia practică: nu presupune niciodată valoarea unui cod de linkageTargetType dintr-un exemplu generic găsit online. Verifică exact ce valori folosește propriul tău contract și propriul WSDL/documentație API, pentru că diferențele între sisteme sunt o sursă reală de erori de mapping.
Criteriile de fitment: atribute condiționale și pe interval
Faptul că un articol este legat de un KTYPE nu înseamnă automat că piesa respectivă se montează pe absolut toate exemplarele acelei configurații de vehicul. Fiecare legătură (linkage) poate avea atașate criterii - atribute suplimentare care restrâng compatibilitatea reală. Documentația funcției „Part Linkage Search" a TecAlliance confirmă acest mecanism prin câmpurile attrId, attrName, attrValue, attrIsConditional și attrIsInterval, atașate fiecărei legături vehicul-articol.
În practică, attrIsConditional marchează faptul că legătura este valabilă doar dacă se respectă o anumită condiție (de exemplu, un cod de motor specific dintr-o gamă mai largă), iar attrIsInterval marchează faptul că atributul este valabil doar într-un interval (de exemplu, un interval de ani de fabricație sau de serie de șasiu, nu pe toată durata de producție a modelului). La nivelul WSDL clasic, operațiunile echivalente sunt getCriteria2, getCriteriaDialogAttributs și getVehicleIdsByCriteria, confirmate în schema publică a serviciului Pegasus 3.0.
Criteriile condiționale și pe interval sunt, de fapt, mecanismul prin care TecDoc încearcă să compenseze faptul că un KTYPE singur nu descrie fiecare variantă de echipare opțională a unui vehicul. Dacă magazinul tău citește doar legătura de bază (articol → KTYPE) și ignoră criteriile atașate, vei afișa drept compatibile piese care, de fapt, se montează doar pe o sub-variantă a acelei configurații.
De ce apar erori de fitment chiar dacă sistemul a răspuns „compatibil"
În experiența noastră de integrare TecDoc pentru magazine din România, erorile de fitment raportate de clienți finali au, de cele mai multe ori, una dintre aceste cauze tehnice:
- Granularitate insuficientă a KTYPE. Sistemul TecDoc folosește un model de tip „defined fitment" (compatibilitate definită pe un identificator simplu de vehicul), nu un model de tip „configuration fitment" (compatibilitate pe baza a zeci de proprietăți tehnice exacte ale unei configurații individuale). O analiză tehnică independentă publicată de specialistul Joan Cabós (Auto Ways) explică exact această limitare: pentru piese precum cutiile de viteze sau alternatoarele, căutarea pe KTYPE returnează frecvent mai multe articole candidate, fără un criteriu suplimentar care să indice clar varianta exactă necesară. Mitigare: tratează rezultatele cu mai multe articole candidate pe același KTYPE ca pe un semnal că trebuie afișate criterii suplimentare de selecție în interfață, nu ca pe o eroare de date.
- Confuzie între sistemele de codificare
linkageTargetType. Folosirea unui cod numeric dintr-un exemplu WSDL generic într-un API REST mai nou (care poate folosi litere) produce filtrare greșită la nivel de tip de vehicul. Mitigare: documentează explicit, pentru propriul tău contract, ce valori și ce format foloseștelinkageTargetType, înainte de a scrie cod de producție. - Ignorarea criteriilor condiționale și pe interval. Multe implementări citesc doar legătura articol-KTYPE și ignoră
attrIsConditional/attrIsInterval, afișând piesa drept compatibilă necondiționat. Mitigare: evaluează explicit aceste atribute înainte de a marca un articol „compatibil" în interfața finală, nu doar la nivel de bază de date internă. - Date de linkage neactualizate local. TecAlliance actualizează periodic legăturile și criteriile; dacă magazinul ține o copie locală fără un proces clar de resincronizare, apar discrepanțe între ce arată magazinul și ce confirmă catalogul oficial. Am detaliat riscurile de sincronizare și de conformitate contractuală a stocării locale în articolul despre erorile frecvente de integrare TecDoc . Mitigare: stabilește un calendar de resincronizare și un proces de validare după fiecare actualizare de date.
- Presupunerea unui mapping 1:1 articol-vehicul. Un singur GenArt poate fi legat de multe KTYPE-uri, iar un singur KTYPE poate avea mai multe articole candidate pentru aceeași categorie de piesă. Mitigare: tratează mapping-ul ca pe o relație many-to-many cu criterii, nu ca pe o căutare simplă de tip „un vehicul → o piesă".
KTYPE și căutarea prin VIN: sisteme complementare, nu interschimbabile
O confuzie frecventă este să crezi că o căutare prin VIN elimină automat riscul de eroare de fitment descris mai sus. Nu este așa. Conform analizei tehnice citate anterior, atunci când un utilizator introduce VIN-ul sau numărul de înmatriculare, sistemul transformă intern acel cod tot într-un KTYPE, pentru a-l căuta apoi în aceeași bază de date de compatibilitate descrisă în secțiunile de mai sus. Cu alte cuvinte, VIN-ul rezolvă ambiguitatea de identificare a vehiculului (care KTYPE exact corespunde acelei mașini), dar nu adaugă, prin el însuși, granularitate suplimentară la nivelul criteriilor de fitment ale piesei.
Pentru detalii tehnice despre operațiunile WSDL reale folosite la identificarea vehiculului prin VIN (getVehicleDataByVINExt, getPartsByVINExt și altele), vezi ghidul nostru dedicat despre identificarea piesei auto prin VIN cu TecDoc API . Cele două mecanisme - identificare prin VIN și mapping prin KTYPE/linkage - se completează: primul răspunde la întrebarea „care este vehiculul exact", al doilea la întrebarea „ce piese sunt cu adevărat compatibile cu acel vehicul, conform criteriilor din linkage".
Implementare practică în Laravel/PHP: ce verifici în mapping-ul de compatibilitate
Pentru arhitectura completă a unui magazin Laravel cu integrare TecDoc - structura de tabele cars*, catalog_products și serviciul dedicat de integrare - am detaliat deja proiectul în articolul despre arhitectura Laravel pentru magazine de piese auto cu TecDoc . Pentru mapping-ul de compatibilitate specific, recomandăm să extinzi acea arhitectură cu o structură care reține explicit și criteriile, nu doar legătura de bază:
| Element TecDoc | Rol | Mapare recomandată local |
|---|---|---|
carId / KTYPE | Configurația exactă de vehicul | cars.tecdoc_ktype_id (index unic) |
linkageTargetType | Clasa de vehicul țintă a legăturii | catalog_products.vehicle_class |
attrId / attrValue | Criteriul exact de fitment | Tabel separat fitment_criteria, relație many-to-many |
attrIsConditional / attrIsInterval | Tipul de restricție a criteriului | Coloane boolean pe fitment_criteria, evaluate la afișare |
Practic, înainte de a marca un produs drept „compatibil" în pagina de listare, serviciul de integrare ar trebui să evalueze explicit criteriile, nu doar legătura de bază:
public function isCompatible(Article $article, int $ktypeId): bool { $linkage = $article->linkagesFor($ktypeId); if (!$linkage) { return false; } foreach ($linkage->criteria as $criterion) { if ($criterion->isConditional && !$criterion->matchesVehicle($ktypeId)) { return false; } if ($criterion->isInterval && !$criterion->withinInterval($ktypeId)) { return false; } } return true; }Codul de mai sus este simplificat pentru claritate și nu reprezintă un client SOAP/REST complet; scopul lui este să arate principiul - isConditional și isInterval trebuie evaluate explicit, nu doar reținute ca metadate fără utilizare în logica de afișare. Operațiunile WSDL reale care alimentează această logică (getCriteria2, getCriteriaDialogAttributs, getVehicleIdsByCriteria) necesită o licență activă TecAlliance; pașii de obținere a licenței sunt detaliați în ghidul complet de licență TecDoc pentru magazine online .
Checklist: cum auditezi un mapping de compatibilitate deja existent
- Verifică, în propriul contract/WSDL, ce valori și ce format folosește efectiv
linkageTargetType- nu presupune un exemplu generic. - Extrage un eșantion de KTYPE-uri cu mai multe articole candidate pentru aceeași categorie de piesă și confirmă dacă diferența reală vine din criterii condiționale ignorate de codul actual.
- Confirmă, citind codul de producție, că
attrIsConditionalșiattrIsIntervalsunt evaluate explicit înainte de afișarea statusului „compatibil", nu doar stocate ca informație descriptivă. - Verifică data ultimei resincronizări a datelor de linkage față de actualizările TecAlliance și documentează un calendar fix de resincronizare.
- Testează același vehicul pe ambele fluxuri - căutare directă prin KTYPE și căutare prin VIN - și confirmă că rezultatele de fitment sunt identice.
- Documentează separat excepțiile cunoscute (de exemplu, piese universale fără KTYPE asociat), ca să nu fie tratate ca erori de mapping în rapoartele de suport.
FAQ: întrebări frecvente despre mapping-ul de compatibilitate în TecDoc
KTYPE este același lucru cu numărul de înmatriculare sau VIN-ul mașinii?
Nu. KTYPE este identificatorul intern TecDoc al unei configurații tehnice de vehicul. Numărul de înmatriculare și VIN-ul sunt date specifice unui exemplar de mașină, care sunt traduse intern, de către sistem, într-un KTYPE pentru a putea fi căutate în baza de date de compatibilitate.
De ce TecDoc arată mai multe piese „compatibile" pentru același KTYPE?
Pentru că modelul KTYPE este de tip „defined fitment" - o granularitate mai mică decât o configurație tehnică completă a vehiculului. Mai multe articole pot fi legate corect de același KTYPE, iar diferențierea exactă se face prin criteriile suplimentare ale legăturii, nu doar prin KTYPE în sine.
Ce înseamnă attrIsConditional și attrIsInterval într-o legătură?
Sunt atribute care restrâng o legătură articol-vehicul: attrIsConditional marchează o condiție specifică (de exemplu, un cod de motor), iar attrIsInterval marchează o valabilitate limitată la un interval (de exemplu, un interval de ani de fabricație). Ignorarea lor în cod duce direct la erori de fitment.
Trebuie să recalculez mapping-ul dacă TecAlliance actualizează datele?
Da. Legăturile și criteriile se actualizează periodic la nivelul catalogului TecDoc. Fără un proces clar de resincronizare și validare, magazinul tău poate rămâne cu un mapping desincronizat față de catalogul oficial.
Pot folosi doar căutarea prin VIN, fără să mă ocup de KTYPE și criterii?
Nu recomandăm asta. VIN-ul rezolvă identificarea exactă a vehiculului, dar rezultatul este tot un KTYPE căutat în aceeași bază de linkage. Fără evaluarea criteriilor condiționale/interval, riști aceleași erori de fitment, indiferent dacă vehiculul a fost identificat prin VIN sau prin selecție manuală marcă/model.
Concluzie: precizia fitment-ului se construiește din KTYPE plus criterii, nu din KTYPE singur
Mapping-ul de compatibilitate vehicul-piesă în TecDoc funcționează prin KTYPE/NTYPE, tabele de linkage și criterii condiționale/pe interval atașate fiecărei legături. Erorile de fitment raportate de clienți apar, în marea majoritate a cazurilor, din ignorarea criteriilor sau din interpretarea greșită a codificării linkageTargetType, nu din date lipsă în catalogul TecDoc. Un mapping corect tratează relația articol-vehicul ca many-to-many, cu criterii evaluate explicit, nu ca o căutare simplă pe un singur identificator.
Dacă vrei să verifici sau să corectezi mapping-ul de compatibilitate din magazinul tău de piese auto, echipa HappyWeb.ro poate analiza împreună cu tine datele de linkage și criteriile existente, ca să elimini erorile de fitment din producție.
Ai nevoie de o soluție personalizată pentru catalogul auto? Discutăm.
Construim aplicații Laravel cu integrare TecDoc. Vezi portofoliul nostru.
Imagine generată cu AI, folosită în scop ilustrativ.
Scrie un comentariu