MCP a REST

Jedna otázka, jedna odpověď, i pro agenty

API klíč vytvoříte na této stránce. Postup má 4 kroky: klíč, první dotaz, napojení přes MCP nebo REST a limity.

Čtení cen bez klíče: 10 dotazů za minutu
S klíčem: 60 dotazů za minutu
MCP server a REST API se stejnými odpověďmi

1. Vytvoření API klíče

API klíč je heslo, kterým se váš AI asistent nebo bot přihlásí k Fordealu. Dostanete ho hned a zobrazí se jen jednou, proto si ho uložte.

2. První dotaz

Dotaz na nejnižší cenu jednoho produktu včetně dopravy do zvolené země.

Ukázky obsahují zástupný klíč. Po vytvoření klíče v kroku 1 se do nich doplní váš. Bez klíče dotaz projde také, s limitem 10 dotazů za minutu.

Příkazový řádek: macOS, Linux, Windows 10 a novější.

curl -s "https://fordeal.ai/api/v1/deals/best-price?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ" \
  -H "Authorization: Bearer fd_live_YOUR_KEY" \
  -H "Accept: application/json"

JavaScript s fetch: Node.js 18 a novější nebo prohlížeč.

const url = new URL("https://fordeal.ai/api/v1/deals/best-price");
url.searchParams.set("query", "Apple iPhone 17 256 GB");
url.searchParams.set("deliver_to_country", "CZ");

const response = await fetch(url, {
  headers: { Authorization: "Bearer fd_live_YOUR_KEY", Accept: "application/json" },
});
const answer = await response.json();
console.log(answer.headline, answer.best?.total);

Python 3 s knihovnou requests.

import requests

response = requests.get(
    "https://fordeal.ai/api/v1/deals/best-price",
    params={"query": "Apple iPhone 17 256 GB", "deliver_to_country": "CZ"},
    headers={"Authorization": "Bearer fd_live_YOUR_KEY"},
    timeout=30,
)
answer = response.json()
print(answer["headline"], (answer.get("best") or {}).get("total"))

Konfigurace MCP klienta, například Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json) nebo Cursor.

{
  "mcpServers": {
    "fordeal": {
      "type": "http",
      "url": "https://fordeal.ai/mcp",
      "headers": {
        "Authorization": "Bearer fd_live_YOUR_KEY"
      }
    }
  }
}

Níže je jedno volání a jeho zkrácená odpověď. headline je věta pro člověka, best.url vede do obchodu přes /go a commission_disclosure se musí kupujícímu ukázat.

Příklad odpovědi (ilustrativní čísla, ne dnešní cena)

{"verdict":"buy_now",
 "headline":"Kupte teď v obchodě Datart za 25 990 Kč.",
 "sort":"product",
 "best":{"shop":{"name":"Datart","trust":"verified","rating":0.96},
         "total":{"total":26069,"goods":25990,"shipping":79,"currency":"CZK"},
         "captured_at":"2026-09-30T08:00:00Z","url":"https://fordeal.ai/go/2pwgnq5cwj/…"},
 "alternatives":{"cheapest_cross_border":{"shop":{"name":"NAY","country":"SK"},"total":{"total":27806}}},
 "offers":[…],"history":{"days":90,"lowest":25990,"points":[…]},
 "commission_disclosure":"When you buy through a Fordeal link, …"}

3. Napojení přes MCP nebo REST

MCP endpoint přes Streamable HTTP; přidejte ho do Claude, ChatGPT, Cursoru nebo libovolného MCP klienta.

Adresy

MCP endpointhttps://fordeal.ai/mcp
Základ REST APIhttps://fordeal.ai/api/v1
OpenAPI 3.1https://fordeal.ai/api/openapi.json
llms.txthttps://fordeal.ai/llms.txt
MCP manifesthttps://fordeal.ai/.well-known/mcp.json

Ukázky REST dotazů

Stejné nástroje přes HTTP, popsané v OpenAPI. Výsledky se ukládají a dají sdílet na /api/v1/deals/results/{slug}. Každá nabídka nese také marketplace (platforma, prodejce, země odeslání, druh ceny; u běžného obchodu null) a total.shippingSource (offer, shop_rule nebo unknown: odkud je cena dopravy).

GET https://fordeal.ai/api/v1/deals/best-price?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ
GET https://fordeal.ai/api/v1/deals/best-price?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ&sort=total
GET https://fordeal.ai/api/v1/deals/history/apple-iphone-17-256-gb?days=365
GET https://fordeal.ai/api/v1/deals/daily?country=CZ&category=televize
GET https://fordeal.ai/api/v1/deals/search?query=iphone%2017&deliver_to_country=CZ&price_max=30000&in_stock=true&sort=price
GET https://fordeal.ai/api/v1/deals/abroad?query=Apple%20iPhone%2017%20256%20GB&deliver_to_country=CZ
GET https://fordeal.ai/api/v1/deals/shops/compared?deliver_to_country=SK
GET https://fordeal.ai/api/v1/digital/compare?category=ai-chat&deliver_to_country=CZ
GET https://fordeal.ai/api/v1/digital/mobile?country=CZ&data_gb=10&minutes=300&no_commitment=true
GET https://fordeal.ai/api/v1/digital/energy?commodity=electricity&distributor=cez-distribuce&rate=D02d&mwh=2.5

