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"

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ámetroSignificado
qObligatorio, de 1 a 200 caracteres.
matchhybrid 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.
kindUn tipo como invoice, credit_note, delivery_note o contract.
since, untilLa fecha de emisión, ISO 8601, inclusive.
due_since, due_untilLa fecha de vencimiento de una factura, ISO 8601, inclusive.
partyEl 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_idEl NIF-IVA de una parte tal como se leyó, sin importar espacios ni mayúsculas.
gross_min, gross_maxEl bruto en la moneda de tu empresa, convertido al tipo del BCE, para el leu al del Banco Nacional de Moldavia, inclusive.
directionincoming de proveedores, o outgoing a clientes.
statusEl de una factura: open (sin pagar) o paid.
categoryUn 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, offsetlimit 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