# Suche
> Alle Belege nach Wörtern und nach Bedeutung durchsuchen: Parameter, Filter, Ergebnisse, Beispiele.
>
> Vorher: [Schlüssel und Berechtigungen](https://ocost.io/docs/de/authentication.md)

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`](https://ocost.io/docs/de/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);
```

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, beim Leu zum Kurs der Nationalbank Moldaus, 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.

## Siehe auch

- [Der Beleg](https://ocost.io/docs/de/document.md): Das Schema ocost.document.v1 in den Begriffen der EN 16931 (auf UBL und CII abbildbar): ein Beispiel, Art und Richtung, Quellen, Prüfungen, Versionen und jedes Feld und jeder Wert.
- [Einheiten und Codes](https://ocost.io/docs/de/units.md): Die Codelisten des Belegs: UNECE-Einheiten mit ihren gedruckten Wörtern, ISO-Währungen und -Länder, Steuerkategorien, Zahlungsarten, Belegarten, Kennungen, ECLASS.
- [MCP-Werkzeuge](https://ocost.io/docs/de/tools.md): Jedes Werkzeug des MCP-Servers, nach Berechtigung: was es tut, seine Argumente und ein Beispielaufruf.