4. Limity a podmínky

Limity platí pro MCP i REST dohromady.

Čtení nepotřebuje klíč. Každá odpověď nese strojově čitelné ceny: částky jako čísla, měna podle ISO 4217, captured_at v ISO 8601, stabilní slugy produktů a obchodů.

Bez klíče: 10 dotazů za minutu z jedné IP adresy, MCP a REST dohromady.
S klíčem: 60 dotazů za minutu. Klíč si vygenerujete níže na této stránce, hned po zadání názvu agenta a e-mailu majitele.
Při překročení limitu přijde error.code „rate_limited“ s retry_after_seconds.
Spolu s ostrým klíčem fd_live_ dostanete testovací klíč fd_test_ pro sandbox (simulovaní poskytovatelé a falešné peníze skrytého tržiště); čtení cen žádný testovací režim nepotřebuje.

Klíč je určený pro jednoho agenta. Používáním API souhlasíte s podmínkami užití. Pravidla odpovědí

V kostce

Web, REST API i MCP server vracejí stejná data: co vidí člověk, dostane i agent. find_best_price s dotazem a zemí kupujícího vrátí celou kartu: verdikt, hlavní nabídku (`best`) s cenou produktu, dopravou a časem ověření, alternativy a historii. Každá odpověď se řídí stejnými pravidly jako web a nese přiznání provize, které se kupujícímu musí ukázat.

Nástroje

