Feed špecifikácia pre partnerov

Nearcharger je trh s elektromobilmi na Slovensku a v Česku. Tento dokument opisuje, ako nám posielať ponuku vozidiel cez feed a aké dáta vám na to dávame my. Nemusíte ho čítať celý: vyberte si, čo práve riešite.

Ako prebieha napojenie

1. Namapujte si katalógVoliteľné, ale najspoľahlivejšie: uložte si naše ID vozidiel a slugy číselníkov (A1 až A3).
2. Pripravte feedPodľa časti 1. Overte ho schémou a porovnajte s ukážkami (sekcia 9).
3. Pošlite nám URLNastavíme sťahovanie, pri vlastnej štruktúre aj mapovanie, a odovzdáme vám token.
4. Kontrolujte výsledokSpätný feed ukáže pri každom vozidle, či je zverejnené, a ak nie, prečo (A6).

Časť 1 Váš feed pre Nearcharger Čo nám posielate: štruktúra, polia, príklady a kontroly

1. Skôr než začnete

Vlastné názvy polí zvládneme. Ak použijete názvy z tohto dokumentu, mapovanie máme hotové a feed napojíme v deň, keď dostaneme jeho URL. Ak máte vlastnú štruktúru, pri onboardingu namapujeme vaše názvy aj hodnoty. Dôležité je, aby údaj vo feede bol.

Technické údaje berieme z katalógu. Keď vozidlo spárujeme s položkou nášho katalógu (vychádza z ev-database.org), doplníme mu z nej chýbajúce technické údaje. Vozidlo, ktoré v katalógu nie je, má len údaje z vášho feedu.

2. Technické požiadavky

3. Polia feedu

Tvrdá podmienka importu sú len tri veci: identifikátor, identita vozidla a cena. Ostatné polia inzerát nezablokujú, ale bez nich mu niečo chýba. Kliknutím na sekciu prejdete na podrobnosti.

3.1 Povinné: bez týchto polí inzerát nevznikne

3.2 Potrebné: bez nich inzerátu niečo chýba

Radšej zverejníme neúplný inzerát než žiadny, preto chýbajúce pole nikto nenahlási ako chybu. Pri každom poli je napísané, o čo inzerát príde.

3.3 Kontroly: čo sa stane pri chybe

Zlú hodnotu radšej vynecháme, než by sme kvôli nej zahodili celé vozidlo. Záznam odmietneme len v prvých šiestich prípadoch; v spätnom feede ho uvidíte ako error s kódom (A6.2).

4. Technické údaje vozidla

Väčšinu týchto údajov má náš katalóg. Pomáhajú nám však vozidlo s katalógom spárovať a pri vozidle mimo katalógu sú jediným zdrojom. Údaj o konkrétnom kuse (kapacita, dojazd, výkon, počet miest) má prednosť pred katalógom; pri karosérii a pohone platí katalóg a vaša hodnota je záloha.

5. Údaje o konkrétnom vozidle

Tieto údaje katalóg nemá, lebo patria konkrétnemu kusu. Pri ojazdenom vozidle výrazne zvyšujú dôveru kupujúceho.

5.1 Registrácia a záruka batérie

Zostávajúcu záruku na batériu počítame sami: od prvej registrácie odpočítame roky záruky spárovanej verzie z katalógu. Dátum konca záruky preto nepotrebujeme, stačí rok a mesiac registrácie.

5.2 Stav batérie (SoH)

SoH je pri ojazdenom elektromobile jeden z najdôležitejších údajov. Ak k meraniu máte certifikát, pošlite naň odkaz, stiahneme si ho k inzerátu.

5.3 Vzhľad a leasing

5.4 Lokalita a kontakt pobočky

Máte viac pobočiek? Pošlite ku každému vozidlu jeho mesto, súradnice a kontakt. Inak dostanú všetky vozidlá adresu a číslo z partnerského profilu a kupujúci zavolá na zlú pobočku.

5.5 Obsah inzerátu

6. Príklady

Úplný JSON s každým poľom. Rovnaké vozidlo v XML je nižšie, ukážkové feedy na stiahnutie v sekcii 9.

