Feed špecifikácia pre partnerov

1. Kľúčové informácie pred začatím

2. Technické požiadavky

Parameter	Požiadavka
Formát	XML (preferované) alebo JSON
Encoding	UTF-8
Dostupnosť	Verejná HTTPS URL alebo s Basic Auth / Bearer Token
Update frekvencia	Minimálne 1× denne, ideálne 2-4× denne
Štruktúra	Plochá - každé vozidlo ako samostatný element / objekt v poli
Typ vozidiel	Len BEV - plne elektrické vozidlá
Veľkosť feedu	Odporúčaný limit do 500 vozidiel na jeden feed. Pri väčšom objeme nás kontaktujte vopred.

3. Povinné polia

#	Pole	Typ	Popis	Príklad
1	id	string	Stabilný unikátny identifikátor vozidla v partnerskom systéme. Nesmie sa meniť počas životnosti inzerátu.	"0300172062"
2	brand	string	Značka vozidla	"Škoda"
3	model	string	Model vozidla, ideálne bez variantu (variant je samostatné pole nižšie).	"Model Y"
4	variant	string	Konkrétna verzia / výbavový stupeň. Príklad rozdelenia: značka Tesla · model Model Y · variant Long Range AWD. Ak váš systém model a variant nerozlišuje, uveďte ich spolu v poli model a toto pole vynechajte.	"Long Range AWD"
5	year_of_production	integer (YYYY)	Rok výroby vozidla. Pri nových autách rovnaký ako rok registrácie, pri ojazdených môže byť rozdielny.	2023
6	price	integer	Cena vozidla s DPH (bez medzier, len číslo)	536000
7	currency	string (ISO 4217)	Mena ceny	"EUR" alebo "CZK"
8	vat_deductible	boolean (0/1)	Možnosť odpočtu DPH	1
9	mileage_km	integer	Stav tachometra v km. Pre nové vozidlá 0.	55279
10	status	string	Aktuálny stav. Akceptujeme: active, available, reserved, sold.	"active"
11	photos[]	array of URLs	Minimálne 1 fotografia. Verejné HTTPS URL. Odporúčame 10+ fotiek pre lepšiu konverziu.	["https://.../1.jpg", "https://.../2.jpg"]

Validačné pravidlá pre povinné polia

• id nesmie obsahovať medzery alebo špeciálne znaky (povolené: A-Z, a-z, 0-9, dash, underscore)
• price musí byť > 0
• year_of_production musí byť medzi 2010 a aktuálnym rokom + 1
• mileage_km musí byť ≥ 0
• photos[] musí obsahovať aspoň 1 dostupnú HTTPS URL (nie HTTP, nie hot-link s blokovaním)

4. Odporúčané polia (z katalógu, ale ideálne dodať)

Pole	Typ	Prečo to chceme	Čo ak nedodáte
vin	string (17)	Najpresnejší identifikátor + jedinečnosť naprieč feedmi (dedup)	Použijeme model + variant matching
engine / powertrain	string	Továrenské označenie pohonu / motorizácie (nie len kapacita batérie). Spresňuje výber konkrétnej verzie v katalógu, napr. „Long Range Dual Motor" alebo „iV 60".	Skúsime odvodiť z modelu a variantu
battery_kwh	integer/float	Kapacita batérie v kWh	Z EV Database katalógu
wltp_range_km	integer	Dojazd podľa WLTP cyklu	Z EV Database katalógu
power_kw	integer	Výkon v kW	Z EV Database katalógu
body_type	string	Typ karosérie (SUV, Hatchback, Sedan, Coupe, Liftback, Combi, MPV, Pickup)	Z EV Database katalógu
drive	string	Typ pohonu (FWD, RWD, AWD, 4WD)	Z EV Database katalógu
seats	integer	Počet sedadiel	Z EV Database katalógu, ale nemusí to vždy sedieť (tá istá verzia môže mať variant s 5 aj so 7 sedadlami), preto je dobré ho tiež dodať

5. Voliteľné polia (špecifické pre konkrétny inzerát)