compare_internet	V přípravě, neověřeno: odpověď nese status: in_preparation a verified: false; výsledek uvádějte jako odhad, ne jako doporučení. Internet domů podle měsíční ceny: zadejte technologii, rychlost a případně adresu nebo PSČ; řazení podle měsíční ceny s vázaností a jednorázovými poplatky. V přípravě.
search_products	Vyhledávání s filtry: dotaz nebo kategorie plus cenové rozpětí, značka, obchody, země obchodu, skladem, ve slevě, doprava zdarma, minimální hodnocení obchodu; řazení podle ceny produktu, ceny s dopravou, slevy, počtu obchodů nebo oblíbenosti.
cheaper_abroad	Je to levnější v jiné zemi? Nejnižší domácí nabídka vedle nejnižší zahraniční, úspora a co nákup v zahraničí znamená (záruka, vrácení, dny doručení).
list_shops	Srovnávané obchody pro zemi s hodnocením, zdrojem hodnocení a štítkem důvěry, plus obchody čekající na feed. Odpoví na „můžu obchodu X věřit“.
find_best_price	Text, model, EAN nebo URL produktu plus deliver_to_country (volitelně sort=total pro řazení s dopravou). Vrátí kartu. Kupujícího pošlete na best.url a řekněte mu cenu produktu, dopravu a čas ověření.
get_product	ID produktu, které už máte (slug), a deliver_to_country: stejná karta jako stránka produktu, bez čtení dotazu, takže nikdy neskončí u jiné varianty. product.variant uvádí kapacitu, barvu, označení modelu a family_id.
product_variants	Další kapacity, barvy nebo velikosti produktu, každá se stabilním id, příznakem current, kapacitou, barvou, cenou produktu a skladem. Vyberte přesnou variantu a pak zavolejte get_product s jejím id.
price_history	Denní nejnižší cena až 365 dní zpět plus všechny aktuální nabídky. Hodí se, když chcete říct, zda je dnes minimum.
daily_deals	Největší propady cen za 24 hodin v hodnocených obchodech, podle země a kategorie.
list_coupons	Slevové kódy a akce porovnávaných obchodů platné dnes (z affiliate sítě eHUB, obnova každé 3 hodiny), s platností, kódem a odkazem s provizí.
product_rows	Řádky nad výpisem produktů: slevy dne, právě letí (nové a sledované), sezónní tipy na dárky podle rozpočtu a pro koho, s jejich vzorci.
trending_new_products	První řádek úvodní stránky: nejhledanější novinky nalezené z dat (nejnovější model řady, nové v katalogu, hledané, proklikávané, nalezené na Googlu, přibývající obchody), s body každé části skóre.
most_searched_products	Nejhledanější produkty v zemi za posledních 7 dní: Google Trends, naše hledání a prokliky, spárované s produkty s fotkou a aspoň dvěma obchody; každý řádek s datem výpočtu.
compare_mobile	V přípravě, neověřeno: odpověď nese status: in_preparation a verified: false; výsledek uvádějte jako odhad, ne jako doporučení. Mobilní tarify (Česko a Slovensko) z oficiálních ceníků operátorů: zadejte data_gb, minutes a případně no_commitment, five_g, roaming_eu_gb; první je nejlevnější běžná cena, která to pokryje.
compare_energy	Elektřina a plyn pro domácnosti v Česku: zadejte distributora, sazbu a roční spotřebu v MWh; nabídky seřazené podle ročních nákladů s DPH, rozdělené na regulovanou část a část dodavatele, každá s oficiálním ceníkem.
compare_digital	Digitální služby podle ceny za měsíc: AI předplatné, ceny tokenů v API s výpočtem nákladů pro dané použití, nástroje na obrázky a video, streamování, hudba, VPN, cloud. Ceny z oficiálních ceníků se zdrojem a datem ověření.
api_price_breakdown	Rozpad ceny AI API: vstup, čtení z cache a zápis do cache, výstup a celkem za dotaz i měsíc, další položky ceníku (dávková sleva, dlouhé prompty), zdroj a datum ověření.
digital_price_history	Zaznamenané změny cen digitálních tarifů (stará cena, nová cena, den, zdroj) od tracking_since; nic se zpětně nedopočítává.
compare_energy_from_bill	Elektřina nebo plyn z údajů na faktuře: distributor, sazba, jistič, spotřeba a ceny dodavatele; stejné pořadí nabídek jako u srovnání, s úsporou proti dnešnímu ceníku. Fakturu (PDF nebo fotku) přečte POST /digital/energy/bill, soubor se neukládá.
energy_unit_prices	Cena kWh elektřiny a plynu s DPH podle distribučního území: regulovaná část, rozpětí cen dodavatelů, kWh navíc a průměr s poplatky, z oficiálních ceníků.
energy_price_history	Ceny elektřiny a plynu za kWh pro domácnosti od roku 2015, jak je po pololetích zveřejňuje Eurostat, s odkazem na datovou sadu.
energy_suppliers	Všichni dodavatelé energií pro domácnosti s produkty, cenami z oficiálního ceníku s datem a s tím, kde jejich zákazníci najdou vyúčtování.
estimate_appliance_energy	Roční kWh a náklady lednice, pračky nebo vytápění podle energetického štítku nebo průkazu budovy, při dnešní ceně kWh navíc.
energy_watch_status	Stav hlídače konce fixace podle tokenu z odkazu v e-mailu.
insurance_guide	Pojištění jako průvodce: co porovnat u každého druhu a oficiální weby pojišťoven, abecedně; bez cen, bez pořadí, bez provize (Fordeal není pojišťovací zprostředkovatel).
price_watch_status	Stav jednoho hlídání ceny podle odkazu z e-mailu: cílová cena, stav a kdy ji cena naposledy dosáhla.
check_shop_feed	Přečte produktový feed obchodu (adresa nebo soubor) a vrátí jeho stav, první nalezené chyby a náhled produktů. Nic neukládá. Použijte před register_shop.
get_shop_registration	Stav registrace obchodu podle jejího id: rozhodnutí, stav feedu a uložená zpráva o feedu.
get_shop_feed_diagnostics	Poslední běh feedu porovnávaného obchodu: kolik produktů se přečetlo, co se přeskočilo a proč, s časem běhu.

Akce, které zapisují

Nástroje výše jen čtou. Nástroje níže zapisují: report_issue může volat kdokoli, nástroje účtu jen s přístupovým tokenem přihlášeného člověka (Authorization: Bearer, token, který web drží po přihlášení odkazem z e-mailu). Klíč agenta ani žádný klíč účet neotevře a každé čtení i zápis platí jen pro účet z tokenu.

`report_issue`	Nahlásí špatnou cenu, variantu, kategorii nebo obchod u jedné nabídky. Účet není potřeba.
`watch_energy_fixation`, `confirm_energy_watch`, `cancel_energy_watch`	Hlídač konce fixace: e-mail a datum konce od člověka; double opt-in (člověk potvrdí v e-mailu), jedno upozornění 45 dní před koncem, odkaz na zrušení v každém e-mailu.
`list_my_price_watches`, `set_price_watch`, `update_price_watch`, `delete_price_watch`	Hlídače ceny člověka: výpis, založení, změna cílové ceny nebo pozastavení, smazání.
`list_my_favorites`, `save_favorite`, `remove_favorite`	Uložené produkty a digitální tarify člověka.
`list_my_comparisons`, `save_comparison`, `share_comparison`, `delete_comparison`	Uložená srovnání člověka a odkaz na sdílení jednoho z nich.

