Optimizare sincronizare TecDoc la volum mare

Un magazin cu câteva mii de articole TecDoc rulează o resincronizare completă a catalogului în câteva minute, fără ca nimeni să observe vreun impact. Aceeași operație, la un catalog cu sute de mii de articole și sute de mii de combinații vehicul-piesă, poate dura ore întregi, poate bloca joburile programate din timpul nopții și poate genera timeout-uri exact în orele cu trafic ridicat. Volumul de date nu este, prin el însuși, problema - modul în care este interogat și sincronizat acel volum este cel care decide dacă magazinul rămâne rapid sau devine, treptat, tot mai lent.

Performanța la volum mare se rezolvă prin trei schimbări structurale: înlocuirea sincronizării complete, periodice, cu o sincronizare incrementală, bazată pe articolele modificate de la ultima rulare; interogarea API-ului TecDoc în loturi (batch), nu articol cu articol; și mutarea căutării/filtrării repetitive dinspre apeluri API către o bază de date locală indexată corect sau un motor de căutare dedicat. Implementate împreună, aceste trei schimbări reduc atât durata sincronizării, cât și numărul de apeluri API necesare la fiecare căutare a unui client.

Acest ghid completează articolul nostru despre erorile frecvente de integrare TecDoc , care acoperă la nivel general conformitatea contractuală a modelului API real-time versus stocare locală. Aici intrăm în detaliul tehnic al sincronizării incrementale, al arhitecturii de joburi în Laravel și al optimizării interogărilor API la volum mare, cu operațiunile WSDL reale implicate.

De ce devine lentă sincronizarea catalogului TecDoc la volum mare de date

În proiectele pe care le-am văzut blocându-se la scalare, încetinirea nu vine dintr-o singură cauză, ci dintr-o combinație de decizii arhitecturale luate când catalogul era mic și care nu mai funcționează la volum mare:

Resincronizare completă la fiecare rulare - tot catalogul este re-extras periodic, deși doar o mică parte din articole s-a schimbat de fapt.
Interogări articol cu articol - magazinul cere fiecare articol printr-un apel API separat, în loc să grupeze cererile în loturi.
Sincronizare sincronă, în firul de execuție al cererii - un job lung rulează direct, blocând resurse care ar trebui să răspundă clienților.
Lipsa indecșilor pe coloanele de căutare/filtrare - fiecare căutare locală scanează un tabel mare fără un index potrivit.
Lipsa unui control de concurență - mai multe procese cer date de la TecAlliance simultan, fără limită internă, ceea ce crește riscul de timeout-uri și erori tranzitorii.

Full sync vs sincronizare incrementală: ce decide performanța pe termen lung

Sincronizarea completă (full sync) înseamnă re-extragerea întregului catalog la fiecare rulare, indiferent câte articole s-au schimbat de fapt. Este simplu de implementat, dar costul crește direct proporțional cu dimensiunea catalogului - nu cu numărul real de modificări. Sincronizarea incrementală (delta sync) cere doar articolele adăugate, modificate sau șterse de la ultima rulare, ceea ce păstrează timpul de sincronizare relativ constant, indiferent cât de mare devine catalogul în timp.

Tabelul de mai jos sintetizează diferența dintre cele trei moduri de sincronizare disponibile practic într-o integrare TecDoc, pe baza operațiunilor WSDL confirmate și a informațiilor publice TecAlliance despre noua interfață de actualizări în timp real:

Aspect	Full sync (re-extragere completă)	Incrementală (state-based, WSDL clasic)	IDP Data Receiver API (delta nativ)
Volum de date transferat	Tot catalogul, la fiecare rulare	Doar articolele cu status modificat de la o dată dată	Doar obiectele noi/modificate/șterse, livrate ca deltă
Timp de procesare la scalare	Crește direct cu mărimea catalogului	Relativ constant, depinde de volumul de modificări	Relativ constant, optimizat nativ pentru actualizări
Complexitate de implementare	Redusă	Medie - necesită urmărirea datei ultimei sincronizări	Medie - integrare API dedicată, conform contractului
Acoperire la data redactării	Întregul catalog la care ai acces contractual	Întregul catalog la care ai acces contractual	Autoturisme, motociclete și vehicule comerciale ușoare; extindere către NType, axe și transmisii anunțată pentru mijlocul anului 2026

Nu este obligatoriu să alegi un singur model. În practică, multe magazine pornesc cu o sincronizare completă inițială (prima populare a bazei de date), apoi trec pe sincronizare incrementală pentru toate rulările următoare.

Sincronizare incrementală reală cu TecDoc: state-based query și IDP Data Receiver API

