Feed špecifikácia pre partnerov

A1. Master data API - prehľad a discovery

Vstupný bod je discovery index - jedna URL, ktorá vráti zoznam všetkých dostupných feedov, ich verziu a čas poslednej generácie:

GET https://nearcharger.sk/wp-json/nearcharger/v1/master-data

Endpoint	Obsah
/master-data	Discovery index - zoznam feedov, schema_version, URL, generated_at
/master-data/catalog	Katalóg vozidiel (variant + výrobný rok = 1 položka), stránkovaný, filtre ?brand= a ?year=
/master-data/brands	Strom značka → model so stabilnými ID a slugmi
/master-data/equipment	Výbava - kategórie + položky
/master-data/enums	Ostatné číselníky: pohon, karoséria, segment, nabíjací port, stav inzerátu, trh, typ inzerátu, stav vozidla, farby, sedadlá, dvere

Formáty a stránkovanie

• Formát: ?format=json (default) alebo ?format=xml. Akceptujeme aj hlavičku Accept: application/xml.
• Stránkovanie (len /catalog a partner feed): ?page= a ?per_page=, maximum 500 položiek na stránku.
• Všetky odpovede majú spoločnú obálku (envelope):

{
  "schema_version": 1,
  "generated_at": "2026-07-07T03:30:00+02:00",
  "page": 1,
  "total_pages": 3,
  "total_items": 1101,
  "items": [ ... ]
}

A2. Katalóg vozidiel (/catalog)

Každá položka katalógu je konkrétny variant v konkrétnom výrobnom roku. Ten istý variant vyrábaný vo viacerých rokoch má teda viacero položiek - každá s vlastným id. Mapovací kľúč je id (stabilné, nikdy sa nemení).

{
  "id": 15498,
  "slug": "mini-aceman-e-2190",
  "make": "Mini",
  "model": "Aceman",
  "version": "E",
  "year": 2024,
  "parent_model_slug": "mini-aceman",
  "brand_id": 125,
  "model_id": 704,
  "body_type": "suv",
  "segment": "jb-small",
  "drivetrain": "front",
  "charge_port": "ccs",
  "price_eur": 34990,
  "range_wltp": 310,
  "battery_kwh": 42.5,
  "power_kw": 135,
  "power_hp": 184,
  "battery_warranty_years": 8,
  "battery_warranty_km": 160000,
  "detail_url": "https://nearcharger.sk/..."
}

Filtre

• ?brand=mini - slug alebo číselné ID značky či modelu (z /brands)
• ?year=2024 - konkrétny výrobný rok

A3. Číselníky (/brands, /equipment, /enums)

Každá položka číselníka má stabilné id, anglický slug a názvy v troch jazykoch:

{
  "id": 87,
  "slug": "heat-pump",
  "names": { "en": "Heat Pump", "sk": "Tepelné čerpadlo", "cz": "Tepelné čerpadlo" }
}

• /brands - strom značka → model. Značky a modely sú vlastné mená (v každom jazyku rovnaké), preto majú namiesto names objektu len jedno pole name: { "id": 125, "slug": "mini", "name": "Mini", ... }. Pole aliases je rezervované pre alternatívne zápisy (napr. VW vs. Volkswagen), v aktuálnej verzii je prázdne.
• /equipment - výbava v kategóriách (kategória má items).
• /enums - pohon (drivetrain), karoséria (body_type), segment, nabíjací port (charge_port), stav inzerátu (listing_status), trh (market), typ EV (ev_type), typ inzerátu (ad_listing_type: nové / ojazdené / predvádzacie), stav vozidla (listing_state: napr. first-owner, service-book, imported-vehicle, crashed) + kanonické hodnoty color, seats a doors.

A4. Stabilita, verzie a caching

HTTP caching a odporúčaný pull

• Snapshoty generujeme raz denne v noci (okolo 03:30). Odporúčaný režim je nočný / ranný full pull, dáta sa počas dňa nemenia.
• Odpovede nesú ETag aj Last-Modified. Posielajte If-None-Match - ak sa obsah nezmenil, dostanete 304 Not Modified bez tela a ušetríte prenos.
• Endpointy sú rate-limitované per IP. Pri nočnom pulle sa limitov nedotknete; ak potrebujete výrazne vyššiu frekvenciu, ozvite sa nám.

A5. Feed vašich inzerátov (token)

Pre každého partnera vieme vygenerovať súkromný feed jeho zverejnených inzerátov na Nearchargeri - napríklad na kontrolu, čo je práve online, alebo na synchronizáciu do vášho systému. Feed je chránený statickým tokenom, ktorý vám odovzdáme pri onboardingu:

GET https://nearcharger.sk/wp-json/nearcharger/v1/partner/{id}/listings?key={token}

Bez platného tokenu vráti API 401. Feed obsahuje len verejné údaje inzerátu (žiadne kontaktné údaje) a používa rovnakú štruktúru vozidla ako váš inbound feed:

{
  "id": 15498,
  "url": "https://nearcharger.sk/inzerat/...",
  "title": "Mini Aceman E, 2024",
  "status": "active",
  "car_version_id": 9876,
  "car_version_slug": "mini-aceman-e-2190",
  "make": "Mini",
  "model": "Aceman",
  "version": "E",
  "year": 2024,
  "price": { "amount": 34990, "currency": "EUR", "vat_deductible": true },
  "mileage_km": 12000,
  "color": "black",
  "vin": "...",
  "condition": "used",
  "state": ["first-owner", "service-book"],
  "equipment": ["heat-pump", "matrix-led"],
  "images": { "main": "https://...", "gallery": ["https://...", "https://..."] },
  "location": { "lat": 48.1, "lng": 17.1, "city": "Bratislava" }
}

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). Ideálne kanonický slug z /master-data/enums (napr. black, pearl-white) - voľný text namapujeme pri onboardingu.	"č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. Ideálne posielajte naše slugy z /master-data/equipment (napr. heat-pump) - vlastné názvy namapujeme pri onboardingu.	["navigácia", "tempomat", "kožené sedadlá"]
condition	string	Potrebujeme vedieť, či je auto nové, ojazdené alebo predvádzacie: new, used, demo	"used"
state[]	array of strings	Stavové príznaky vozidla (viac naraz). Ideálne posielajte naše slugy z /master-data/enums (skupina listing_state): napr. first-owner, service-book, imported-vehicle, crashed - voľný text namapujeme pri onboardingu.	["first-owner", "service-book"]

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>
    <state>
      <item>first-owner</item>
      <item>service-book</item>
    </state>
    <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",
      "state": ["first-owner", "service-book"],
      "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

9. Na stiahnutie

Pre self-service validáciu feedu ešte pred odoslaním ponúkame strojovo čitateľné definície listing template (časť B):

Súbor	Popis
listing-template.schema.json	JSON Schema (draft 2020-12) pre JSON feed - zvalidujete si feed napr. cez ajv alebo online validátor
listing-template.xsd	XSD schéma pre XML feed - validácia cez xmllint --schema alebo ľubovoľný XML nástroj