MCP a REST

Jedna otázka, jedna odpoveď, aj pre agentov

API kľúč vytvoríte na tejto stránke. Postup má 4 kroky: kľúč, prvý dopyt, napojenie cez MCP alebo REST a limity.

Čítanie cien bez kľúča: 10 dopytov za minútu
S kľúčom: 60 dopytov za minútu
MCP server a REST API s rovnakými odpoveďami

1. Vytvorenie API kľúča

API kľúč je heslo, ktorým sa váš AI asistent alebo bot prihlási k Fordealu. Dostanete ho hneď a zobrazí sa len raz, preto si ho uložte.

2. Prvý dopyt

Dopyt na najnižšiu cenu jedného produktu vrátane dopravy do zvolenej krajiny.

Ukážky obsahujú zástupný kľúč. Po vytvorení kľúča v kroku 1 sa do nich doplní váš. Bez kľúča dopyt prejde tiež, s limitom 10 dopytov za minútu.

Príkazový riadok: macOS, Linux, Windows 10 a novší.

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ší alebo prehliadač.

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 knižnicou 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"))

Konfigurácia MCP klienta, napríklad Claude Desktop (claude_desktop_config.json), Claude Code (.mcp.json) alebo Cursor.

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

Nižšie je jedno volanie a jeho skrátená odpoveď. headline je veta pre človeka, best.url vedie do obchodu cez /go a commission_disclosure sa musí kupujúcemu ukázať.