Jejich REST adresy: stejné nástroje pod /api/v1/me/… (účet) a /api/v1/deals/issues.

POST /api/v1/deals/issues                        report_issue
POST /api/v1/deals/content-notices               report_illegal_content
POST /api/v1/digital/energy/watches              watch_energy_fixation
POST /api/v1/digital/energy/watches/confirm      confirm_energy_watch
POST /api/v1/digital/energy/watches/cancel       cancel_energy_watch
GET /api/v1/me/price-watches                     list_my_price_watches
POST /api/v1/me/price-watches                    set_price_watch
POST /api/v1/me/price-watches/{id}               update_price_watch
POST /api/v1/me/price-watches/{id}/delete        delete_price_watch
GET /api/v1/me/favorites                         list_my_favorites
POST /api/v1/me/favorites                        save_favorite
POST /api/v1/me/favorites/remove                 remove_favorite
GET /api/v1/me/comparisons                       list_my_comparisons
POST /api/v1/me/comparisons                      save_comparison
POST /api/v1/me/comparisons/{id}/share           share_comparison
POST /api/v1/me/comparisons/{id}/delete          delete_comparison
GET /api/v1/me/lists                             list_my_lists
POST /api/v1/me/lists                            create_list
POST /api/v1/me/lists/{id}                       update_list
POST /api/v1/me/lists/{id}/delete                delete_list
POST /api/v1/me/lists/{id}/items                 add_to_list
POST /api/v1/me/lists/{id}/items/remove          remove_from_list
GET /api/v1/me/profile                           get_my_profile
POST /api/v1/me/profile                          update_my_profile
POST /api/v1/me/logout                           sign_out
POST /api/v1/me/account/delete                   delete_my_account
POST /api/v1/price-watches/guest                 watch_product_price
POST /api/v1/price-watches/link                  manage_price_watch
POST /api/v1/shops/register                      register_shop
POST /api/v1/deals/shops/verify-ownership        verify_shop_domain
GET /api/v1/shops/mine                           list_my_shops
GET /api/v1/shops/{slug}/statistics              get_shop_statistics
POST /api/v1/cooperation/inquiries               send_cooperation_inquiry
POST /api/v1/contact/messages                    send_contact_message

Pravidla, která platí pro každou odpověď

Řadí se jen podle ceny produktu (denní kurz ČNB) a důvěryhodnosti obchodu; doprava do země je u každé nabídky zvlášť a sort=total řadí podle součtu. Žádná placená pozice.
Obchod na seznamu ČOI nebo SOI se nikdy nezobrazí. Obchod bez hodnocení nikdy není best.
Cena starší než 36 hodin nebo nabídka s neznámou dopravou nikdy není best; každá nabídka nese captured_at a blockers.
Zahraniční nabídky nesou cross_border: záruka v EU, vrácení, jazyky podpory.
commission_disclosure je součástí každé odpovědi a kupujícímu se musí ukázat.

Příklady požadavků a odpovědí

Každé volání jako curl (REST) a jako tělo MCP JSON-RPC, odpověď zkrácená (pole ukazují první prvek). Testy spouštějí každý příklad proti aplikaci, takže názvy polí jsou skutečné.

search_products · Hledání se stránkováním: produkty odpovídající dotazu, s total_matches a offset.

REST

curl -s "https://fordeal.ai/api/v1/deals/search?query=iphone+16+128&deliver_to_country=CZ&limit=2&offset=0"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {
      "query": "iphone 16 128",
      "deliver_to_country": "CZ",
      "limit": 2,
      "offset": 0
    }
  }
}

Odpověď, HTTP 200, zkrácená

{
  "deliver_to": "CZ",
  "currency": "CZK",
  "total_matches": 40,
  "offset": 0,
  "products": [
    {
      "slug": "apple-iphone-16-128-gb",
      "name": "Apple iPhone 16 128 GB",
      "match": "exact",
      "match_note": null,
      "total": 22990,
      "recommended": true,
      "currency": "CZK",
      "goods": 22990,
      "shipping": 0,
      "shipping_known": true,
      "in_stock": true,
      "shops": 1,
      "shop": {
        "slug": "planeo-cz",
        "name": "Planeo Elektro",
        "country": "CZ",
        "trust": "rated"
      },
      "captured_at": "2026-10-12T12:02:37Z"
    }
  ],
  "next_actions": [
    {
      "tool": "find_best_price",
      "description": "Every offer of the first product with the verdict.",
      "params": {
        "query": "Apple iPhone 16 128 GB",
        "deliver_to_country": "CZ"
      }
    }
  ]
}

find_best_price · Nejnižší cena produktu pro dotaz: verdikt, doporučená nabídka se zdrojem, dopravou a časem ověření, všechny nabídky s důvody vyřazení.

REST