La nivelul contractului WSDL clasic Pegasus 3.0 (aceeași familie de webservice verificată și în articolele noastre despre identificarea prin VIN și despre mapping-ul de compatibilitate), operațiunea relevantă pentru sincronizare incrementală este getArticleIdsWithState. Confirmat direct din schema publică a serviciului, această operațiune acceptă parametrul articleStatusDate, descris oficial ca incluzând „doar articolele al căror status este valabil de la data dată" - practic, exact mecanismul necesar pentru a cere „ce s-a schimbat de la ultima mea sincronizare". Răspunsul include și totalMatchingArticles, util pentru a urmări progresul unei rulări mari de sincronizare.

Notă de transparență factuală: parametrul articleStatusIds din aceeași operațiune filtrează după coduri de status, dar codificarea exactă a acestor coduri (de exemplu, ce cod înseamnă „articol nou" față de „articol șters") nu este publică - se confirmă din propriul contract/documentație TecAlliance, nu dintr-un exemplu generic găsit online.

Pentru preluarea efectivă a datelor articolelor identificate ca modificate, operațiunile de tip getAssignedArticlesByIds7 și getDirectArticlesByIds7 acceptă un șir de identificatori de articol (articleIds) într-un singur apel, ceea ce permite preluarea în loturi, nu articol cu articol.

Pe lângă mecanismul clasic state-based, TecAlliance a introdus public IDP (Instant Data Processing) și interfața IDP Data Receiver API, descrisă oficial ca oferind „acces mai rapid la obiecte noi, actualizate sau șterse" și reducând „efortul de procesare prin livrarea de delte, nu de seturi complete de date". Conform aceleiași surse, acoperirea inițială include autoturisme, motociclete și vehicule comerciale ușoare, cu extindere planificată către NType, axe și transmisii la mijlocul anului 2026. Dacă proiectul tău se încadrează în acoperirea curentă, IDP Data Receiver API este, la data redactării, mecanismul nativ recomandat de TecAlliance pentru actualizări incrementale; pentru restul cataloagelor, state-based query rămâne soluția practică.

Arhitectura de sincronizare în Laravel: chunking, joburi în coadă și idempotență

Pentru arhitectura completă a unui magazin Laravel cu integrare TecDoc, am detaliat deja structura de tabele și serviciul de integrare în articolul despre arhitectura Laravel pentru magazine de piese auto cu TecDoc . Pentru sincronizare la volum mare, recomandăm extinderea acelei arhitecturi cu un flux în trei pași: identificarea articolelor modificate, împărțirea lor în loturi și procesarea fiecărui lot printr-un job de coadă separat, nu printr-un singur script monolitic care rulează ore în șir.

$lastSyncAt = TecdocSyncRun::latest('finished_at')->value('finished_at'); $changed = $tecdoc->getArticleIdsWithState( provider: config('tecdoc.provider'), articleCountry: 'RO', articleStatusDate: $lastSyncAt?->toDateString(), ); foreach (array_chunk($changed->articleIds, 200) as $batch) { SyncTecdocArticlesBatch::dispatch($batch); }

class SyncTecdocArticlesBatch implements ShouldQueue { public function __construct(private array $articleIds) { } public function handle(TecdocClient $tecdoc): void { $articles = $tecdoc->getAssignedArticlesByIds7( articleIds: $this->articleIds, provider: config('tecdoc.provider'), ); CatalogProduct::upsert( $this->mapToRows($articles), uniqueBy: ['tecdoc_article_id'], update: ['title', 'price_group', 'updated_at'], ); } }

Codul de mai sus este simplificat pentru claritate și nu reprezintă un client SOAP complet; scopul lui este să arate principiul - identifici modificările cu getArticleIdsWithState, le împarți în loturi gestionabile cu array_chunk, procesezi fiecare lot printr-un job separat (ShouldQueue) și scrii rezultatul cu upsert, cheiat pe identificatorul TecDoc al articolului. Idempotența contează: dacă un job eșuează la jumătate și este reluat, upsert nu creează duplicate, doar actualizează rândurile deja scrise. Dimensiunea unui lot (în exemplu, 200) este orientativă - testeaz-o pe propriul cont, pentru că TecAlliance nu publică o limită universală de mărime a loturilor.

Optimizarea interogărilor API la volum mare: batching, cache și control de concurență

Sincronizarea pe fundal rezolvă doar o parte din problemă. Cealaltă parte sunt interogările declanșate live de vizitatori - căutare după marcă/model, verificare de compatibilitate, afișare fișă produs - care pot lovi API-ul TecDoc direct din cererea utilizatorului dacă arhitectura nu este atentă.

