Поиск

Находите документы в файлах вашей компании по их словам и по их смыслу. Слова находятся и внутри составных слов, поэтому «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"

Ответ перечисляет по одному результату на документ, лучшие первыми:

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 символов.
matchhybrid ищет по словам и по смыслу и действует по умолчанию. 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Сумма брутто в валюте вашей компании, пересчитанная по курсу ЕЦБ, для лея по курсу Национального банка Молдовы, включительно.
directionincoming от поставщиков или outgoing клиентам.
statusСтатус счёта: open (не оплачен) или paid.
categoryКод ECLASS любого уровня, восемь цифр, например 24000000. Находит документы со строкой в этом классе или под ним.
limit, offsetlimit от 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, поиск по смыслу строится или недоступен. Поиск по словам всё равно отвечает.

См. также