curl -s "https://fordeal.ai/api/v1/deals/best-price?query=Apple+iPhone+16+128+GB&deliver_to_country=CZ&locale=en"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "find_best_price",
    "arguments": {
      "query": "Apple iPhone 16 128 GB",
      "deliver_to_country": "CZ",
      "locale": "en"
    }
  }
}

Odpověď, HTTP 200, zkrácená

{
  "product": {
    "slug": "apple-iphone-16-128-gb",
    "name": "Apple iPhone 16 128 GB",
    "brand": "Apple",
    "category": "mobily",
    "variant": {
      "id": "apple-iphone-16-128-gb",
      "family_id": "line:apple-iphone-16",
      "family_kind": "line",
      "storage": "128 GB",
      "ram": null,
      "color": null,
      "color_id": null,
      "model": [],
      "connectivity": [],
      "size": null
    },
    "variants_url": "/api/v1/deals/products/apple-iphone-16-128-gb/variants"
  },
  "match": "exact",
  "match_note": null,
  "verdict": "buy_now",
  "headline": "Buy now at Planeo Elektro for CZK 22,990 in total.",
  "reasons": [
    "at_90d_low"
  ],
  "warnings": [
    "The shop has customer ratings but no verified-shop badge."
  ],
  "best": {
    "offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
    "shop": {
      "slug": "planeo-cz",
      "name": "Planeo Elektro",
      "country": "CZ",
      "trust": "rated",
      "rating": 0.84,
      "rating_source": "google",
      "rating_captured_at": "2026-10-09T11:18:24Z"
    },
    "title": "Apple iPhone 16 128GB Black",
    "source": "scrape",
    "source_name": "planeo-cz-page",
    "price": 22990,
    "currency": "CZK",
    "in_stock": true,
    "condition": "new",
    "delivery_days": null,
    "unknown": [
      {
        "field": "delivery_days",
        "reason": "not_stated"
      }
    ],
    "total": {
      "deliverTo": "CZ",
      "currency": "CZK",
      "goods": 22990,
      "shipping": 0,
      "shippingUnknown": false,
      "shippingApproximate": false,
      "total": 22990,
      "fx": null,
      "crossBorder": false
    },
    "url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
    "direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
    "captured_at": "2026-10-12T12:02:37Z",
    "age_hours": 21.6,
    "stale": false,
    "blockers": []
  },
  "offers": [
    {
      "offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
      "shop": {
        "slug": "planeo-cz",
        "name": "Planeo Elektro",
        "country": "CZ",
        "trust": "rated",
        "rating": 0.84,
        "rating_source": "google",
        "rating_captured_at": "2026-10-09T11:18:24Z"
      },
      "title": "Apple iPhone 16 128GB Black",
      "source": "scrape",
      "source_name": "planeo-cz-page",
      "price": 22990,
      "currency": "CZK",
      "in_stock": true,
      "condition": "new",
      "delivery_days": null,
      "unknown": [
        {
          "field": "delivery_days",
          "reason": "not_stated"
        }
      ],
      "total": {
        "deliverTo": "CZ",
        "currency": "CZK",
        "goods": 22990,
        "shipping": 0,
        "shippingUnknown": false,
        "shippingApproximate": false,
        "total": 22990,
        "fx": null,
        "crossBorder": false
      },
      "url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
      "direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
      "captured_at": "2026-10-12T12:02:37Z",
      "age_hours": 21.6,
      "stale": false,
      "blockers": []
    }
  ],
  "hidden_risky_shops": 0,
  "history": {
    "days": 90,
    "currency": "CZK",
    "lowest": 22990,
    "highest": 22990,
    "points": [
      {
        "date": "2026-10-01",
        "price": 22990
      }
    ]
  },
  "deliver_to": "CZ",
  "currency": "CZK",
  "fx_date": "2026-10-12",
  "data_source": "stored",
  "refresh_pending": false,
  "commission_disclosure": "When you buy through a Fordeal link, the shop pays Fordeal a commission. It does not raise your price and it never affects the order: offers are ranked by product price and shop trust only; shipping is shown separately for each offer."
}

get_product · Stejná karta podle ID produktu, jak ji ukazuje stránka produktu.

REST

curl -s "https://fordeal.ai/api/v1/deals/products/apple-iphone-16-128-gb?deliver_to_country=CZ&locale=en"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {
      "product": "apple-iphone-16-128-gb",
      "deliver_to_country": "CZ",
      "locale": "en"
    }
  }
}

Odpověď, HTTP 200, zkrácená

