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

Находите документы в файлах вашей компании по их словам и по их смыслу. Слова находятся и внутри составных слов, поэтому «Stuhl» находит «Bürostuhl». Смысл не зависит от языка, поэтому «office chairs» находит «Bürostühle». Поиск находит документы. Он не отвечает на вопросы и ничего не меняет.

## Искать

Вызовите `GET /public/v1/search` со словами в `q`. Ключу нужно право [`search:read`](https://ocost.io/docs/ru/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/ru/document.md): Схема ocost.document.v1 в терминах EN 16931 (переносится в UBL и CII): пример, вид и направление, источники, проверки, версии, каждое поле и значение.
- [Единицы и коды](https://ocost.io/docs/ru/units.md): Списки кодов документа: единицы UNECE с их печатными словами, валюты и страны ISO, категории НДС, способы оплаты, виды документов, коды, ECLASS.
- [Инструменты MCP](https://ocost.io/docs/ru/tools.md): Каждый инструмент сервера MCP по правам: что он делает, его аргументы и пример вызова.
