Поиск
Находите документы в файлах вашей компании по их словам и по их смыслу. Слова находятся и внутри составных слов, поэтому «Stuhl» находит «Bürostuhl». Смысл не зависит от языка, поэтому «office chairs» находит «Bürostühle». Поиск находит документы. Он не отвечает на вопросы и ничего не меняет.
Искать
Вызовите GET /public/v1/search со словами в q. Ключу нужно право search:read.
curl -sS -G https://api.ocost.io/public/v1/search \
-H "Authorization: Bearer $OCOST_KEY" \
--data-urlencode "q=Wartungsvertrag Aufzug" \
--data-urlencode "kind=contract"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"])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);Ответ перечисляет по одному результату на документ, лучшие первыми:
{
"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, поиск по смыслу строится или недоступен. Поиск по словам всё равно отвечает.