{
  "feed_version": "1.0",
  "generated_at": "2026-09-23T04:00:00Z",
  "vehicles": [
    {
      "id": "SK-2021-0457",
      "brand": "Škoda",
      "model": "Enyaq",
      "price": 21900,

      "photos": [
        "https://partner.sk/img/0457/1.jpg",
        "https://partner.sk/img/0457/2.jpg"
      ],
      "status": "active",
      "variant": "iV 60",
      "mileage_km": 55279,
      "year_of_production": 2021,
      "vat_deductible": true,
      "currency": "EUR",

      "catalog_id": 14914,
      "vin": "TMBJB7NY2NF022916",
      "engine": "iV 60 (RWD)",
      "battery_kwh": 62,
      "wltp_range_km": 413,
      "power_kw": 132,
      "body_type": "suv",
      "drive": "rear",
      "seats": 5,

      "registration_year": 2021,
      "registration_month": 5,
      "manufacture_month": 3,
      "battery_warranty_km": 160000,

      "soh": 94,
      "soh_certificate_url": "https://partner.sk/cert/0457-soh.pdf",
      "soh_measurement_date": "2026-08-15",

      "color_exterior": "white",
      "metallic": true,
      "continuation_of_leasing": false,

      "branch": "Bratislava",
      "address": "Pestovateľská 5, Bratislava",
      "gps_lat": 48.1486,
      "gps_lng": 17.1077,
      "contact_phone": "+421 900 123 456",
      "contact_email": "bratislava@partner.sk",

      "title": "Škoda Enyaq iV 60, tepelné čerpadlo, 1. majiteľ",
      "description": "Vozidlo v perfektnom stave, prvý majiteľ.",
      "condition": "used",
      "state": ["first-owner", "service-book"],
      "doors": 5,
      "equipment": ["heat-pump", "navigation", "adaptive-cruise-control", "panoramic-roof"],
      "equipment_unmapped": ["bočné airbagy"],
      "price_without_vat": 17805
    }
  ]
}

<?xml version="1.0" encoding="UTF-8"?>
<feed>
  <vehicle>
    <!-- 3.1 POVINNÉ -->
    <id>SK-2021-0457</id>
    <brand>Škoda</brand>
    <model>Enyaq</model>
    <price>21900</price>

    <!-- 3.2 POTREBNÉ -->
    <photos>
      <photo>https://partner.sk/img/0457/1.jpg</photo>
      <photo>https://partner.sk/img/0457/2.jpg</photo>
    </photos>
    <status>active</status>
    <variant>iV 60</variant>
    <mileage_km>55279</mileage_km>
    <year_of_production>2021</year_of_production>
    <vat_deductible>1</vat_deductible>
    <currency>EUR</currency>

    <!-- 4 TECHNICKÉ ÚDAJE -->
    <catalog_id>14914</catalog_id>
    <vin>TMBJB7NY2NF022916</vin>
    <engine>iV 60 (RWD)</engine>
    <battery_kwh>62</battery_kwh>
    <wltp_range_km>413</wltp_range_km>
    <power_kw>132</power_kw>
    <body_type>suv</body_type>
    <drive>rear</drive>
    <seats>5</seats>

    <!-- 5.1 REGISTRÁCIA A ZÁRUKA -->
    <registration_year>2021</registration_year>
    <registration_month>5</registration_month>
    <manufacture_month>3</manufacture_month>
    <battery_warranty_km>160000</battery_warranty_km>

    <!-- 5.2 BATÉRIA -->
    <soh>94</soh>
    <soh_certificate_url>https://partner.sk/cert/0457-soh.pdf</soh_certificate_url>
    <soh_measurement_date>2026-08-15</soh_measurement_date>

    <!-- 5.3 VZHĽAD A LEASING -->
    <color_exterior>white</color_exterior>
    <metallic>1</metallic>
    <continuation_of_leasing>0</continuation_of_leasing>

    <!-- 5.4 LOKALITA A KONTAKT -->
    <branch>Bratislava</branch>
    <address>Pestovateľská 5, Bratislava</address>
    <gps_lat>48.1486</gps_lat>
    <gps_lng>17.1077</gps_lng>
    <contact_phone>+421 900 123 456</contact_phone>
    <contact_email>bratislava@partner.sk</contact_email>

    <!-- 5.5 OBSAH INZERÁTU -->
    <title>Škoda Enyaq iV 60, tepelné čerpadlo, 1. majiteľ</title>
    <description><![CDATA[Vozidlo v perfektnom stave, prvý majiteľ.]]></description>
    <condition>used</condition>
    <state>
      <item>first-owner</item>
      <item>service-book</item>
    </state>
    <doors>5</doors>
    <equipment>
      <item>heat-pump</item>
      <item>navigation</item>
      <item>adaptive-cruise-control</item>
      <item>panoramic-roof</item>
    </equipment>
    <equipment_unmapped>
      <item>bočné airbagy</item>
    </equipment_unmapped>
    <price_without_vat>17805</price_without_vat>
  </vehicle>
</feed>

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

7. Checklist pred odoslaním

