# Wyszukiwanie
> Przeszukiwać wszystkie dokumenty po słowach i po znaczeniu: parametry, filtry, wyniki, przykłady.
>
> Najpierw: [Klucze i uprawnienia](https://ocost.io/docs/pl/authentication.md)

Znajduj dokumenty w plikach Twojej firmy po ich słowach i po ich znaczeniu. Słowa pasują także wewnątrz złożeń, więc „Stuhl” znajduje „Bürostuhl”. Znaczenie przekracza granice języków, więc „krzesła biurowe” znajdują „Bürostühle”. Wyszukiwanie znajduje dokumenty. Nie odpowiada na pytania i niczego nie zmienia.

## Szukaj

Wywołaj `GET /public/v1/search` ze słowami w `q`. Klucz potrzebuje uprawnienia [`search:read`](https://ocost.io/docs/pl/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);
```

Odpowiedź wymienia jeden wynik na dokument, od najlepszego:

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

## Zawęź wyniki

Każdy parametr poza `q` jest opcjonalny. Powtórz `kind`, aby podać kilka rodzajów.

| Parametr | Znaczenie |
| --- | --- |
| `q` | Wymagany, od 1 do 200 znaków. |
| `match` | `hybrid` używa słów i znaczenia i jest domyślny. `keywords` używa tylko słów, `meaning` tylko znaczenia. `exact` znajduje tylko dokumenty zawierające `q` tak, jak je zapisano, bez względu na wielkość liter, akcenty i odstępy. |
| `kind` | Rodzaj, na przykład `invoice`, `credit_note`, `delivery_note` lub `contract`. |
| `since`, `until` | Data wystawienia, ISO 8601, włącznie. |
| `due_since`, `due_until` | Termin płatności faktury, ISO 8601, włącznie. |
| `party` | Nazwa dowolnej strony, tak jak ją odczytano. Wielkość liter, umlauty i formy prawne nie mają znaczenia, więc „Müller Sanitär GmbH” znajduje „MUELLER SANITAER G.m.b.H.”. |
| `vat_id` | NIP UE strony, tak jak go odczytano, bez względu na spacje i wielkość liter. |
| `gross_min`, `gross_max` | Kwota brutto w walucie Twojej firmy, przeliczona po kursie EBC, dla leja po kursie Narodowego Banku Mołdawii, włącznie. |
| `direction` | `incoming` od dostawców albo `outgoing` do klientów. |
| `status` | Status faktury: `open` (nieopłacona) lub `paid`. |
| `category` | Kod ECLASS dowolnego poziomu, osiem cyfr, na przykład `24000000`. Znajduje dokumenty z pozycją w tej klasie lub poniżej niej. |
| `limit`, `offset` | `limit` od 1 do 50, domyślnie 20. `offset` do 250. |

## Odczytaj wyniki

Każdy wynik wskazuje swój dokument i plik, z polami pokazanymi powyżej. Plik bez dokumentu pojawia się sam, z `document_id` ustawionym na `null`.

- `passages` zawiera do pięciu fragmentów po około 300 znaków, od najlepszego.
- `highlights` zaznacza dopasowane słowa w `text` fragmentu jako zakresy `[start, end)`.
- `found_by` mówi, czy fragment pasuje przez `words`, przez `meaning` czy przez `both`.
- `facts` wymienia fakty z karty dokumentu, które zawierają Twoje słowa.
- `file_url` i `document_url` prowadzą do pliku i dokumentu w tym API.

`total` liczy dopasowania. Ocost układa w kolejności najlepsze 300, a `truncated` mówi, że było ich więcej. Usunięte pliki nigdy się nie pojawiają.

Gdy `meaning` ma wartość `unavailable`, wyszukiwanie po znaczeniu jest w budowie lub niedostępne. Słowa nadal dają wyniki.

## Zobacz też

- [Dokument](https://ocost.io/docs/pl/document.md): Schemat ocost.document.v1 w pojęciach EN 16931 (odwzorowywalny na UBL i CII): przykład, rodzaj i kierunek, źródła, kontrole, wersje oraz każde pole i każda wartość.
- [Jednostki i kody](https://ocost.io/docs/pl/units.md): Listy kodów dokumentu: jednostki UNECE z drukowanymi słowami, waluty i kraje ISO, kategorie VAT, sposoby płatności, rodzaje dokumentów, identyfikatory, ECLASS.
- [Narzędzia MCP](https://ocost.io/docs/pl/tools.md): Każde narzędzie serwera MCP, według uprawnienia: co robi, jego argumenty i przykładowe wywołanie.