Príklad odpovede (ilustratívne čísla, nie 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. Napojenie cez MCP alebo REST

MCP endpoint cez Streamable HTTP; pridajte ho do Claude, ChatGPT, Cursoru alebo ľubovoľné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ážky REST dopytov

Rovnaké nástroje cez HTTP, opísané v OpenAPI. Výsledky sa ukladajú a dajú zdieľať na /api/v1/deals/results/{slug}. Každá ponuka nesie aj marketplace (platforma, predajca, krajina odoslania, druh ceny; pri bežnom obchode null) a total.shippingSource (offer, shop_rule alebo unknown: odkiaľ 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 podmienky

Limity platia pre MCP aj REST spolu.

Čítanie nepotrebuje kľúč. Každá odpoveď nesie strojovo čitateľné ceny: sumy ako čísla, mena podľa ISO 4217, captured_at v ISO 8601, stabilné slugy produktov a obchodov.

Bez kľúča: 10 dopytov za minútu z jednej IP adresy, MCP a REST spolu.
S kľúčom: 60 dotazov za minútu. Kľúč si vygenerujete nižšie na tejto stránke, hneď po zadaní názvu agenta a e-mailu majiteľa.
Pri prekročení limitu príde error.code „rate_limited“ s retry_after_seconds.
Spolu s ostrým kľúčom fd_live_ dostanete testovací kľúč fd_test_ pre sandbox (simulovaní poskytovatelia a falošné peniaze skrytého trhoviska); čítanie cien žiadny testovací režim nepotrebuje.

Kľúč je určený pre jedného agenta. Používaním API súhlasíte s podmienkami používania. Pravidlá odpovedí

V skratke

Web, REST API aj MCP server vracajú rovnaké dáta: čo vidí človek, dostane aj agent. find_best_price s dopytom a krajinou kupujúceho vráti celú kartu: verdikt, hlavnú ponuku (`best`) s cenou produktu, dopravou a časom overenia, alternatívy a históriu. Každá odpoveď sa riadi rovnakými pravidlami ako web a nesie priznanie provízie, ktoré sa kupujúcemu musí ukázať.

Nástroje

compare_internet	V príprave, neoverené: odpoveď nesie status: in_preparation a verified: false; výsledok uvádzajte ako odhad, nie ako odporúčanie. Internet domov podľa mesačnej ceny: zadajte technológiu, rýchlosť a prípadne adresu alebo PSČ; radenie podľa mesačnej ceny s viazanosťou a jednorazovými poplatkami. V príprave.
search_products	Vyhľadávanie s filtrami: dopyt alebo kategória plus cenové rozpätie, značka, obchody, krajina obchodu, skladom, v zľave, doprava zadarmo, minimálne hodnotenie obchodu; radenie podľa ceny produktu, ceny s dopravou, zľavy, počtu obchodov alebo obľúbenosti.
cheaper_abroad	Je to lacnejšie v inej krajine? Najnižšia domáca ponuka vedľa najnižšej zahraničnej, úspora a čo nákup v zahraničí znamená (záruka, vrátenie, dni doručenia).
list_shops	Porovnávané obchody pre krajinu s hodnotením, zdrojom hodnotenia a štítkom dôvery, plus obchody čakajúce na feed. Odpovie na „môžem obchodu X veriť“.
find_best_price	Text, model, EAN alebo URL produktu plus deliver_to_country (voliteľne sort=total pre radenie s dopravou). Vráti kartu. Kupujúceho pošlite na best.url a povedzte mu cenu produktu, dopravu a čas overenia.
get_product	ID produktu, ktoré už máte (slug), a deliver_to_country: rovnaká karta ako stránka produktu, bez čítania dopytu, takže nikdy neskončí pri inej variante. product.variant uvádza kapacitu, farbu, označenie modelu a family_id.
product_variants	Ďalšie kapacity, farby alebo veľkosti produktu, každá so stabilným id, príznakom current, kapacitou, farbou, cenou produktu a skladom. Vyberte presnú variantu a potom zavolajte get_product s jej id.
price_history	Denná najnižšia cena až 365 dní späť plus všetky aktuálne ponuky. Hodí sa, keď chcete povedať, či je dnes minimum.
daily_deals	Najväčšie poklesy cien za 24 hodín v hodnotených obchodoch, podľa krajiny a kategórie.
list_coupons	Zľavové kódy a akcie porovnávaných obchodov platné dnes (z affiliate siete eHUB, obnova každé 3 hodiny), s platnosťou, kódom a odkazom s províziou.
product_rows	Riadky nad výpisom produktov: zľavy dňa, práve letí (nové a sledované), sezónne tipy na darčeky podľa rozpočtu a pre koho, s ich vzorcami.
trending_new_products	Prvý riadok úvodnej stránky: najhľadanejšie novinky nájdené z dát (najnovší model rady, nové v katalógu, hľadané, preklikávané, nájdené na Googli, pribúdajúce obchody), s bodmi každej časti skóre.
most_searched_products	Najhľadanejšie produkty v krajine za posledných 7 dní: Google Trends, naše vyhľadávanie a prekliky, spárované s produktmi s fotkou a aspoň dvoma obchodmi; každý riadok s dátumom výpočtu.
compare_mobile	V príprave, neoverené: odpoveď nesie status: in_preparation a verified: false; výsledok uvádzajte ako odhad, nie ako odporúčanie. Mobilné tarify (Česko a Slovensko) z oficiálnych cenníkov operátorov: zadajte data_gb, minutes a prípadne no_commitment, five_g, roaming_eu_gb; prvá je najlacnejšia bežná cena, ktorá to pokryje.
compare_energy	Elektrina a plyn pre domácnosti v Česku: zadajte distribútora, sadzbu a ročnú spotrebu v MWh; ponuky zoradené podľa ročných nákladov s DPH, rozdelené na regulovanú časť a časť dodávateľa, každá s oficiálnym cenníkom.
compare_digital	Digitálne služby podľa ceny za mesiac: AI predplatné, ceny tokenov v API s výpočtom nákladov pre dané použitie, nástroje na obrázky a video, streamovanie, hudba, VPN, cloud. Ceny z oficiálnych cenníkov so zdrojom a dátumom overenia.
api_price_breakdown	Rozpad ceny AI API: vstup, čítanie z cache a zápis do cache, výstup a spolu za dopyt aj mesiac, ďalšie položky cenníka (dávková zľava, dlhé prompty), zdroj a dátum overenia.
digital_price_history	Zaznamenané zmeny cien digitálnych taríf (stará cena, nová cena, deň, zdroj) od tracking_since; nič sa spätne nedopočítava.
compare_energy_from_bill	Elektrina alebo plyn z údajov na faktúre: distribútor, sadzba, istič, spotreba a ceny dodávateľa; rovnaké poradie ponúk ako pri porovnaní, s úsporou oproti dnešnému cenníku. Faktúru (PDF alebo fotku) prečíta POST /digital/energy/bill, súbor sa neukladá.
energy_unit_prices	Cena kWh elektriny a plynu s DPH podľa distribučného územia: regulovaná časť, rozpätie cien dodávateľov, kWh navyše a priemer s poplatkami, z oficiálnych cenníkov.
energy_price_history	Ceny elektriny a plynu za kWh pre domácnosti od roku 2015, ako ich po polrokoch zverejňuje Eurostat, s odkazom na dátovú sadu.
energy_suppliers	Všetci dodávatelia energií pre domácnosti s produktmi, cenami z oficiálneho cenníka s dátumom a s tým, kde ich zákazníci nájdu vyúčtovanie.
estimate_appliance_energy	Ročné kWh a náklady chladničky, práčky alebo vykurovania podľa energetického štítku alebo certifikátu budovy, pri dnešnej cene kWh navyše.
energy_watch_status	Stav strážcu konca fixácie podľa tokenu z odkazu v e-maile.
insurance_guide	Poistenie ako sprievodca: čo porovnať pri každom druhu a oficiálne weby poisťovní, abecedne; bez cien, bez poradia, bez provízie (Fordeal nie je sprostredkovateľ poistenia).
price_watch_status	Stav jedného stráženia ceny podľa odkazu z e-mailu: cieľová cena, stav a kedy ju cena naposledy dosiahla.
check_shop_feed	Prečíta produktový feed obchodu (adresa alebo súbor) a vráti jeho stav, prvé nájdené chyby a náhľad produktov. Nič neukladá. Použite pred register_shop.
get_shop_registration	Stav registrácie obchodu podľa jej id: rozhodnutie, stav feedu a uložená správa o feede.
get_shop_feed_diagnostics	Posledný beh feedu porovnávaného obchodu: koľko produktov sa prečítalo, čo sa preskočilo a prečo, s časom behu.

Akcie, ktoré zapisujú

Nástroje vyššie len čítajú. Nástroje nižšie zapisujú: report_issue môže volať ktokoľvek, nástroje účtu len s prístupovým tokenom prihláseného človeka (Authorization: Bearer, token, ktorý web drží po prihlásení odkazom z e-mailu). Kľúč agenta ani žiadny kľúč účet neotvorí a každé čítanie aj zápis platí len pre účet z tokenu.

`report_issue`	Nahlási zlú cenu, variant, kategóriu alebo obchod pri jednej ponuke. Účet nie je potrebný.
`watch_energy_fixation`, `confirm_energy_watch`, `cancel_energy_watch`	Strážca konca fixácie: e-mail a dátum konca od človeka; double opt-in (človek potvrdí v e-maile), jedno upozornenie 45 dní pred koncom, odkaz na zrušenie v každom e-maile.
`list_my_price_watches`, `set_price_watch`, `update_price_watch`, `delete_price_watch`	Strážené ceny človeka: výpis, založenie, zmena cieľovej ceny alebo pozastavenie, zmazanie.
`list_my_favorites`, `save_favorite`, `remove_favorite`	Uložené produkty a digitálne tarify človeka.
`list_my_comparisons`, `save_comparison`, `share_comparison`, `delete_comparison`	Uložené porovnania človeka a odkaz na zdieľanie jedného z nich.

Ich REST adresy: rovnaké 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

Pravidlá, ktoré platia pre každú odpoveď

Radí sa len podľa ceny produktu (denný kurz ČNB) a dôveryhodnosti obchodu; doprava do krajiny je pri každej ponuke zvlášť a sort=total radí podľa súčtu. Žiadna platená pozícia.
Obchod na zozname ČOI alebo SOI sa nikdy nezobrazí. Obchod bez hodnotenia nikdy nie je best.
Cena staršia ako 36 hodín alebo ponuka s neznámou dopravou nikdy nie je best; každá ponuka nesie captured_at a blockers.
Zahraničné ponuky nesú cross_border: záruka v EÚ, vrátenie, jazyky podpory.
commission_disclosure je súčasťou každej odpovede a kupujúcemu sa musí ukázať.

Príklady požiadaviek a odpovedí

Každé volanie ako curl (REST) a ako telo MCP JSON-RPC, odpoveď skrátená (polia ukazujú prvý prvok). Testy spúšťajú každý príklad proti aplikácii, takže názvy polí sú skutočné.

search_products · Hľadanie so stránkovaním: produkty zodpovedajúce dopytu, 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
    }
  }
}

