# Búsqueda
> Buscar en todos los documentos por palabras y por significado: parámetros, filtros, resultados, ejemplos.
>
> Antes: [Claves y permisos](https://ocost.io/docs/es/authentication.md)

Encuentra documentos en los archivos de tu empresa por sus palabras y por su significado. Las palabras también coinciden dentro de palabras compuestas, así que "Stuhl" encuentra "Bürostuhl". El significado cruza idiomas, así que "sillas de oficina" encuentra "Bürostühle". La búsqueda encuentra documentos. No responde preguntas ni cambia nada.

## Busca

Llama a `GET /public/v1/search` con tus palabras en `q`. La clave necesita el permiso [`search:read`](https://ocost.io/docs/es/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 respuesta lista un resultado por documento, el mejor primero:

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

## Acota la búsqueda

Todos los parámetros salvo `q` son opcionales. Repite `kind` para varios tipos.

| Parámetro | Significado |
| --- | --- |
| `q` | Obligatorio, de 1 a 200 caracteres. |
| `match` | `hybrid` usa palabras y significado, y es el valor por defecto. `keywords` usa solo palabras, `meaning` solo el significado. `exact` encuentra solo documentos que contienen `q` tal como está escrito, sin importar mayúsculas, acentos ni espacios. |
| `kind` | Un tipo como `invoice`, `credit_note`, `delivery_note` o `contract`. |
| `since`, `until` | La fecha de emisión, ISO 8601, inclusive. |
| `due_since`, `due_until` | La fecha de vencimiento de una factura, ISO 8601, inclusive. |
| `party` | El nombre de cualquier parte tal como se leyó. Las mayúsculas, las diéresis y las formas jurídicas no importan, así que "Müller Sanitär GmbH" encuentra "MUELLER SANITAER G.m.b.H.". |
| `vat_id` | El NIF-IVA de una parte tal como se leyó, sin importar espacios ni mayúsculas. |
| `gross_min`, `gross_max` | El bruto en la moneda de tu empresa, convertido al tipo del BCE, para el leu al del Banco Nacional de Moldavia, inclusive. |
| `direction` | `incoming` de proveedores, o `outgoing` a clientes. |
| `status` | El de una factura: `open` (sin pagar) o `paid`. |
| `category` | Un código ECLASS de cualquier nivel, de ocho dígitos como `24000000`. Encuentra documentos con una línea en esa clase o por debajo de ella. |
| `limit`, `offset` | `limit` de 1 a 50, 20 por defecto. `offset` hasta 250. |

## Lee los resultados

Cada resultado nombra su documento y su archivo, con los campos de arriba. Un archivo sin documento aparece como él mismo, con `document_id` en `null`.

- `passages` contiene hasta cinco pasajes de unos 300 caracteres cada uno, el mejor primero.
- `highlights` marca las palabras encontradas en el `text` de un pasaje como rangos `[start, end)`.
- `found_by` dice si un pasaje coincidió por `words`, por `meaning` o por `both`.
- `facts` lista los datos de la ficha de un documento que contienen tus palabras.
- `file_url` y `document_url` llevan al archivo y al documento en esta API.

`total` cuenta las coincidencias. Ocost ordena las 300 mejores, y `truncated` dice que había más. Los archivos borrados nunca aparecen.

Cuando `meaning` es `unavailable`, la búsqueda por significado se está construyendo o no responde. Las palabras siguen respondiendo.

## Véase también

- [El documento](https://ocost.io/docs/es/document.md): El esquema ocost.document.v1 en términos de EN 16931 (se corresponde con UBL y CII): un ejemplo, tipo y dirección, fuentes, comprobaciones, versiones, y cada campo y valor.
- [Unidades y códigos](https://ocost.io/docs/es/units.md): Las listas de códigos del documento: unidades UNECE con sus palabras impresas, monedas y países ISO, categorías de IVA, medios de pago, tipos de documento, identificadores, ECLASS.
- [Herramientas MCP](https://ocost.io/docs/es/tools.md): Cada herramienta del servidor MCP, por permiso: qué hace, sus argumentos y una llamada de ejemplo.
