Produkty a polia
Identita produktu
Identitu tvorí kombinácia ean + stock_code. Pre jedno skladové číslo používajte vždy rovnaký neprázdny EAN. Ak EAN zatiaľ nie je známy, pošlite null alebo ho vynechajte: produkt sa prijme s upozornením. Neskoršie doplnenie EAN pri rovnakom stock_code aktualizuje ten istý produkt, zachová jeho stránku aj históriu. Vynechanie, null ani prázdny EAN už známy EAN nevymažú.
Iný neprázdny EAN pri tom istom skladovom čísle je konflikt identity: daný riadok sa odloží na preverenie, ostatné produkty dávky pokračujú. Rovnaký EAN pod rôznymi skladovými číslami označuje samostatné položky. Interné ID Administrácie sa neposiela. Nové skladové číslo vytvorí nový produkt. Chýbajúci produkt v exporte neznamená zmazanie ani skrytie.
Duplicitné stock_code v jednej dávke sa odložia na opravu, ostatné riadky pokračujú. Medzery okolo skladového čísla sa odstránia. Disky sa neimportujú.
Povinné polia každej položky
Nulová cena a zásoba sú hodnoty, nie vynechanie. active s nulovou zásobou umožňuje objednávku na objednávku. passive skryje neukončený produkt. discontinued=true ukončí nákup, ale zachová stránku produktu. Pri novom produkte treba poslať aj názov.
Prijatie dávky a opakovanie
Endpointy a autentifikácia zostávajú: POST /api/v1/elall/products/sync, PUT /api/v1/elall/products/item, X-API-Key. Jedna dávka má 1–10000 riadkov.
Celé JSON telo posielajte v UTF-8, s hlavičkou Content-Type: application/json. UTF-8 BOM sa toleruje; odporúčame UTF-8 bez BOM. Samotné premenovanie .txt na .json kódovanie nemení.
Príjem kvôli kompatibilite automaticky konvertuje rozpoznané UTF-16/32. Pri neplatných UTF-8 bajtoch použije deklarované Windows-1250, Windows-1252, ISO-8859-1 alebo ISO-8859-2; bez použiteľnej deklarácie predpokladá Windows-1250 podľa doterajších exportov. Už správne UTF-8 znaky v zmiešanom vstupe zostávajú zachované. Konverzia je evidovaná ako upozornenie dodávateľovi a neblokuje spracovanie čitateľných produktov. Dodávateľ má naďalej opraviť odosielanie na jednotné UTF-8.
Kódovanie sa nedá vždy určiť jednoznačne; odhad nemusí opraviť každý text. Už stratené alebo nahradené znaky (napr. �) nemožno spätne obnoviť. Nečitateľné Unicode telo alebo syntakticky neplatný JSON sa odmietne odpoveďou 400 alebo 422; nevytvára sa falošné potvrdenie prijatia.
HTTP 200 a success=true potvrdzujú bezpečné prijatie dávky. Produkty sa aktualizujú na pozadí; products_updated je pri prijatí 0. Odpoveď zachováva pôvodné polia a dopĺňa batch_id, processing_status, products_rejected, products_excluded. Chybný riadok sa uloží na opravu; nezastaví celú dávku. Neplatná obálka vráti 422, zlyhanie spojenia 502/503.
request_id je v koreni POST, prípadne v tele PUT; má najviac 64 znakov. Pri chybe spojenia zopakujte rovnaké telo vrátane ID a kontextu. Dostanete rovnaké batch_id; presná retry už spracovanej dávky neprehrá sklad ani cenu. Všetky časti jedného denného exportu posielajte so spoločným request_id; ďalší export dostane nové ID. Rôzne chunky s tým istým ID sa spracujú samostatne. Identické telo s tým istým ID je opakovanie tej istej dávky. Bez ID server vytvorí UUID, ale medzi samostatnými odoslaniami bez stabilného ID nie je garantovaná deduplikácia.
Príklad prijatia jedného platného riadka:
Číselné batch_id prideľuje server. Pri presnej retry sa vracia pôvodné ID a aktuálny stav dávky; products_updated zostáva v potvrdení 0. Počet odmietnutých riadkov môže pri neskoršej retry zahŕňať už známe výsledky spracovania. Neinterpretujte ho ako konečný výsledok importu pri prvom prijatí.
Pre preukázanie úplnosti denného katalógu doplňte existujúci sync_context (číslo časti je doplnok k spoločnému request_id):
Každý chunk má spoločný source_ref, svoje číslo od 1 po N a rovnaký celkový počet. Pre ďalší denný export použite novú referenciu. Aj jednodávkový katalóg označte Chunk 1/1. Hodnota note obsahuje iba tento zápis, bez ďalšieho textu; source_type je catalog_sync (akceptuje sa aj scheduled). source_ref má najviac 128 znakov, note najviac 512.
Monitoring rozlišuje kompletné doručenie všetkých častí od úspešného spracovania celého exportu. Aj bez poznámky alebo kontextu sa produkty spracujú a dávky sa v prehľade združia podľa request_id. Samotné spoločné ID však nedokazuje úplnosť denného katalógu; bez očakávaného počtu častí sa úplnosť označí ako nepotvrdená. Chybný chunk opravte a odošlite znova so zhodným source_ref a Chunk N/M; pri kontrole úplnosti rozhoduje posledná prijatá verzia chunku.
Počas dňa posielajte zmeny cez rovnaké endpointy. Denný katalógový kontext používajte iba pre úplný export; pri skladovej zmene uveďte zodpovedajúci typ dokladu, napr. stock_receipt, stock_issue, customer_sale alebo stock_adjustment. Odoslanie zmien nemusí čakať na dokončenie denného katalógu.
API zaručuje poradie prijatia, nie čas vzniku dokumentu v Elalle. Konektor preto musí zachovať poradie zmien každého skladového čísla; čerstvo doručený starý dokument bez zdrojovej verzie nemožno automaticky odlíšiť od novej aktualizácie.
Katalógové polia (PATCH)
Vynechané pole alebo null zachová aktuálnu hodnotu. false a 0 sa aktualizujú. Dodané hodnoty majú prednosť pred ručnými úpravami v Administrácii. Marketing, SEO a iné neprenášané polia zostávajú.
Prázdny text vymaže príslušnú hodnotu, ak ho schéma nenormalizuje na null; napr. prázdny EAN a prázdne rozmery zachovajú pôvodnú hodnotu. Presná retry nemení už spracovaný produkt. Nová aktualizácia obnoví dodané hodnoty Elallu aj po ručnej úprave v Administrácii.
Pre chybný produkt treba opraviť údaje v Elalle a znova odoslať. Pri hlásení problému použite stock_code, request_id a batch_id. Pole unknown_products je kompatibilné pole s hodnotou 0; nové skladové číslo sa prijíma ako nový produkt.
Zaradenie pneumatík a usage
Pre presné zaradenie pneumatiky podľa typu použitia potrebujeme v exporte vyplnené usage, napr. osobné, SUV alebo ľahký úžitkový. Posielajte skutočné a konzistentné zaradenie z Elallu. Hodnoty pre konkrétne typy použitia dohodnite so Segatom; API nepredpisuje pevný zoznam hodnôt.
Pole zostáva v API voliteľné pre kompatibilitu existujúceho konektora. Jeho neprítomnosť neodmietne produkt. Rozpoznané pneumatiky sa môžu dočasne zobrazovať vo všeobecnom katalógu pneumatík, ale správne zaradenie podľa typu vozidla/použitia sa bez usage nedá spoľahlivo potvrdiť. Konkrétny typ použitia sa neodhadne iba z rozmeru alebo názvu.
Keď doplníte usage, odošlite aktualizovaný produkt cez existujúci endpoint spolu s povinnými poľami. Vyplnená hodnota sa aktualizuje; vynechanie alebo null zachová predchádzajúcu hodnotu.
Kvalita exportu
load_index = nosnosť (napr. 91 alebo 104/102) a speed_index = rýchlosť (napr. V). Hodnoty sa použijú v dodaných poliach bez vzájomného prehadzovania. Posielajte ich už v správnom význame.
rim_inch obsahuje samotný priemer, napr. R16, nie celý rozmer 205/55 R16. dot_code obsahuje číselný DOT / rok, nie značku. ean má byť platný GTIN vrátane kontrolnej číslice; zdieľaný platný EAN medzi skladovými číslami nemení identitu produktu. EÚ štítok môže mať aktuálnu triedu hluku A/B/C alebo historickú 1/2/3.
Nulová cena sa podľa dohody použije aj pri kladnej zásobe; treba ju preveriť pri zdroji. Chýbajúce rozmery môžu obmedziť dostupnosť produktu vo filtroch; posielajte ich v samostatných poliach. Pravidlá pre chýbajúce usage sú uvedené vyššie. Konkrétne problémy, prijaté hodnoty a ďalší krok vysvetľuje Monitoring a opravy.