Tieto údaje nemáme v katalógu a sú špecifické pre dané vozidlo. Ak ich máte, pošlite ich - zvyšujú dôveryhodnosť inzerátu (najmä pri ojazdených vozidlách).

5.1 Registrácia vozidla a záruka batérie

Pole	Typ	Popis	Príklad
registration_year	integer (YYYY)	Rok prvej registrácie vozidla	2021
registration_month	integer (1-12)	Mesiac prvej registrácie (potrebné pre presný výpočet záruky)	5 (= máj)
battery_warranty	boolean (0/1)	Má vozidlo platnú záruku na batériu	1
battery_warranty_km	integer	Maximálny počet km pre záruku batérie (ak sa líši od defaultu výrobcu)	160000

5.2 SoH (State of Health) batérie

Pole	Typ	Popis	Príklad
soh	integer (0-100)	State of Health batérie v % (aktuálna kapacita vs. nová)	94
soh_certificate_url	URL	Odkaz na PDF / obrázok certifikátu o meraní SoH (Aviloo, Moba, výrobca atď.)	"https://.../soh-cert.pdf"
soh_measurement_date	date (YYYY-MM-DD)	Dátum, kedy bolo SoH merané (voliteľné, ale užitočné)	"2024-11-15"

5.3 Vzhľad vozidla

Pole	Typ	Popis	Príklad
color_exterior	string	Farba karosérie (slovne)	"čierna metalíza"
color_interior	string	Farba/typ interiéru	"čierna koža"
metallic	boolean (0/1)	Metalíza	1

5.4 Lokalita a predajca

Pole	Typ	Popis	Príklad
branch / location	string	Mesto/pobočka, kde sa vozidlo nachádza	"Bratislava"
address	string	Plná adresa (voliteľné)	"Pestovateľská 5, Bratislava"
gps_lat	float	GPS súradnice - latitude	48.1486
gps_lng	float	GPS súradnice - longitude	17.1077

5.5 Cenové detaily

Pole	Typ	Popis	Príklad
price_without_vat	integer	Cena bez DPH	442975
original_price	integer	Pôvodná cena pred zľavou (ak je vozidlo zľavnené)	580000

5.6 Dodatočné informácie

Pole	Typ	Popis	Príklad
doors	integer	Počet dverí. Tento údaj nemáme v katalógu, takže ho zobrazíme len ak ho dodáte.	5
description	string (text)	Voľný popis vozidla (môže obsahovať HTML break tags)	"Vozidlo v garantovanom stave..."
equipment[]	array of strings	Zoznam výbavy. Jeden item = jedna položka.	["navigácia", "tempomat", "kožené sedadlá"]
condition	string	Potrebujeme vedieť, či je auto nové, ojazdené alebo predvádzacie: new, used, demo	"used"

6. Príklady štruktúry

6.1 XML - minimálny príklad (len povinné polia)

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vehicle>
    <id>VIN123456789</id>
    <brand>Škoda</brand>
    <model>Enyaq</model>
    <variant>iV 60</variant>
    <year_of_production>2023</year_of_production>
    <price>536000</price>
    <currency>CZK</currency>
    <vat_deductible>1</vat_deductible>
    <mileage_km>55279</mileage_km>
    <status>active</status>
    <photos>
      <photo>https://partner.sk/img/123/1.jpg</photo>
      <photo>https://partner.sk/img/123/2.jpg</photo>
    </photos>
  </vehicle>
</feed>

