Búsqueda
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.
curl -sS -G https://api.ocost.io/public/v1/search \
-H "Authorization: Bearer $OCOST_KEY" \
--data-urlencode "q=Wartungsvertrag Aufzug" \
--data-urlencode "kind=contract"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"])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:
{
"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.
passagescontiene hasta cinco pasajes de unos 300 caracteres cada uno, el mejor primero.highlightsmarca las palabras encontradas en eltextde un pasaje como rangos[start, end).found_bydice si un pasaje coincidió porwords, pormeaningo porboth.factslista los datos de la ficha de un documento que contienen tus palabras.file_urlydocument_urlllevan 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.