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
robots.txtinterzice crawlerelor/api/. Documentația nu autorizează ignorarea regulilor de acces; folosește API-ul printr-o integrare explicită, nu pentru crawling.- Folosește cereri punctuale, cu
q. Nu enumera și nu descărca catalogul. - Nu există o limită de cereri documentată sau garantată; accesul poate fi restricționat. Nu există garanții de stabilitate a ID-urilor sau a formatului cursorului.
- Nu există pagini individuale de produs pe Cautio. Câmpul
urleste un link de afiliere către magazin; prețul și disponibilitatea se confirmă acolo.
GET /api/search
| Parametru | Format | Descriere |
|---|---|---|
q | text | Termenii 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. |
currency | trei litere mari | Moneda pentru min, max și sortarea după preț. |
min, max | număr cu punct, cel mult 2 zecimale | Interval de preț inclusiv. |
sort | relevance (implicit), price_asc, price_desc | Ordinea rezultatelor. |
cursor | opac | nextCursor 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
- Textul se normalizează: litere mici, fără diacritice, doar litere și cifre. Se păstrează cel mult 6 termeni, fiecare cu cel mult 40 de caractere; ordinea nu contează.
- Se caută în denumirea și brandul produsului, cu toți termenii (AND), ca subșir. Cuvintele de legătură (
cu, de, la, si, sau, in, pe, din, un, o, pentru, fara) se ignoră dacă rămân alți termeni. - Stemming ușor: se taie terminații frecvente (
-urilor, -elor, -ilor, -uri, -ele, -ale, -ii, -i, -e, -a) dacă termenul are cel puțin 5 caractere, nu conține cifre și rămân cel puțin 4 caractere. Termenii conținuți în alți termeni se elimină. - Pentru că potrivirea este pe subșir, un termen scurtat poate găsi cuvinte nedorite (
casti→castgăsește și „Cast Iron”). Prezența unui cuvânt în titlu nu confirmă o caracteristică tehnică a produsului. - Fără
qși fără filtre sau sortare, răspunsul este gol. Cu filtre și fărăqse parcurge catalogul filtrat; folosește întotdeaunaq.
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¤cy=RON&max=300
Interval de preț, într-un singur magazin (ID din /api/filters):
GET /api/search?q=cafea&shop=p8427¤cy=RON&min=20&max=100
Pagina următoare (aceiași parametri, plus cursorul primit):
GET /api/search?q=masa%20lemn&sort=price_asc¤cy=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.