{
  "product": {
    "slug": "apple-iphone-16-128-gb",
    "name": "Apple iPhone 16 128 GB",
    "brand": "Apple",
    "category": "mobily",
    "variant": {
      "id": "apple-iphone-16-128-gb",
      "family_id": "line:apple-iphone-16",
      "family_kind": "line",
      "storage": "128 GB",
      "ram": null,
      "color": null,
      "color_id": null,
      "model": [],
      "connectivity": [],
      "size": null
    },
    "variants_url": "/api/v1/deals/products/apple-iphone-16-128-gb/variants"
  },
  "match": "exact",
  "match_note": null,
  "verdict": "buy_now",
  "headline": "Buy now at Planeo Elektro for CZK 22,990 in total.",
  "reasons": [
    "at_90d_low"
  ],
  "warnings": [
    "The shop has customer ratings but no verified-shop badge."
  ],
  "best": {
    "offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
    "shop": {
      "slug": "planeo-cz",
      "name": "Planeo Elektro",
      "country": "CZ",
      "trust": "rated",
      "rating": 0.84,
      "rating_source": "google",
      "rating_captured_at": "2026-10-09T11:18:24Z"
    },
    "title": "Apple iPhone 16 128GB Black",
    "source": "scrape",
    "source_name": "planeo-cz-page",
    "price": 22990,
    "currency": "CZK",
    "in_stock": true,
    "condition": "new",
    "delivery_days": null,
    "unknown": [
      {
        "field": "delivery_days",
        "reason": "not_stated"
      }
    ],
    "total": {
      "deliverTo": "CZ",
      "currency": "CZK",
      "goods": 22990,
      "shipping": 0,
      "shippingUnknown": false,
      "shippingApproximate": false,
      "total": 22990,
      "fx": null,
      "crossBorder": false
    },
    "url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
    "direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
    "captured_at": "2026-10-12T12:02:37Z",
    "age_hours": 21.6,
    "stale": false,
    "blockers": []
  },
  "offers": [
    {
      "offer_id": "f8edb345-e97e-4599-99e3-3c9240481aee",
      "shop": {
        "slug": "planeo-cz",
        "name": "Planeo Elektro",
        "country": "CZ",
        "trust": "rated",
        "rating": 0.84,
        "rating_source": "google",
        "rating_captured_at": "2026-10-09T11:18:24Z"
      },
      "title": "Apple iPhone 16 128GB Black",
      "source": "scrape",
      "source_name": "planeo-cz-page",
      "price": 22990,
      "currency": "CZK",
      "in_stock": true,
      "condition": "new",
      "delivery_days": null,
      "unknown": [
        {
          "field": "delivery_days",
          "reason": "not_stated"
        }
      ],
      "total": {
        "deliverTo": "CZ",
        "currency": "CZK",
        "goods": 22990,
        "shipping": 0,
        "shippingUnknown": false,
        "shippingApproximate": false,
        "total": 22990,
        "fx": null,
        "crossBorder": false
      },
      "url": "https://fordeal.ai/go/7a2gxvdd36/f8edb345-e97e-4599-99e3-3c9240481aee",
      "direct_url": "https://www.planeo.cz/apple-iphone-16-128gb-black",
      "captured_at": "2026-10-12T12:02:37Z",
      "age_hours": 21.6,
      "stale": false,
      "blockers": []
    }
  ],
  "hidden_risky_shops": 0,
  "history": {
    "days": 90,
    "currency": "CZK",
    "lowest": 22990,
    "highest": 22990,
    "points": [
      {
        "date": "2026-10-01",
        "price": 22990
      }
    ]
  },
  "deliver_to": "CZ",
  "currency": "CZK",
  "fx_date": "2026-10-12",
  "data_source": "stored",
  "refresh_pending": false,
  "commission_disclosure": "When you buy through a Fordeal link, the shop pays Fordeal a commission. It does not raise your price and it never affects the order: offers are ranked by product price and shop trust only; shipping is shown separately for each offer."
}

product_variants · Varianty produktu se stabilními ID.

REST

curl -s "https://fordeal.ai/api/v1/deals/products/apple-iphone-16-128-gb/variants?deliver_to_country=CZ&locale=en"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "product_variants",
    "arguments": {
      "product": "apple-iphone-16-128-gb",
      "deliver_to_country": "CZ",
      "locale": "en"
    }
  }
}

Odpověď, HTTP 200, zkrácená

{
  "slug": "apple-iphone-16-128-gb",
  "family_id": "line:apple-iphone-16",
  "family_kind": "line",
  "axes": [
    "storage",
    "color"
  ],
  "currency": "CZK",
  "variants": [
    {
      "id": "apple-iphone-16-128-gb",
      "slug": "apple-iphone-16-128-gb",
      "current": true,
      "storage": "128 GB",
      "size": "128 GB",
      "color": null,
      "color_id": null,
      "total": 22990,
      "in_stock": true,
      "url": "https://fordeal.ai/en/p/apple-iphone-16-128-gb"
    }
  ]
}

