# Пошук
> Шукати в усіх документах за словами і за змістом: параметри, фільтри, результати, приклади.
>
> Спершу: [Ключі та дозволи](https://ocost.io/docs/uk/authentication.md)

Знаходьте документи у файлах вашої компанії за їхніми словами і за змістом. Слова знаходяться і всередині складених слів, тож «Stuhl» знаходить «Bürostuhl». Зміст працює між мовами, тож «office chairs» знаходить «Bürostühle». Пошук знаходить документи. Він не відповідає на запитання і нічого не змінює.

## Пошук

Викличте `GET /public/v1/search` зі своїми словами в `q`. Ключу потрібен дозвіл [`search:read`](https://ocost.io/docs/uk/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);
```

Відповідь перелічує один результат на документ, від найкращого:

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

## Звузьте пошук

Кожен параметр, крім `q`, необов’язковий. Повторіть `kind` для кількох видів.

| Параметр | Зміст |
| --- | --- |
| `q` | Обов’язковий, від 1 до 200 символів. |
| `match` | `hybrid` шукає за словами і за змістом, це типове значення. `keywords` шукає лише за словами, `meaning` лише за змістом. `exact` знаходить лише документи, що містять `q` як написано, без урахування регістру, діакритики та пробілів. |
| `kind` | Вид, наприклад `invoice`, `credit_note`, `delivery_note` або `contract`. |
| `since`, `until` | Дата документа, ISO 8601, включно. |
| `due_since`, `due_until` | Строк оплати рахунку, ISO 8601, включно. |
| `party` | Назва будь-якої сторони, як її прочитано. Регістр, умлаути і правові форми не мають значення, тож «Müller Sanitär GmbH» знаходить «MUELLER SANITAER G.m.b.H.». |
| `vat_id` | Номер платника ПДВ сторони, як його прочитано, без урахування пробілів і регістру. |
| `gross_min`, `gross_max` | Сума брутто у валюті вашої компанії, перерахована за курсом ЄЦБ, для лея за курсом Національного банку Молдови, включно. |
| `direction` | `incoming` від постачальників або `outgoing` клієнтам. |
| `status` | Статус рахунку: `open` (неоплачений) або `paid`. |
| `category` | Код ECLASS будь-якого рівня, вісім цифр, наприклад `24000000`. Знаходить документи з рядком у цьому класі або нижче за ним. |
| `limit`, `offset` | `limit` від 1 до 50, типово 20. `offset` до 250. |

## Читайте результати

Кожен результат називає свій документ і файл із полями, показаними вище. Файл без документа приходить сам, з `document_id`, рівним `null`.

- `passages` містить до п’яти уривків приблизно по 300 символів, від найкращого.
- `highlights` позначає знайдені слова в `text` уривка як діапазони `[start, end)`.
- `found_by` каже, чи уривок знайдено за словами (`words`), за змістом (`meaning`) чи за обома (`both`).
- `facts` перелічує факти на картці документа, що містять ваші слова.
- `file_url` і `document_url` ведуть до файлу та документа в цьому API.

`total` рахує збіги. Ocost ранжує найкращі 300, а `truncated` каже, що їх було більше. Видалені файли ніколи не з’являються.

Коли `meaning` дорівнює `unavailable`, пошук за змістом будується або недоступний. Пошук за словами все одно відповідає.

## Див. також

- [Документ](https://ocost.io/docs/uk/document.md): Схема ocost.document.v1 у термінах EN 16931 (відображається на UBL і CII): приклад, вид і напрям, джерела, перевірки, версії, кожне поле і значення.
- [Одиниці та коди](https://ocost.io/docs/uk/units.md): Списки кодів документа: одиниці UNECE з їхніми друкованими словами, валюти й країни ISO, категорії ПДВ, способи оплати, види документів, коди, ECLASS.
- [Інструменти MCP](https://ocost.io/docs/uk/tools.md): Кожен інструмент сервера MCP за дозволом: що він робить, його аргументи і приклад виклику.
