# Căutare
> Căutați în fiecare document după cuvinte și după sens: parametri, filtre, rezultate, exemple.
>
> Înainte: [Chei și drepturi](https://ocost.io/docs/ro/authentication.md)

Găsiți documente în fișierele firmei dumneavoastră după cuvintele și după sensul lor. Cuvintele se potrivesc și în interiorul cuvintelor compuse, așa că „Stuhl” găsește „Bürostuhl”. Sensul trece peste limbi, așa că „office chairs” găsește „Bürostühle”. Căutarea găsește documente. Nu răspunde la întrebări și nu schimbă nimic.

## Căutați

Apelați `GET /public/v1/search` cu cuvintele dumneavoastră în `q`. Cheia are nevoie de dreptul [`search:read`](https://ocost.io/docs/ro/authentication.md).

```bash
curl -sS -G https://api.ocost.io/public/v1/search \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "q=Wartungsvertrag Aufzug" \
  --data-urlencode "kind=contract"
```

```python
found = requests.get(
    f"{API}/search",
    headers=auth,
    params={"q": "Bürostuhl", "party": "Musterbüro Lieferant", "limit": 10},
    timeout=15,
).json()
for r in found["results"]:
    first = r["passages"][0] if r["passages"] else None
    print(r["number"], r["seller"], r["issue_date"], first and first["page"])
```

```javascript
const params = new URLSearchParams({ q: 'Skonto', kind: 'invoice' });
const found = await fetch(`${API}/search?${params}`, { headers: auth }).then((r) => r.json());
for (const r of found.results) console.log(r.number, r.file_url);
```

Răspunsul listează un rezultat pentru fiecare document, cele mai bune primele:

```json
{
  "results": [
    {
      "document_id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11",
      "file_id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
      "file_name": "invoice.pdf",
      "kind": "invoice",
      "number": "RE-2026-1187",
      "seller": "Musterbüro Lieferant GmbH",
      "buyer": "Beispiel Handel GmbH",
      "issue_date": "2026-11-03",
      "gross": 1270.92,
      "currency": "EUR",
      "pages": [1],
      "passages": [
        { "page": 1, "text": "4 Bürostuhl ErgoPlus schwarz à 189,00 €", "highlights": [[2, 11]], "found_by": "both" }
      ],
      "facts": [],
      "file_url": "/public/v1/files/01a1b08c-6e3a-7562-8f4a-7924722667b1",
      "document_url": "/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11"
    }
  ],
  "total": 1,
  "truncated": false,
  "meaning": "available"
}
```

## Restrângeți căutarea

Fiecare parametru în afară de `q` este opțional. Repetați `kind` pentru mai multe tipuri.

| Parametru | Semnificație |
| --- | --- |
| `q` | Obligatoriu, de la 1 la 200 de caractere. |
| `match` | `hybrid` folosește cuvinte și sens și este implicit. `keywords` folosește doar cuvinte, `meaning` doar sensul. `exact` găsește doar documentele care conțin `q` așa cum este scris, ignorând majusculele, diacriticele și spațiile. |
| `kind` | Un tip precum `invoice`, `credit_note`, `delivery_note` sau `contract`. |
| `since`, `until` | Data emiterii, ISO 8601, inclusiv. |
| `due_since`, `due_until` | Data scadenței unei facturi, ISO 8601, inclusiv. |
| `party` | Numele oricărei părți, așa cum a fost citit. Majusculele, umlauturile și formele juridice nu contează, așa că „Müller Sanitär GmbH” găsește „MUELLER SANITAER G.m.b.H.”. |
| `vat_id` | Codul de TVA al unei părți, așa cum a fost citit, ignorând spațiile și majusculele. |
| `gross_min`, `gross_max` | Suma brută în moneda firmei dumneavoastră, convertită la cursul BCE, pentru leu la cel al Băncii Naționale a Moldovei, inclusiv. |
| `direction` | `incoming` de la furnizori sau `outgoing` către clienți. |
| `status` | Al unei facturi: `open` (neplătită) sau `paid`. |
| `category` | Un cod ECLASS de orice nivel, opt cifre, precum `24000000`. Găsește documentele cu o linie în acea clasă sau sub ea. |
| `limit`, `offset` | `limit` de la 1 la 50, implicit 20. `offset` până la 250. |

## Citiți rezultatele

Fiecare rezultat își numește documentul și fișierul, cu câmpurile de mai sus. Un fișier fără document apare ca atare, cu `document_id` setat la `null`.

- `passages` conține până la cinci pasaje de circa 300 de caractere fiecare, cele mai bune primele.
- `highlights` marchează cuvintele găsite în `text`-ul unui pasaj ca intervale `[start, end)`.
- `found_by` spune dacă un pasaj s-a potrivit după `words`, după `meaning` sau după `both`.
- `facts` listează faptele de pe fișa unui document care conțin cuvintele dumneavoastră.
- `file_url` și `document_url` duc la fișier și la document în acest API.

`total` numără potrivirile. Ocost le ordonează pe cele mai bune 300, iar `truncated` spune că au fost mai multe. Fișierele șterse nu apar niciodată.

Când `meaning` este `unavailable`, căutarea după sens este în construcție sau nu poate fi accesată. Cuvintele răspund în continuare.

## Vezi și

- [Documentul](https://ocost.io/docs/ro/document.md): Schema ocost.document.v1 în termenii EN 16931 (se mapează pe UBL și CII): un exemplu, tip și direcție, surse, verificări, versiuni și fiecare câmp și valoare.
- [Unități și coduri](https://ocost.io/docs/ro/units.md): Listele de coduri ale documentului: unități UNECE cu cuvintele lor tipărite, monede și țări ISO, categorii de TVA, modalități de plată, tipuri de documente, identificatori, ECLASS.
- [Instrumente MCP](https://ocost.io/docs/ro/tools.md): Fiecare instrument al serverului MCP, după drept: ce face, argumentele sale și un exemplu de apel.