price_history · Denní nejnižší cena za 90 dní a odkud každá cena pochází.

REST

curl -s "https://fordeal.ai/api/v1/deals/history/apple-iphone-16-128-gb?days=90&currency=CZK"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "price_history",
    "arguments": {
      "product": "apple-iphone-16-128-gb",
      "days": 90,
      "currency": "CZK"
    }
  }
}

Odpověď, HTTP 200, zkrácená

{
  "product": {
    "slug": "apple-iphone-16-128-gb",
    "name": "Apple iPhone 16 128 GB",
    "variant": {
      "id": "apple-iphone-16-128-gb",
      "family_id": "line:apple-iphone-16",
      "family_kind": "line",
      "storage": "128 GB",
      "ram": null,
      "color": null,
      "color_id": null,
      "model": [],
      "connectivity": [],
      "size": null
    }
  },
  "history": {
    "days": 90,
    "currency": "CZK",
    "lowest": 22990,
    "highest": 22990,
    "points": [
      {
        "date": "2026-10-01",
        "price": 22990
      }
    ]
  },
  "offers": [
    {
      "shop": "Planeo Elektro",
      "shop_slug": "planeo-cz",
      "title": "Apple iPhone 16 128GB Black",
      "price": 22990,
      "currency": "CZK",
      "condition": "new",
      "source_name": "planeo-cz-page",
      "in_history": true,
      "captured_at": "2026-10-12T12:02:37Z"
    }
  ]
}

compare_digital · Digitální služby podle ceny za měsíc, každá s oficiálním ceníkem a datem ověření.

REST

curl -s "https://fordeal.ai/api/v1/digital/compare?category=ai-chat&deliver_to_country=CZ"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "compare_digital",
    "arguments": {
      "category": "ai-chat",
      "deliver_to_country": "CZ"
    }
  }
}

Odpověď, HTTP 200, zkrácená

{
  "category": "ai-chat",
  "currency": "CZK",
  "fx_date": "2026-10-12",
  "rows": [
    {
      "id": "claude-free",
      "provider": "Anthropic",
      "service": "Claude",
      "plan": "Free",
      "monthly": {
        "amount": 0,
        "currency": "EUR"
      },
      "monthlyLocal": {
        "amount": 0,
        "currency": "CZK",
        "rate": 24.39,
        "rateDate": "2026-10-12"
      },
      "sourceUrl": "https://claude.com/pricing",
      "verifiedOn": "2026-10-05"
    }
  ]
}

price_history · Neznámý produkt: HTTP 404, error.code not_found.

REST

curl -s "https://fordeal.ai/api/v1/deals/history/no-such-product"

MCP tools/call (POST na MCP endpoint)

POST https://fordeal.ai/mcp
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "price_history",
    "arguments": {
      "product": "no-such-product"
    }
  }
}

Odpověď, HTTP 404, zkrácená

{
  "error": {
    "code": "not_found",
    "message": "unknown product no-such-product",
    "fix": "Use `product.slug` from a find_best_price answer."
  }
}

/deals/search · Chybný parametr: HTTP 400, error.code validation se seznamem chyb.

REST

curl -s "https://fordeal.ai/api/v1/deals/search?query=iphone&limit=abc"

Odpověď, HTTP 400, zkrácená

{
  "error": {
    "code": "validation",
    "message": "invalid request: limit: Invalid input: expected number, received string",
    "fix": "Fix the listed fields. GET /api/openapi.json documents every parameter.",
    "details": {
      "issues": [
        "limit: Invalid input: expected number, received string"
      ]
    }
  }
}

/deals/shops/compared · Překročený limit: HTTP 429 s hlavičkou Retry-After.

REST

curl -s "https://fordeal.ai/api/v1/deals/shops/compared?country=CZ"

Odpověď, HTTP 429, zkrácená

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit of 10 requests per minute reached",
    "fix": "Wait 42 s and retry (Retry-After). Without an API key the limit is 10 requests per minute per IP address; generate a free key at https://fordeal.ai/agents#klic and send Authorization: Bearer <key> for 60 per minute.",
    "details": {
      "limit_per_min": 10,
      "retry_after_seconds": 42,
      "window_seconds": 60,
      "limit": 10,
      "remaining": 0,
      "reset": 42,
      "reset_at": "2026-10-28T09:15:00.000Z",
      "anonymous": true,
      "get_a_key": "https://fordeal.ai/agents#klic"
    }
  }
}

Stránkování, limity, chyby a neznámé hodnoty

Stránkování

search_products a GET /deals/search	limit (1 až 100, výchozí 20) a offset (výchozí 0); total_matches počítá všechny shody před stránkováním.
GET /deals/products	limit až 500 a offset; total počítá odpovídající produkty. facets=true přidá značky, obchody, cenové rozpětí a hodnoty parametrů za celý vyfiltrovaný seznam.
Stránka za koncem vrátí prázdný seznam se stejným total.