Odpoveď, HTTP 200, skrátená

{
  "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 · Najnižšia cena produktu pre dopyt: verdikt, odporúčaná ponuka so zdrojom, dopravou a časom overenia, všetky ponuky s dôvodmi vyradenia.

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"
    }
  }
}

Odpoveď, HTTP 200, skrátená

{
  "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 · Rovnaká karta podľa ID produktu, ako ju 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"
    }
  }
}

Odpoveď, HTTP 200, skrátená

{
  "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 so 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"
    }
  }
}

Odpoveď, HTTP 200, skrátená

{
  "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á najnižšia cena za 90 dní a odkiaľ každá cena pochádza.

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"
    }
  }
}

Odpoveď, HTTP 200, skrátená

{
  "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álne služby podľa ceny za mesiac, každá s oficiálnym cenníkom a dátumom overenia.

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"
    }
  }
}

Odpoveď, HTTP 200, skrátená

{
  "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ámy 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"
    }
  }
}

Odpoveď, HTTP 404, skrátená

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

/deals/search · Chybný parameter: HTTP 400, error.code validation so zoznamom chýb.

REST

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

Odpoveď, HTTP 400, skrátená

{
  "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 · Prekročený limit: HTTP 429 s hlavičkou Retry-After.

REST

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

Odpoveď, HTTP 429, skrátená

{
  "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ánkovanie, limity, chyby a neznáme hodnoty

Stránkovanie

search_products a GET /deals/search	limit (1 až 100, predvolene 20) a offset (predvolene 0); total_matches počíta všetky zhody pred stránkovaním.
GET /deals/products	limit do 500 a offset; total počíta zodpovedajúce produkty. facets=true pridá značky, obchody, cenové rozpätie a hodnoty parametrov za celý vyfiltrovaný zoznam.
Stránka za koncom vráti prázdny zoznam s rovnakým total.

Limity

Bez kľúča	10 požiadaviek za minútu na IP adresu, volania MCP nástrojov a REST spolu.
S kľúčom	60 požiadaviek za minútu.
Po prekročení	HTTP 429 s hlavičkou Retry-After v sekundách, error.code rate_limited a error.details.retry_after_seconds, aj cez MCP.

Chyby

Každá chyba má tvar {"error":{"code","message","fix"}}: code je stály a strojovo čitateľný, fix hovorí, čo zmeniť.
validation 400 (details.issues vypíše chybné parametre), country_not_supported 400, invalid_input 400, unauthorized 401, forbidden 403, not_found 404, rate_limited 429, not_available 503.
Cez MCP je chyba výsledok nástroja s isError: true a rovnakým telom v structuredContent.

Neznáme hodnoty, odhady a zastarané údaje

Hodnota, ktorú nepoznáme, je null a hovorí prečo: každá ponuka uvádza unknown[] (delivery_days not_stated, shipping not_stated alebo approximate, shop_rating unrated).
total.shippingUnknown true	cena celkom je len cena tovaru a ponuka nikdy nie je best; total.shippingApproximate true: doprava je najnižšia sadzba, ktorú obchod uvádza, teda odhad.
Každá ponuka nesie captured_at a age_hours; stale je true po 36 hodinách a taká ponuka nikdy nie je best; refresh_pending je true, kým sa ceny znova načítavajú.
match close s match_note	produkt je najbližšia varianta, nie tá požadovaná; presné ID dáva product.variant a product_variants.
history.since je prvý deň s údajmi	okno 90 dní môže mať menej dní.

Polia odpovede, odhady a stránky

labels pri každej ponuke, rovnaké slová ako na webe: lowest_price len pri najnižšej cene produktu medzi zobrazenými novými ponukami; recommended pri best, keď to nie je najnižšia cena produktu (nikdy ju nenazývajte najlacnejšia); lowest_verified_total pri najnižšom celku s uvedenou (nie „od“) dopravou, keď to nie je najnižšia cena produktu.
shipping_is_estimate true: doprava je len sadzba „od“ alebo neznáma, takže celok je dolná hranica; saving_is_estimate true (savings_vs_best ponuky, recommended_surcharge): rozdiel stojí na takejto doprave. Hovorte „odhadovaná úspora pri uvedenej minimálnej doprave“, nikdy istá úspora.
saving_kind je vždy „estimate“ tam, kde je uvedená úspora alebo rozdiel (savings_vs_best ponuky, recommended_surcharge, saving pri zahraničnej ponuke, saving_year pri energiách): ide o rozdiel pri cenách a doprave zistených v dňoch uvedených v saving_basis, nikdy o zaručený výsledok. Píšte „odhadovaná úspora“ a uveďte dátum zistenia, nie „ušetríte“.
price_verdict {level low|usual|high|short_history|stale, percentile, days, basis} pri find_best_price, get_product a price_history hodnotí poslednú cenu voči posledným 90 dňom našich vlastných denných miním. Pri histórii kratšej ako 14 dní nehodnotí (short_history); nikdy to nie je tvrdenie o zľave.
daily_deals a GET /deals/daily vracajú najväčšie namerané poklesy za posledných 24 hodín pri hodnotených obchodoch, rozložené medzi obchody a kategórie (max_per_shop, web žiada 4; aj category, country, min_percent); fond pre Slovensko tvoria eurové obchody, ktoré tam doručujú.
report_issue a POST /deals/issues berú offer_id dotknutej ponuky (z karty), takže chybná cena alebo variant jedného riadku príde človeku, ktorý front číta, rovno s ním; web má rovnaké tlačidlo na nahlásenie pri každom riadku ponuky.
Stránky „najlacnejší X“ (/nejlevnejsi/<model>) a „X vs Y“ (/srovnani/<a>-vs-<b>) nemajú vlastné koncové body: čítajú GET /deals/products (query, category, slugs, deliver_to_country; search_products, product_variants), pri službách a operátoroch compare_digital a compare_mobile. Rovnakú otázku položíte rovnakými nástrojmi.
Odkazy na poskytovateľa na porovnaní v /digitalni vedú cez /go/plan/<id>, počítané presmerovanie (kľúč tarifu, typ stránky, naša stránka; nič osobné; roboty označené). GET /deals/plan-clicks/{kind}/{id} (kind plan|energy|insurance|mobile) vráti adresu poskytovateľa bez počítania; vlastný odkaz ponuky je jej url (/go/<shop>/<offer_id>).
GET /deals/coverage (po obchodoch) a GET /deals/coverage/groups (po skupinách kategórií) dávajú dnešné pokrytie: produkty s uloženou cenou, obchody s cenami a obchody čakajúce na feed. Čísla sa menia denne, preto ich čítajte, namiesto aby ste citovali číslo z dokumentu.