{
  "openapi": "3.1.0",
  "info": {
    "title": "Cautio API de căutare",
    "version": "1.0.0",
    "description": "API-ul folosit de interfața web Cautio (https://cautio.ro), un agregator de produse cu linkuri afiliate. Magazinele sunt vânzătorii; Cautio nu vinde produse și nu are pagini individuale de produs. Câmpul `url` al unui produs este un link de afiliere către oferta din magazin.\n\nFolosește cereri punctuale; nu enumera și nu descărca catalogul. `robots.txt` interzice crawlerelor `/api/`, iar această specificație nu autorizează ignorarea regulilor de acces. Nu există o limită de cereri documentată sau garantată, iar accesul poate fi restricționat. Prețurile și disponibilitatea se confirmă în magazin. Nu există garanții de stabilitate a ID-urilor sau a formatului cursorului."
  },
  "security": [],
  "servers": [{ "url": "https://cautio.ro" }],
  "externalDocs": { "description": "Documentație în limba română", "url": "https://cautio.ro/documentatie-api/" },
  "paths": {
    "/api/search": {
      "get": {
        "operationId": "searchProducts",
        "summary": "Caută produse",
        "description": "Căutare cu toți termenii (AND) în denumirea și brandul produselor active. Textul se normalizează (litere mici, fără diacritice, doar litere și cifre), 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, iar pluralul și articolul se taie ușor (de exemplu `masini` → `masin`). Se păstrează cel mult 6 termeni, fiecare cu cel mult 40 de caractere, din primele 80 de caractere ale lui `q`; termenii conținuți în alți termeni se elimină. Potrivirea este pe subșir: termenul scurtat poate găsi și cuvinte nedorite (`casti` → `cast` găsește și „Cast Iron”). Paginile au 24 de produse; parametrul `limit` nu există.\n\nFără `q` și fără niciun filtru sau sortare, răspunsul este gol (`items: []`). Cu filtre și fără `q` se parcurge catalogul filtrat; folosește întotdeauna `q`.\n\nPrețul se filtrează sau se sortează doar în aceeași monedă: când catalogul conține mai multe monede (vezi `/api/filters`), `min`, `max` sau `sort` diferit de `relevance` fără `currency` dau eroarea `currency_required`.\n\nRăspunsurile se păstrează în cache (`Cache-Control: public, max-age=30, s-maxage=300`). Metodele diferite de GET primesc 405, fără corp.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Textul căutat. Se folosesc primele 80 de caractere. Interfața web (`/?q=...`) folosește `q` la fel, dar are alți parametri de URL (de exemplu `cur` în loc de `currency`).",
            "schema": { "type": "string", "maxLength": 1000 },
            "example": "aparat de cafea"
          },
          {
            "name": "shop",
            "in": "query",
            "required": false,
            "description": "ID-ul magazinului, exact ca în `shops[].id` din `/api/filters` (de exemplu `p8427`).",
            "schema": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$" }
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "description": "Cod de monedă din trei litere mari, din `currencies[].code` din `/api/filters`. În interfața web parametrul corespunzător din URL se numește `cur`, nu `currency`.",
            "schema": { "type": "string", "pattern": "^[A-Z]{3}$" },
            "example": "RON"
          },
          {
            "name": "min",
            "in": "query",
            "required": false,
            "description": "Prețul minim (inclusiv), în moneda `currency`. Număr zecimal cu cel mult 9 cifre întregi și 2 zecimale, cu punct (fără separator de mii).",
            "schema": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,2})?$" },
            "example": "50"
          },
          {
            "name": "max",
            "in": "query",
            "required": false,
            "description": "Prețul maxim (inclusiv), în moneda `currency`. Același format ca `min`. Dacă `min` > `max`, răspunsul este `bad_range`.",
            "schema": { "type": "string", "pattern": "^\\d{1,9}(\\.\\d{1,2})?$" },
            "example": "300"
          },
          {
            "name": "sort",
            "in": "query",
            "required": false,
            "description": "Ordinea rezultatelor. `relevance` (implicit) clasează, când există un termen de cel puțin 3 litere, cel mult 30.000 de potriviri și diversifică magazinele și tipurile de produs; la peste 30.000 de potriviri doar un eșantion determinist este clasat (`rankLimited`). `price_asc` și `price_desc` sortează toate potrivirile după preț.",
            "schema": { "type": "string", "enum": ["relevance", "price_asc", "price_desc"], "default": "relevance" }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "description": "Valoarea `nextCursor` din răspunsul anterior, cu aceiași ceilalți parametri. Este opac: nu-l construi și nu te baza pe formatul lui. Un cursor invalid dă `bad_cursor`.",
            "schema": { "type": "string", "maxLength": 64 }
          }
        ],
        "responses": {
          "200": {
            "description": "Pagina de rezultate.",
            "headers": {
              "Cache-Control": { "schema": { "type": "string" }, "description": "`public, max-age=30, s-maxage=300` pentru răspunsurile cu rezultate." },
              "X-Robots-Tag": { "schema": { "type": "string" }, "description": "`noindex, nofollow`." }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchResponse" },
                "examples": {
                  "buget": {
                    "summary": "q=masa lemn&sort=price_asc&currency=RON&max=300",
                    "description": "Valorile sunt ilustrative; prețurile, magazinele și numerele reale diferă.",
                    "value": {
                      "items": [
                        {
                          "id": 1001,
                          "name": "Masă din lemn 80x60 cm",
                          "brand": null,
                          "price": 149.9,
                          "currency": "RON",
                          "shop": "magazin-exemplu.ro",
                          "image": "https://magazin-exemplu.ro/imagini/masa.jpg",
                          "url": "https://event.2performant.com/events/click?ad_type=product_store&unique=EXEMPLU&aff_code=EXEMPLU&campaign_unique=EXEMPLU",
                          "demo": false
                        }
                      ],
                      "nextCursor": null,
                      "total": 1,
                      "totalCapped": false,
                      "shops": [{ "id": "p0000", "name": "magazin-exemplu.ro", "count": 1 }],
                      "refine": ["stejar"]
                    }
                  },
                  "zero_rezultate": {
                    "summary": "Fără rezultate, cu sugestie de eliminare a unui cuvânt",
                    "value": {
                      "items": [],
                      "nextCursor": null,
                      "total": 0,
                      "totalCapped": false,
                      "rankLimited": false,
                      "rankLimit": 30000,
                      "shops": [],
                      "suggest": { "drop": "zzqx", "q": "casti" }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Parametru invalid. Corpul este `{\"error\": \"<cod>\"}`; codurile sunt cele din schema `Error`.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "405": { "description": "Metodă nepermisă (doar GET). Fără corp." },
          "500": {
            "description": "Eroare internă (`internal`).",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/filters": {
      "get": {
        "operationId": "listFilters",
        "summary": "Magazine și monede disponibile",
        "description": "Magazinele (cu ID-ul pentru `shop`) și monedele produselor active, cu numărul de produse din catalog. Util pentru a afla valorile valabile ale lui `shop` și `currency`. Se cere o singură dată; cache `public, max-age=30, s-maxage=3600`.",
        "responses": {
          "200": {
            "description": "Listele de filtre.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FiltersResponse" } } }
          },
          "405": { "description": "Metodă nepermisă (doar GET). Fără corp." },
          "500": {
            "description": "Eroare internă.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    },
    "/api/meta": {
      "get": {
        "operationId": "getMeta",
        "summary": "Data ultimei actualizări a catalogului",
        "description": "Data globală a ultimei sincronizări a catalogului. Nu există o dată de actualizare pentru fiecare produs. Cache `public, max-age=30, s-maxage=600`.",
        "responses": {
          "200": {
            "description": "Metadate.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaResponse" } } }
          },
          "405": { "description": "Metodă nepermisă (doar GET). Fără corp." },
          "500": {
            "description": "Eroare internă.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Product": {
        "type": "object",
        "required": ["id", "name", "brand", "price", "currency", "shop", "image", "url", "demo"],
        "properties": {
          "id": { "type": "integer", "description": "ID intern al produsului în Cautio. Nu are garanție de stabilitate și nu corespunde unei pagini Cautio." },
          "name": { "type": "string", "description": "Denumirea din feedul magazinului." },
          "brand": { "type": ["string", "null"] },
          "price": { "type": "number", "description": "Prețul din feed, în `currency`. Se confirmă în magazin." },
          "currency": { "type": "string", "description": "Cod de monedă, de exemplu RON sau EUR." },
          "shop": { "type": "string", "description": "Numele magazinului (vânzătorul)." },
          "image": { "type": ["string", "null"], "format": "uri", "description": "Adresa imaginii, găzduită de magazin." },
          "url": { "type": "string", "format": "uri", "description": "Link de afiliere către oferta din magazin. Cautio nu are pagină individuală de produs." },
          "demo": { "type": "boolean", "description": "Produs demonstrativ; `false` pentru ofertele reale." }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["items", "nextCursor"],
        "properties": {
          "items": { "type": "array", "maxItems": 24, "items": { "$ref": "#/components/schemas/Product" } },
          "nextCursor": { "type": ["string", "null"], "description": "Cursor pentru pagina următoare sau `null` la ultima pagină." },
          "total": { "type": "integer", "description": "Numărul de rezultate, plafonat la 10.000. Doar pe prima pagină (fără `cursor`)." },
          "totalCapped": { "type": "boolean", "description": "`true` dacă există mai mult de 10.000 de potriviri. Doar pe prima pagină." },
          "rankLimited": { "type": "boolean", "description": "La `sort=relevance` cu termeni: `true` dacă potrivirile depășesc `rankLimit` și doar un eșantion este clasat. Doar pe prima pagină." },
          "rankLimit": { "type": "integer", "description": "Limita clasamentului pe relevanță (30.000). Doar pe prima pagină, cu `rankLimited`." },
          "shops": {
            "type": "array",
            "description": "Magazinele cu rezultate pentru căutare, cu numărul de rezultate, fără filtrul `shop`. Doar pe prima pagină, când există termeni de cel puțin 3 litere.",
            "items": { "$ref": "#/components/schemas/ShopCount" }
          },
          "refine": {
            "type": "array",
            "description": "Cuvinte frecvente în titlurile unui eșantion de rezultate (cel mult 10), pentru rafinarea căutării. Nu sunt statistici despre căutările utilizatorilor. Doar pe prima pagină, când există.",
            "items": { "type": "string" }
          },
          "suggest": {
            "oneOf": [{ "$ref": "#/components/schemas/Suggest" }, { "type": "null" }],
            "description": "Prezent pe prima pagină fără rezultate. Dacă `q` are cel puțin 2 termeni și eliminarea unuia singur ar produce rezultate, indică cuvântul eliminat (`drop`) și căutarea rămasă (`q`); altfel `null`. Nu se aplică automat."
          }
        }
      },
      "Suggest": {
        "type": "object",
        "required": ["drop", "q"],
        "properties": {
          "drop": { "type": "string", "description": "Cuvântul care ar fi eliminat din căutare." },
          "q": { "type": "string", "description": "Căutarea rămasă, de refăcut cu un nou apel." }
        }
      },
      "ShopCount": {
        "type": "object",
        "required": ["id", "name", "count"],
        "properties": {
          "id": { "type": "string", "description": "Valoare pentru parametrul `shop`." },
          "name": { "type": "string" },
          "count": { "type": "integer" }
        }
      },
      "FiltersResponse": {
        "type": "object",
        "required": ["shops", "currencies"],
        "properties": {
          "shops": { "type": "array", "items": { "$ref": "#/components/schemas/ShopCount" } },
          "currencies": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["code", "count"],
              "properties": { "code": { "type": "string" }, "count": { "type": "integer" } }
            }
          },
          "source": { "type": "string", "enum": ["summary", "scan"], "description": "Informativ: modul de calcul al numărătorilor." }
        }
      },
      "MetaResponse": {
        "type": "object",
        "required": ["lastUpdated", "demo"],
        "properties": {
          "lastUpdated": { "type": ["string", "null"], "description": "Data ultimei sincronizări a catalogului (ISO 8601, UTC)." },
          "demo": { "type": "boolean", "description": "`true` dacă baza conține date demonstrative." }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "string",
            "enum": ["bad_sort", "bad_shop", "bad_currency", "bad_price", "bad_range", "bad_cursor", "currency_required", "internal"],
            "description": "bad_sort: `sort` necunoscut. bad_shop: `shop` în format invalid. bad_currency: `currency` nu are trei litere mari. bad_price: `min` sau `max` în format invalid. bad_range: `min` > `max`. bad_cursor: cursor invalid pentru cererea curentă. currency_required: filtru sau sortare după preț fără `currency`, când există mai multe monede. internal: eroare internă (500)."
          }
        }
      }
    }
  }
}
