1. Úvod

Partner API slouží pro integraci odhadu ceny vozidla do vašeho systému. Odpovědi jsou minimalizované (cena v CZK; volitelně průměrné km, pokud máte povolení).

2. Autentizace

Každé volání musí obsahovat bezpečnostní klíč v HTTP headeru:

X-OO-Partner-Key: {VÁŠ_KLÍČ}

3. Rate limiting

• Per minuta: max. počet volání za minutu
• Per den: max. počet volání za den

Při překročení limitu vrací API 429 Too Many Requests.

4. Katalog vozidel

API používá číselníky výrobců a modelů. Vždy používejte manufacturer_id a model_id získané z katalogu.

4.1 Seznam výrobců

GET http://www.megasjednavac.cz/api/v1/catalog/manufacturers
X-OO-Partner-Key: {VÁŠ_KLÍČ}

{"ok":true,"data":{"manufacturers":[{"id":123,"name":"Škoda"}]}}

4.2 Modely výrobce

GET http://www.megasjednavac.cz/api/v1/catalog/models?manufacturer_id={MANUFACTURER_ID}
X-OO-Partner-Key: {VÁŠ_KLÍČ}

{"ok":true,"data":{"manufacturer_id":123,"models":[{"id":456,"name":"Octavia"}]}}

4.3 Plný katalog

GET http://www.megasjednavac.cz/api/v1/catalog/full
X-OO-Partner-Key: {VÁŠ_KLÍČ}

{"ok":true,"data":{"manufacturers":[{"id":123,"name":"Škoda","models":[{"id":456,"name":"Octavia"}]}]}}

5. Odhad ceny

POST http://www.megasjednavac.cz/api/v1/estimate
X-OO-Partner-Key: {VÁŠ_KLÍČ}
Content-Type: application/json

Request body

{"manufacturer_id":{MANUFACTURER_ID},"model_id":{MODEL_ID},"year":{YEAR},"mileage":{MILEAGE_KM},"power_kw":{POWER_KW}}

Response (úspěch)

{"ok":true,"data":{"price_czk":123456}}

Poznámka: Pokud máte povolení, může se vracet i avg_mileage_km.

5.1 Rychlý test (Škoda Octavia 2020)

Tento příklad je připravený tak, aby fungoval i bez znalosti ID. Skript si nejdříve stáhne katalog, dohledá manufacturer_id pro Škoda a model_id pro Octavia, a pak rovnou zavolá odhad.

Konfigurace: rok 2020, nájezd 150 000 km, výkon 110 kW

PowerShell (doporučené)

$key = "{VÁŠ_KLÍČ}"
    $base = "http://www.megasjednavac.cz/api/v1"

    $mfr = Invoke-RestMethod -Method GET -Uri "$base/catalog/manufacturers" -Headers @{"X-OO-Partner-Key"=$key}
    $skoda = $mfr.data.manufacturers | Where-Object { $_.name -eq "Škoda" } | Select-Object -First 1
    if (-not $skoda) { throw "Škoda not found in catalog" }

    $models = Invoke-RestMethod -Method GET -Uri "$base/catalog/models?manufacturer_id=$([string]$skoda.id)" -Headers @{"X-OO-Partner-Key"=$key}
    $octavia = $models.data.models | Where-Object { $_.name -eq "Octavia" } | Select-Object -First 1
    if (-not $octavia) { throw "Octavia not found in catalog" }

    $body = @{ manufacturer_id = [int]$skoda.id; model_id = [int]$octavia.id; year = 2020; mileage = 150000; power_kw = 110 } | ConvertTo-Json
    $res = Invoke-RestMethod -Method POST -Uri "$base/estimate" -Headers @{"X-OO-Partner-Key"=$key; "Content-Type"="application/json"} -Body $body
    $res | ConvertTo-Json -Depth 6

curl (alternativa)

curl varianta je dvoukroková (nejdřív katalog, potom estimate). ID si prosím vezměte z odpovědí:

curl -s -H "X-OO-Partner-Key: {VÁŠ_KLÍČ}" "http://www.megasjednavac.cz/api/v1/catalog/manufacturers"

curl -s -H "X-OO-Partner-Key: {VÁŠ_KLÍČ}" "http://www.megasjednavac.cz/api/v1/catalog/models?manufacturer_id={MANUFACTURER_ID_SKODA}"

curl -s -X POST -H "X-OO-Partner-Key: {VÁŠ_KLÍČ}" -H "Content-Type: application/json" 
    -d '{"manufacturer_id":{MANUFACTURER_ID_SKODA},"model_id":{MODEL_ID_OCTAVIA},"year":2020,"mileage":150000,"power_kw":110}' 
    "http://www.megasjednavac.cz/api/v1/estimate"

6. Chyby

7. Bezpečnost

• Partner API nevrací interní debug data ani interní kalkulace.
• Katalog vrací pouze id a name (bez interních metrik).
• avg_mileage_km se vrací pouze partnerům s explicitním povolením.
• Chyby jsou generické, bez úniku interních detailů.

8. Monitoring

Každé volání vrátí hlavičku X-OO-Request-Id. Uložte si ji pro debugging.

Děkujeme za partnerství.