# Suche

Finden Sie Belege in den Dateien Ihres Unternehmens nach ihren Wörtern und nach ihrer Bedeutung. Wörter treffen auch in Komposita, „Stuhl“ findet also „Bürostuhl“. Bedeutung geht über Sprachen hinweg, „office chairs“ findet also „Bürostühle“. Die Suche findet Belege. Sie beantwortet keine Fragen und ändert nichts.

## Suchen

Rufen Sie `GET /public/v1/search` mit Ihren Wörtern in `q` auf. Der Schlüssel braucht die Berechtigung `search:read`.

```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);
```

Die Antwort listet ein Ergebnis je Beleg, das beste zuerst:

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

## Eingrenzen

Jeder Parameter außer `q` ist optional. Wiederholen Sie `kind` für mehrere Arten.

| Parameter | Bedeutung |
| --- | --- |
| `q` | Pflicht, 1 bis 200 Zeichen. |
| `match` | `hybrid` nutzt Wörter und Bedeutung und ist der Standard. `keywords` nutzt nur Wörter, `meaning` nur Bedeutung. `exact` findet nur Belege, die `q` wie geschrieben enthalten, ohne Rücksicht auf Groß- und Kleinschreibung, Akzente und Leerzeichen. |
| `kind` | Eine Art wie `invoice`, `credit_note`, `delivery_note` oder `contract`. |
| `since`, `until` | Das Ausstellungsdatum, ISO 8601, einschließlich. |
| `due_since`, `due_until` | Das Fälligkeitsdatum einer Rechnung, ISO 8601, einschließlich. |
| `party` | Der Name einer beliebigen Partei, wie gelesen. Groß- und Kleinschreibung, Umlaute und Rechtsformen zählen nicht, „Müller Sanitär GmbH“ findet also „MUELLER SANITAER G.m.b.H.“. |
| `vat_id` | Die USt-IdNr. einer Partei, wie gelesen, ohne Rücksicht auf Leerzeichen und Schreibweise. |
| `gross_min`, `gross_max` | Der Bruttobetrag in der Währung Ihres Unternehmens, zum EZB-Kurs umgerechnet, einschließlich. |
| `direction` | `incoming` von Lieferanten oder `outgoing` an Kunden. |
| `status` | Bei einer Rechnung: `open` (unbezahlt) oder `paid`. |
| `category` | Ein ECLASS-Code beliebiger Ebene, acht Ziffern wie `24000000`. Er findet Belege mit einer Position in dieser Klasse oder darunter. |
| `limit`, `offset` | `limit` 1 bis 50, standardmäßig 20. `offset` bis 250. |

## Die Ergebnisse lesen

Jedes Ergebnis nennt seinen Beleg und seine Datei, mit den Feldern oben. Eine Datei ohne Beleg kommt als sie selbst, mit `document_id` gleich `null`.

- `passages` enthält bis zu fünf Stellen von je etwa 300 Zeichen, die beste zuerst.
- `highlights` markiert die getroffenen Wörter im `text` einer Stelle als Bereiche `[start, end)`.
- `found_by` sagt, ob eine Stelle nach `words`, nach `meaning` oder nach `both` traf.
- `facts` listet die Fakten der Belegkarte, die Ihre Wörter enthalten.
- `file_url` und `document_url` führen zur Datei und zum Beleg in dieser API.

`total` zählt die Treffer. Ocost ordnet die besten 300, und `truncated` sagt, dass es mehr gab. Gelöschte Dateien erscheinen nie.

Ist `meaning` gleich `unavailable`, wird die Suche nach Bedeutung gerade aufgebaut oder ist nicht erreichbar. Die Wörter antworten trotzdem.