Documentație API

Cautio este un agregator de produse cu linkuri afiliate. Magazinele sunt vânzătorii; Cautio nu vinde produse. Această pagină descrie API-ul folosit de interfața web, pentru integrări explicite. Contractul în format OpenAPI 3.1 este în /openapi.json, iar un rezumat pentru agenți AI în /llms.txt.

Reguli de utilizare

GET /api/search

ParametruFormatDescriere
qtextTermenii căutați. Se folosesc primele 80 de caractere.
shop[A-Za-z0-9_-]{1,40}ID de magazin din /api/filters, de exemplu p8427.
currencytrei litere mariMoneda pentru min, max și sortarea după preț.
min, maxnumăr cu punct, cel mult 2 zecimaleInterval de preț inclusiv.
sortrelevance (implicit), price_asc, price_descOrdinea rezultatelor.
cursoropacnextCursor din răspunsul anterior, cu aceiași ceilalți parametri.

Atenție la numele din interfață. Interfața web (/?q=…) folosește parametrii URL q, shop, min, max, sort și cur (nu currency), nu trimite cursor în URL, iar s=1 înregistrează o căutare confirmată. Parametrii API de mai sus nu sunt aceiași cu cei ai URL-ului interfeței. Interfața necesită JavaScript.

Cum se interpretează q

Răspuns

Până la 24 de produse pe pagină (fix; nu există limit). Câmpurile unui produs din items: id, name, brand (poate fi null), price, currency, shop, image (poate fi null), url, demo. id este intern și nu corespunde unei pagini Cautio.

Alte câmpuri, doar pe prima pagină (fără cursor): total (plafonat la 10.000) cu totalCapped; rankLimited și rankLimit (30.000) la relevanță; shops (magazinele cu rezultate și numărul lor); refine (cuvinte frecvente într-un eșantion de titluri, cel mult 10); suggest la zero rezultate. nextCursor este null la ultima pagină.

Sugestia de eliminare a unui cuvânt. Dacă nu există rezultate și q are cel puțin 2 termeni, iar eliminarea unui singur termen ar produce rezultate, suggest este {"drop": "cuvânt", "q": "căutarea rămasă"}. Sugestia nu se aplică automat; poți repeta cererea cu q din sugestie.

Relevanța. Cu cel puțin un termen de 3 litere, se clasează cel mult 30.000 de potriviri (cuvânt întreg înaintea prefixului și a subșirului, termen la începutul titlului, produse cu imagine, intercalat între magazine și tipuri de produs). Peste această limită doar un eșantion este clasat, iar rankLimited este true. Sortările după preț acoperă toate potrivirile.

Monede. Prețurile nu se compară între monede. Când catalogul conține mai multe monede (vezi /api/filters), min, max sau sort diferit de relevance fără currency dau currency_required.

Erori

Cod 400 cu {"error": "…"}: bad_sort, bad_shop, bad_currency, bad_price (format min/max), bad_range (min > max), bad_cursor, currency_required. Eroare internă: 500 cu internal. Alte metode decât GET: 405, fără corp.

Cache

Răspunsurile cu rezultate au Cache-Control: public, max-age=30, s-maxage=300; după o sincronizare a catalogului, rezultatele vechi nu se mai servesc după cel mult aproximativ un minut, plus intervalul de cache din browser. Răspunsurile de eroare nu se păstrează în cache.

Exemple

Produse cu buget, în RON, de la cel mai mic preț:

GET /api/search?q=masa%20lemn&sort=price_asc&currency=RON&max=300

Interval de preț, într-un singur magazin (ID din /api/filters):

GET /api/search?q=cafea&shop=p8427&currency=RON&min=20&max=100

Pagina următoare (aceiași parametri, plus cursorul primit):

GET /api/search?q=masa%20lemn&sort=price_asc&currency=RON&max=300&cursor=<nextCursor>

Valorile din shop sunt exemple; ia ID-urile actuale din /api/filters.

GET /api/filters

Întoarce shops (id, name, count) și currencies (code, count), precum și source (informativ). Apelează-l o singură dată pentru valorile lui shop și currency. Cache: s-maxage=3600.

GET /api/meta

Întoarce lastUpdated (data ultimei sincronizări a catalogului, UTC, sau null) și demo. Nu există dată de actualizare pentru fiecare produs.

Limitele datelor

Datele provin din feedurile magazinelor partenere și nu acoperă toată piața. Prețurile și disponibilitatea se confirmă în magazin; API-ul nu oferă informații despre stoc. Rezultatele nu constituie o recomandare sau un clasament de calitate.