Limity

Bez klíče	10 požadavků za minutu na IP adresu, volání MCP nástrojů a REST dohromady.
S klíčem	60 požadavků za minutu.
Po překročení	HTTP 429 s hlavičkou Retry-After v sekundách, error.code rate_limited a error.details.retry_after_seconds, i přes MCP.

Chyby

Každá chyba má tvar {"error":{"code","message","fix"}}: code je stálý a strojově čitelný, fix říká, co změnit.
validation 400 (details.issues vypíše chybné parametry), country_not_supported 400, invalid_input 400, unauthorized 401, forbidden 403, not_found 404, rate_limited 429, not_available 503.
Přes MCP je chyba výsledek nástroje s isError: true a stejným tělem ve structuredContent.

Neznámé hodnoty, odhady a zastaralá data

Hodnota, kterou neznáme, je null a říká proč: každá nabídka uvádí unknown[] (delivery_days not_stated, shipping not_stated nebo approximate, shop_rating unrated).
total.shippingUnknown true	cena celkem je jen cena zboží a nabídka nikdy není best; total.shippingApproximate true: doprava je nejnižší sazba, kterou obchod uvádí, tedy odhad.
Každá nabídka nese captured_at a age_hours; stale je true po 36 hodinách a taková nabídka nikdy není best; refresh_pending je true, dokud se ceny znovu načítají.
match close s match_note	produkt je nejbližší varianta, ne ta požadovaná; přesná ID dává product.variant a product_variants.
history.since je první den s daty	okno 90 dní může mít méně dní.

Pole odpovědi, odhady a stránky

labels u každé nabídky, stejná slova jako na webu: lowest_price jen u nejnižší ceny produktu mezi zobrazenými novými nabídkami; recommended u best, když to není nejnižší cena produktu (nikdy ji nenazývejte nejlevnější); lowest_verified_total u nejnižšího celku s uvedenou (ne „od“) dopravou, když to není nejnižší cena produktu.
shipping_is_estimate true: doprava je jen sazba „od“ nebo neznámá, takže celek je dolní mez; saving_is_estimate true (savings_vs_best nabídky, recommended_surcharge): rozdíl stojí na takové dopravě. Říkejte „odhadovaná úspora při uvedené minimální dopravě“, nikdy jistá úspora.
saving_kind je vždy „estimate“ tam, kde je uvedena úspora nebo rozdíl (savings_vs_best nabídky, recommended_surcharge, saving u zahraniční nabídky, saving_year u energií): jde o rozdíl při cenách a dopravě zjištěných ve dnech uvedených v saving_basis, nikdy o zaručený výsledek. Pište „odhadovaná úspora“ a uveďte datum zjištění, ne „ušetříte“.
price_verdict {level low|usual|high|short_history|stale, percentile, days, basis} u find_best_price, get_product a price_history hodnotí poslední cenu proti posledním 90 dnům našich vlastních denních minim. Při historii kratší než 14 dnů nehodnotí (short_history); nikdy to není tvrzení o slevě.
daily_deals a GET /deals/daily vracejí největší naměřené poklesy za posledních 24 hodin u hodnocených obchodů, rozložené mezi obchody a kategorie (max_per_shop, web žádá 4; také category, country, min_percent); fond pro Slovensko tvoří eurové obchody, které tam doručují.
report_issue a POST /deals/issues berou offer_id dotčené nabídky (z karty), takže chybná cena nebo varianta jednoho řádku dojde člověku, který frontu čte, rovnou s ním; web má stejné tlačítko pro nahlášení u každého řádku nabídky.
Stránky „nejlevnější X“ (/nejlevnejsi/<model>) a „X vs Y“ (/srovnani/<a>-vs-<b>) nemají vlastní koncové body: čtou GET /deals/products (query, category, slugs, deliver_to_country; search_products, product_variants), u služeb a operátorů compare_digital a compare_mobile. Stejnou otázku položíte stejnými nástroji.
Odkazy na poskytovatele na srovnání v /digitalni vedou přes /go/plan/<id>, počítané přesměrování (klíč tarifu, typ stránky, naše stránka; nic osobního; roboti označeni). GET /deals/plan-clicks/{kind}/{id} (kind plan|energy|insurance|mobile) vrátí adresu poskytovatele bez počítání; vlastní odkaz nabídky je její url (/go/<shop>/<offer_id>).
GET /deals/coverage (po obchodech) a GET /deals/coverage/groups (po skupinách kategorií) dávají dnešní pokrytí: produkty s uloženou cenou, obchody s cenami a obchody čekající na feed. Čísla se mění denně, proto je čtěte, místo abyste citovali číslo z dokumentu.