# Recherche
> Rechercher chaque document par ses mots et par son sens : paramètres, filtres, résultats, exemples.
>
> Avant: [Clés et autorisations](https://ocost.io/docs/fr/authentication.md)

Trouvez des documents dans les fichiers de votre entreprise par leurs mots et par leur sens. Les mots se trouvent aussi à l'intérieur des mots composés, donc « Stuhl » trouve « Bürostuhl ». Le sens traverse les langues, donc « office chairs » trouve « Bürostühle ». La recherche trouve des documents. Elle ne répond à aucune question et ne change rien.

## Rechercher

Appelez `GET /public/v1/search` avec vos mots dans `q`. La clé a besoin de l'autorisation [`search:read`](https://ocost.io/docs/fr/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);
```

La réponse liste un résultat par document, le meilleur d'abord :

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

## Affiner

Chaque paramètre sauf `q` est facultatif. Répétez `kind` pour plusieurs types.

| Paramètre | Signification |
| --- | --- |
| `q` | Obligatoire, de 1 à 200 caractères. |
| `match` | `hybrid` utilise les mots et le sens, et c'est la valeur par défaut. `keywords` n'utilise que les mots, `meaning` que le sens. `exact` ne trouve que les documents contenant `q` tel qu'écrit, sans tenir compte de la casse, des accents ni des espaces. |
| `kind` | Un type comme `invoice`, `credit_note`, `delivery_note` ou `contract`. |
| `since`, `until` | La date d'émission, ISO 8601, bornes incluses. |
| `due_since`, `due_until` | La date d'échéance d'une facture, ISO 8601, bornes incluses. |
| `party` | Le nom d'une partie quelconque, tel que lu. La casse, les trémas et les formes juridiques ne comptent pas, donc « Müller Sanitär GmbH » trouve « MUELLER SANITAER G.m.b.H. ». |
| `vat_id` | Le numéro de TVA d'une partie, tel que lu, sans tenir compte des espaces ni de la casse. |
| `gross_min`, `gross_max` | Le montant TTC dans la devise de votre entreprise, converti au taux de la BCE, pour le leu à celui de la Banque nationale de Moldavie, bornes incluses. |
| `direction` | `incoming` venant des fournisseurs, ou `outgoing` vers les clients. |
| `status` | Celui d'une facture : `open` (impayée) ou `paid`. |
| `category` | Un code ECLASS de n'importe quel niveau, huit chiffres comme `24000000`. Il trouve les documents ayant une ligne dans cette classe ou en dessous. |
| `limit`, `offset` | `limit` de 1 à 50, 20 par défaut. `offset` jusqu'à 250. |

## Lire les résultats

Chaque résultat nomme son document et son fichier, avec les champs montrés plus haut. Un fichier sans document arrive tel quel, avec `document_id` à `null`.

- `passages` contient jusqu'à cinq passages d'environ 300 caractères chacun, le meilleur d'abord.
- `highlights` marque les mots trouvés dans le `text` d'un passage, en intervalles `[start, end)`.
- `found_by` dit si un passage a été trouvé par `words`, par `meaning` ou par `both`.
- `facts` liste les faits de la fiche d'un document qui contiennent vos mots.
- `file_url` et `document_url` mènent au fichier et au document dans cette API.

`total` compte les résultats. Ocost classe les 300 meilleurs, et `truncated` indique qu'il y en avait plus. Les fichiers supprimés n'apparaissent jamais.

Quand `meaning` vaut `unavailable`, la recherche par le sens est en construction ou injoignable. Les mots répondent toujours.

## Voir aussi

- [Le document](https://ocost.io/docs/fr/document.md): Le schéma ocost.document.v1 dans les termes de l'EN 16931 (transposable en UBL et CII) : un exemple, type et sens, sources, contrôles, versions, et chaque champ et chaque valeur.
- [Unités et codes](https://ocost.io/docs/fr/units.md): Les listes de codes du document : unités UNECE avec leurs mots imprimés, devises et pays ISO, catégories de TVA, moyens de paiement, types de documents, identifiants, ECLASS.
- [Outils MCP](https://ocost.io/docs/fr/tools.md): Chaque outil du serveur MCP, par autorisation : ce qu'il fait, ses arguments et un exemple d'appel.