Cache cu TTL controlat. Pentru interogări repetitive (același KTYPE sau aceeași căutare cerută de mai mulți vizitatori într-un interval scurt), un cache temporar (de exemplu, Redis) reduce numărul de apeluri reale către TecAlliance. Aplică această măsură doar în limitele permise de licența activă - vezi nota de conformitate din articolul despre erorile frecvente de integrare TecDoc .
Batching la cerere. Dacă o pagină are nevoie de date pentru mai multe articole, grupează-le într-un singur apel getAssignedArticlesByIds7, în loc de un apel per articol afișat în listă.
Control de concurență. Limitează numărul de cereri simultane trimise către TecAlliance dintr-un singur proces (semafor sau rate limiter intern), ca să nu amplifici singur o problemă temporară de latență a API-ului.
Retry cu backoff, doar pe erori tranzitorii. Reîncearcă automat la timeout sau eroare 5xx, cu pauză crescătoare între încercări; nu reîncerca pe erori funcționale (de exemplu, identificator de articol inexistent), pentru că acelea nu se rezolvă singure.

Despre limitele exacte de rată (rate limiting) sau cotele de utilizare ale contractului tău TecAlliance: la data redactării, nu am găsit o documentație publică unică, universală, cu valori exacte. Tratează acest aspect ca specific contractului tău și clarifică-l direct cu reprezentantul TecAlliance, conform și ghidului nostru de licență TecDoc pentru magazine online .

Indexare locală și motor de căutare dedicat pentru catalogul TecDoc

Datele preluate prin sincronizare ajung, de obicei, într-o bază de date relațională locală. La volum mare, viteza căutării locale depinde direct de indexare: un index unic pe identificatorul TecDoc al articolului (tecdoc_article_id) și indecși pe coloanele folosite efectiv la filtrare (producător, categorie, identificatorul de vehicul/KTYPE) reduc timpul de căutare de la scanări complete de tabel la căutări directe.

Pentru cataloage foarte mari, cu căutare full-text complexă (după nume, cod OE, cod producător, sinonime), indexarea relațională clasică poate deveni insuficientă pentru un timp de răspuns bun. Într-un astfel de caz, o decizie arhitecturală validă este introducerea unui motor de căutare dedicat (de exemplu Meilisearch sau Elasticsearch), folosit strict pentru căutare/filtrare, în paralel cu baza de date relațională care rămâne sursa canonică de date.

Criteriu	Doar indexare relațională (MySQL/PostgreSQL)	Motor de căutare dedicat (ex. Meilisearch/Elasticsearch)
Complexitate de operare	Mai simplă - o singură sursă de date de administrat	Mai mare - necesită sincronizare proprie index ↔ bază de date
Potrivit pentru	Cataloage medii, filtrare structurată (marcă, model, categorie)	Cataloage foarte mari, căutare text liber, sinonime, toleranță la erori
Cost suplimentar de infrastructură	Redus	Mediu-ridicat, în funcție de volum și disponibilitate cerută

Erori de performanță frecvente și cum le previi

Resincronizare completă programată zilnic, fără motiv real. Crește costul de sincronizare proporțional cu mărimea catalogului, deși modificările reale sunt, de obicei, o fracțiune mică din total. Mitigare: treci pe sincronizare incrementală bazată pe articleStatusDate sau pe IDP Data Receiver API, acolo unde acoperirea contractuală permite.
Apeluri API sincrone direct în cererea utilizatorului. O pagină de produs care așteaptă răspunsul TecAlliance înainte de a se afișa devine la fel de lentă pe cât este, în acel moment, API-ul extern. Mitigare: mută interogările care pot fi anticipate în sincronizare pe fundal și folosește cache pentru cele repetitive.
Lipsa indecșilor pe coloanele de filtrare reală. Fiecare căutare scanează un tabel mare, iar timpul de răspuns crește liniar cu numărul de articole. Mitigare: adaugă indecși pe coloanele efectiv folosite în clauzele de filtrare, nu doar pe cheia primară.
Lipsa monitorizării sincronizării. Un job de sincronizare care eșuează silențios poate lăsa magazinul cu date vechi săptămâni la rând, fără ca echipa să observe. Mitigare: loghează fiecare rulare (durată, număr de articole procesate, erori) și alertează automat la eșec sau la o durată anormal de mare.
Retry agresiv, fără backoff, pe toate tipurile de eroare. Amplifică o problemă temporară de disponibilitate a API-ului TecAlliance, transformând o încetinire scurtă într-o cascadă de erori. Mitigare: aplică backoff exponențial și reîncearcă doar erorile tranzitorii (timeout, 5xx), nu și pe cele funcționale.

Plan practic: checklist de optimizare a sincronizării și interogărilor API