8. Časté otázky

9. Na stiahnutie

Obe ukážky spolu obsahujú každé pole z časti 1 a prejdú naším importom bez varovania. Schémy kontrolujú štruktúru a typy; čo import naozaj odmietne, je v 3.3.

Časť 2 Naše dáta pre vás (API) Katalóg a číselníky na mapovanie, feed vašich inzerátov a spätný feed

A1. Master data: prehľad a formáty

Master data sú verejný export nášho katalógu a číselníkov: značky, modely, verzie po výrobných rokoch, výbava, farby a ďalšie hodnoty, každá so stabilným ID a slugom. Uložte si ich ako mapovací kľúč a vo feede posielajte naše hodnoty namiesto voľného textu. Nie je potrebný žiadny token.

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

• Formát: ?format=json (predvolené) alebo ?format=xml, prípadne hlavička Accept: application/xml. Formát, filtre a stránkovanie sa dajú kombinovať, napríklad ?brand=mini&year=2024&format=xml.
• Stránkovanie (/catalog, A5, A6): ?page= a ?per_page=, predvolene 100, najviac 500 položiek na stránku.
• Obálka: stránkované odpovede majú schema_version, generated_at, page, total_pages, total_items a items. /brands, /equipment a /enums vracajú všetko naraz, len so schema_version, generated_at a items.

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

A2. Katalóg vozidiel (/catalog)

Položka katalógu je jedna verzia v jednom výrobnom roku, takže tá istá verzia vyrábaná viac rokov má viac položiek. Mapovací kľúč je id, nikdy sa nemení a vo feede ho posielate ako catalog_id.

{
  "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": "type-2",
  "ev_type": "bev",
  "price_eur": 34990,
  "range_wltp": 310,
  "battery_kwh": 42.5,
  "battery_kwh_usable": 40.7,
  "power_kw": 135,
  "power_hp": 184,
  "battery_warranty_years": 8,
  "battery_warranty_km": 160000,
  "seats": 5,
  "detail_url": "https://nearcharger.sk/..."
}

• version je null pri modeloch s jedinou verziou; identitu potom tvorí make + model + year. Záruka batérie je null, keď ju výrobca neudáva.
• battery_kwh je brutto kapacita (tak ju prijímame aj vo feede), battery_kwh_usable využiteľná. body_type, segment, drivetrain, charge_port a ev_type sú slugy z /enums.
• seats je počet miest podľa katalógu. Tá istá verzia sa vyrába s 5 aj so 7 miestami, preto posielajte vo feede skutočný počet; vaša hodnota má prednosť.

Filtre: ?brand= berie slug alebo ID značky či modelu presne tak, ako sú v /brands (napríklad mini, 125, aceman alebo 704), ?year= výrobný rok. Filtre platia súčasne a total_items zodpovedá výsledku po filtrovaní. Neznámy slug vráti prázdny zoznam.

GET https://nearcharger.sk/wp-json/nearcharger/v1/master-data/catalog?brand=mini&year=2024

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

Položka číselníka má stabilné id, anglický slug a názvy v troch jazykoch (cz je čeština). Vo feede posielajte slug: je rovnaký v každom jazyku.

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

Keď sa tento dokument a endpoint rozchádzajú v hodnote číselníka, platí endpoint.

A4. Stabilita, aktualizácia a limity

• Aktualizácia: master data aj feed inzerátov generujeme raz denne v noci, okolo 03:30 UTC. Stačí jeden pull denne, ideálne po 04:00 UTC.
• Cache: odpovede nesú ETag a Last-Modified. Pošlite ETag späť v If-None-Match a pri nezmenenom obsahu dostanete 304 Not Modified bez tela.
• Limity na IP adresu: 60 requestov za minútu spolu pre master data, 30 za minútu spolu pre feed inzerátov a spätný feed. Nad limitom vrátime 429.

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

Súkromný feed vašich zverejnených inzerátov, napríklad na kontrolu, čo je online, alebo na synchronizáciu do vášho systému. Chráni ho token, ktorý dostanete pri onboardingu. Skryté inzeráty v ňom nie sú, pre tie je spätný feed (A6). Formáty a stránkovanie ako v A1.

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

Číselníkové polia (color, condition, state, equipment, body_type, drivetrain, ev_type, market) obsahujú slugy z A3, nevyplnené polia sú null. Odpoveď má Cache-Control: private, no-store, podmienený request s If-None-Match však funguje a token overíme aj pred 304.