6.2 XML - úplný príklad (so všetkými poľami)

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vehicle>
    <!-- POVINNÉ -->
    <id>VIN123456789</id>
    <brand>Škoda</brand>
    <model>Enyaq</model>
    <variant>iV 60</variant>
    <year_of_production>2023</year_of_production>
    <price>536000</price>
    <currency>CZK</currency>
    <vat_deductible>1</vat_deductible>
    <mileage_km>55279</mileage_km>
    <status>active</status>
    <photos>
      <photo>https://partner.sk/img/123/1.jpg</photo>
      <photo>https://partner.sk/img/123/2.jpg</photo>
    </photos>

    <!-- ODPORÚČANÉ (z katalógu) -->
    <vin>TMBJB7NY2NF022916</vin>
    <engine>iV 60 (RWD)</engine>
    <battery_kwh>62</battery_kwh>
    <wltp_range_km>412</wltp_range_km>
    <power_kw>132</power_kw>
    <body_type>SUV</body_type>
    <drive>RWD</drive>
    <seats>5</seats>

    <!-- REGISTRÁCIA + ZÁRUKA BATÉRIE -->
    <registration_year>2021</registration_year>
    <registration_month>5</registration_month>
    <battery_warranty>1</battery_warranty>
    <battery_warranty_km>160000</battery_warranty_km>

    <!-- SOH -->
    <soh>94</soh>
    <soh_certificate_url>https://partner.sk/cert/123-soh.pdf</soh_certificate_url>
    <soh_measurement_date>2024-11-15</soh_measurement_date>

    <!-- VZHĽAD -->
    <color_exterior>biela</color_exterior>
    <color_interior>čierna koža</color_interior>
    <metallic>1</metallic>

    <!-- LOKALITA -->
    <branch>Bratislava</branch>
    <gps_lat>48.1486</gps_lat>
    <gps_lng>17.1077</gps_lng>

    <!-- CENY -->
    <price_without_vat>442975</price_without_vat>

    <!-- DODATOČNÉ -->
    <doors>5</doors>
    <description><![CDATA[Vozidlo v perfektnom stave, prvý majiteľ.]]></description>
    <condition>used</condition>
    <equipment>
      <item>tepelné čerpadlo</item>
      <item>navigácia</item>
      <item>adaptívny tempomat</item>
      <item>panoramatická strecha</item>
    </equipment>
  </vehicle>
</feed>

6.3 JSON - ekvivalentný príklad

{
  "feed_version": "1.0",
  "generated_at": "2024-12-15T08:00:00Z",
  "vehicles": [
    {
      "id": "VIN123456789",
      "brand": "Škoda",
      "model": "Enyaq",
      "variant": "iV 60",
      "year_of_production": 2023,
      "price": 536000,
      "currency": "CZK",
      "vat_deductible": true,
      "mileage_km": 55279,
      "status": "active",
      "photos": [
        "https://partner.sk/img/123/1.jpg",
        "https://partner.sk/img/123/2.jpg"
      ],

      "vin": "TMBJB7NY2NF022916",
      "engine": "iV 60 (RWD)",
      "battery_kwh": 62,
      "wltp_range_km": 412,
      "power_kw": 132,
      "body_type": "SUV",
      "drive": "RWD",
      "seats": 5,

      "registration_year": 2021,
      "registration_month": 5,
      "battery_warranty": true,
      "battery_warranty_km": 160000,

      "soh": 94,
      "soh_certificate_url": "https://partner.sk/cert/123-soh.pdf",
      "soh_measurement_date": "2024-11-15",

      "color_exterior": "biela",
      "color_interior": "čierna koža",
      "metallic": true,

      "branch": "Bratislava",
      "gps_lat": 48.1486,
      "gps_lng": 17.1077,

      "price_without_vat": 442975,

      "doors": 5,
      "description": "Vozidlo v perfektnom stave, prvý majiteľ.",
      "condition": "used",
      "equipment": [
        "tepelné čerpadlo",
        "navigácia",
        "adaptívny tempomat",
        "panoramatická strecha"
      ]
    }
  ]
}

7. Quick checklist pred odoslaním feedu

• Feed obsahuje len BEV (plne elektrické) vozidlá
• Feed je dostupný cez verejnú HTTPS URL
• Encoding je UTF-8
• Každé vozidlo má stabilný unikátny id
• Každé vozidlo má vyplnený model a variant (samostatne, alebo spolu v poli model)
• Každé vozidlo má minimálne 1 fotku cez verejnú URL
• Každé vozidlo má cenu a menu
• Pole status obsahuje jednu z hodnôt: active / sold / reserved / available
• Pole year_of_production je vyplnené (rok výroby)
• Fotky nemajú zapnutý hotlink protection
• Feed sa generuje minimálne 1× denne

8. Často kladené otázky