Măsoară durata actuală și volumul de date al sincronizării complete, ca linie de bază de comparație pentru optimizările următoare.
Înlocuiește sincronizarea completă programată cu interogare incrementală - getArticleIdsWithState cu articleStatusDate sau IDP Data Receiver API, după acoperirea disponibilă în contractul tău.
Împarte sincronizarea în loturi (array_chunk) și rulează fiecare lot printr-un job de coadă separat, nu printr-un singur script monolitic.
Adaugă scriere idempotentă (upsert), cheiată pe identificatorul TecDoc al articolului, ca să poți relua în siguranță un job eșuat.
Introdu cache cu TTL controlat pentru interogările repetitive din front-end, în limitele permise de licența activă.
Adaugă indecși pe coloanele de căutare/filtrare folosite efectiv și evaluează un motor de căutare dedicat dacă volumul și complexitatea căutării o cer.
Configurează monitorizare explicită: durata fiecărei sincronizări, rata de eroare a API-ului, latența p95/p99 și alertare automată la eșec silențios.
Clarifică direct cu TecAlliance limitele de rată/cotă ale contractului tău, în loc să presupui o valoare generică găsită online.

FAQ: întrebări frecvente despre performanța integrării TecDoc

Cât de des ar trebui să rulez sincronizarea cu TecDoc?

Depinde de cât de des se schimbă efectiv datele relevante pentru magazinul tău și de termenii contractului. Cu sincronizare incrementală, rulările frecvente (de exemplu, orar) sunt mai puțin costisitoare decât cu sincronizare completă, pentru că se transferă doar modificările, nu tot catalogul.

Sincronizarea incrementală înlocuiește complet sincronizarea completă?

Nu neapărat de la zero. O sincronizare completă rămâne utilă pentru popularea inițială a bazei de date sau pentru validări periodice de consistență; rulările curente, repetate, ar trebui însă să folosească mecanismul incremental, nu re-extragerea integrală a catalogului.

Pot folosi cache pentru rezultatele API TecDoc?

Depinde de termenii licenței active. Unele forme de cache temporar pentru reducerea latenței sunt frecvent acceptabile, dar persistența pe termen lung a anumitor date poate fi limitată contractual - verifică explicit acest aspect cu TecAlliance înainte de a implementa un cache permanent.

Ce diferență este între getArticleIdsWithState și IDP Data Receiver API?

getArticleIdsWithState face parte din contractul WSDL clasic Pegasus 3.0 și permite filtrarea articolelor după o dată de status. IDP Data Receiver API este interfața mai nouă a TecAlliance, construită nativ pentru livrarea de delte (doar obiecte noi, actualizate sau șterse), cu acoperire inițială limitată la anumite clase de vehicule la data redactării.

Cât de mari ar trebui să fie loturile (batch-urile) la sincronizare?

Nu există o valoare universală publicată de TecAlliance. Pornește cu un lot moderat (de exemplu, câteva sute de articole), măsoară timpul de răspuns și rata de eroare, apoi ajustează dimensiunea pe baza rezultatelor reale din contul tău.

De ce sincronizarea pare corectă, dar magazinul rămâne lent la căutare?

De obicei pentru că problema nu mai este la sincronizare, ci la interogarea locală a datelor deja sincronizate - lipsa unor indecși potriviți sau absența unui motor de căutare dedicat la volum foarte mare. Verifică separat cele două fluxuri: viteza sincronizării și viteza căutării locale.

Concluzie: performanța la volum mare vine din arhitectură, nu din mai mult hardware

Problemele de performanță la integrarea TecDoc nu se rezolvă, de regulă, cu un server mai puternic. Soluția sustenabilă este o combinație de sincronizare incrementală, interogări API grupate în loturi, cache controlat contractual, indexare locală corectă și monitorizare activă a întregului flux. Implementate împreună, aceste măsuri păstrează timpul de sincronizare și viteza de căutare relativ constante, chiar dacă numărul de articole și de combinații vehicul-piesă din catalogul tău crește semnificativ.

Dacă magazinul tău se confruntă cu sincronizări lente sau cu timeout-uri la volum mare de date, echipa HappyWeb.ro poate analiza arhitectura actuală și propune un plan concret de optimizare.

Construim aplicații Laravel cu integrare TecDoc. Vezi portofoliul nostru.

Vrei să optimizezi sincronizarea sau interogările API din magazinul tău TecDoc? Contactează-ne pentru o consultanță tehnică.

Imagine generată cu AI, folosită în scop ilustrativ.

Probleme de performanță la integrarea TecDoc: optimizarea sincronizării catalogului și a interogărilor API la volum mare de date