{
  "id": 58153,
  "source_id": "BMWSK-000123",
  "url": "https://nearcharger.sk/inzerat/...",
  "title": "Mini Aceman E, 2024",
  "description": "Vozidlo v perfektnom stave, prvý majiteľ, servisná knižka.",
  "status": "active",
  "market": "sk",
  "updated_at": "2026-09-22T03:30:11+00:00",
  "car_version_id": 15498,
  "car_version_slug": "mini-aceman-e-2190",
  "make": "Mini",
  "model": "Aceman",
  "version": "E",
  "year": 2024,
  "manufacture_month": 1,
  "registration_year": 2024,
  "registration_month": 3,
  "price": { "amount": 34990, "currency": "EUR", "vat_deductible": true },
  "mileage_km": 12000,
  "soh": 95.9,
  "soh_certificate_url": "https://nearcharger.sk/wp-content/uploads/soh-certifikat.pdf",
  "soh_measurement_date": "2026-08-14",
  "battery_kwh": 42.5,
  "range_wltp": 310,
  "battery_warranty_years": 8,
  "battery_warranty_km": 160000,
  "power_kw": 135,
  "body_type": "suv",
  "drivetrain": "front",
  "ev_type": "bev",
  "seats": 5,
  "color": "black",
  "doors": 5,
  "metallization": true,
  "continuation_of_leasing": false,
  "vin": "WMW21GF0XR2V15498",
  "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", "address": "Tuhovská 5, 831 07 Bratislava" },
  "contact": { "phone": "+421 900 123 456", "email": "predaj@vasadomena.sk", "name": null, "address": null }
}

A6. Spätný feed: čo sa stalo s každým vozidlom (token)

Jeden riadok na každé vozidlo, ktoré ste nám poslali, kľúčovaný na vaše id: naše ID inzerátu, URL, stav a pri vozidle, ktoré zostalo vonku, aj dôvod. Nie je to nočný snapshot, ukazuje stav hneď po poslednom behu importu, takže ho stačí skontrolovať raz po každom behu.

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

Rovnaký token, formáty a stránkovanie ako feed inzerátov. V XML je koreň <reconciliation>, riadky <items><item>, feedy <feeds><feed>. Cache funguje len cez obsahový ETag (Last-Modified sa neposiela). Kým váš feed nie je nastavený, payload je prázdny (items: [], generated_at: null).

{
  "schema_version": 1,
  "generated_at": "2026-09-23T04:05:12Z",
  "partner_id": 29540,
  "feeds": [
    {
      "feed_id": 12,
      "name": "MINI Slovakia",
      "market": "sk",
      "is_active": true,
      "last_sync_at": "2026-09-23T04:00:00Z",
      "last_sync_status": "ok",
      "last_sync_message": "",
      "listings": { "live": 3, "sold": 1, "orphaned": 0, "error": 1, "over_cap": 0 }
    }
  ],
  "summary": { "error": 1, "sold": 1, "unmatched": 1, "published": 2 },
  "page": 1,
  "total_pages": 1,
  "total_items": 5,
  "items": [
    {
      "source_id": "MINI-SK-000101",
      "vin": "WMW11DJ0XP2R00101",
      "status": "published",
      "our_post_id": 58153,
      "url": "https://nearcharger.sk/inzerat/mini-cooper-se-2024/",
      "error_code": "",
      "error_message": "",
      "photos_sent": 12,
      "photos_imported": 12,
      "warnings": [],
      "car_version_id": 15344,
      "match_method": "catalog_id",
      "match_score": 1,
      "adopted_at": null,
      "sold_at": null,
      "orphaned_at": null,
      "last_seen_in_feed": "2026-09-23T04:00:41Z",
      "last_changed": "2026-09-21T04:00:37Z",
      "last_synced": "2026-09-23T04:00:41Z"
    },
    {
      "source_id": "MINI-SK-000105",
      "vin": "WMW11DJ0XP2R00105",
      "status": "error",
      "our_post_id": null,
      "url": null,
      "error_code": "validation",
      "error_message": "missing_required: price.amount",
      "photos_sent": null,
      "photos_imported": null,
      "warnings": [],
      "car_version_id": null,
      "match_method": "none",
      "match_score": null,
      "adopted_at": null,
      "sold_at": null,
      "orphaned_at": null,
      "last_seen_in_feed": "2026-09-23T04:00:41Z",
      "last_changed": null,
      "last_synced": "2026-09-23T04:00:41Z"
    }
  ]
}

A6.1 Stavy

Presne jeden stav na riadok; vyhráva prvý, ktorý sedí (zhora nadol).

A6.2 Kódy chýb

A6.3 Varovania

Varovanie nemení stav, len hovorí, čo inzerátu chýba.

A6.4 Polia riadku a stav feedu