# Context pack: Guías prácticas Source: https://nordvec.com/es/docs/guides/how-to Pack: https://nordvec.com/es/docs/packs/how-to This pack bundles one Nordvec guide with the guides it builds on and the guides it links to, in reading order, so an assistant reading it meets no reference it cannot follow. ## Contents 1. [Guías prácticas](https://nordvec.com/es/docs/guides/how-to) (this guide) 2. [Sube documentos desde tus propios sistemas](https://nordvec.com/es/docs/guides/how-to/push-documents) (linked from this guide) 3. [Filtra y ajusta la búsqueda](https://nordvec.com/es/docs/guides/how-to/filter-search) (linked from this guide) 4. [Lista y recupera documentos](https://nordvec.com/es/docs/guides/how-to/list-documents) (linked from this guide) --- # Guías prácticas Source: https://nordvec.com/es/docs/guides/how-to Recetas paso a paso para las tareas comunes de la API, desde buscar y listar documentos hasta enviar los tuyos. Cada guía te lleva desde la primera solicitud hasta un resultado funcional, mostrando los campos de la solicitud que utiliza y la respuesta que obtienes. Para ver todos los campos de cada operación, consulta la [referencia de la API](/docs/api). - [Sube documentos desde tus propios sistemas](https://nordvec.com/es/docs/guides/how-to/push-documents): Crea un origen de datos, sube documentos a él con una clave de API de indexación, elige quién puede leerlos y pausa o elimínalo cuando cambie el origen. - [Filtra y ajusta la búsqueda](https://nordvec.com/es/docs/guides/how-to/filter-search): Reduce una búsqueda de documentos con filtros de origen de datos, proveedor, tipo y fecha, y lee los resultados ordenados. - [Lista y recupera documentos](https://nordvec.com/es/docs/guides/how-to/list-documents): Navega por tus documentos con paginación por cursor, filtra y ordénalos, y obtén uno o varios por id. --- # Sube documentos desde tus propios sistemas Source: https://nordvec.com/es/docs/guides/how-to/push-documents Crea un origen de datos, sube documentos a él con una clave de API de indexación, elige quién puede leerlos y pausa o elimínalo cuando cambie el origen. La API de push indexa documentos de sistemas para los que Nordvec no tiene conector: una exportación de wiki interna, un archivo de tickets, una base de datos de notas. Tú envías el texto y quién puede leerlo; Nordvec lo almacena en la UE, lo indexa y lo hace buscable y citable como cualquier otro documento. Cada documento enviado llega a un **origen de datos**, un contenedor con nombre en tu espacio de trabajo que un administrador del espacio crea primero. Un push que nombra un origen de datos que no existe, o que está pausado, se rechaza. ## Crea un origen de datos [#crea-un-origen-de-datos] Abre **Configuración del espacio de trabajo > Orígenes de datos** y elige **Crear origen de datos**. Los administradores y propietarios del espacio de trabajo pueden hacerlo; en un espacio personal, eres tú. | Campo | Notas | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Nombre | Lo que ven las personas en la lista de configuración. Hasta 200 caracteres. | | Slug | Lo que nombra cada push. Letras minúsculas, dígitos, `-` y `_`, empezando por una letra o dígito, hasta 200 caracteres. No se puede cambiar después. | El slug `confluence-export` se usa en los ejemplos siguientes. ## Crea una clave de API de indexación [#crea-una-clave-de-api-de-indexación] Los envíos se autentican con una clave API de la clase **Indexing** que lleva el ámbito `index:write`; añade `index:status` para hacer seguimiento de la ingesta y `index:delete` para eliminar documentos o reemplazar un origen de datos completo. Crea una bajo **Configuración del espacio de trabajo > Claves API**; la clave en bruto empieza por `nv_eu_idx_` y se muestra una sola vez. Consulta [Autenticación](/docs/guides/authentication). Cada solicitud también nombra tu id de espacio de trabajo como `tenantId`, el id en la dirección de tu espacio en la app (`/w//...`), y debe ser el espacio al que pertenece la clave. ## Envía un documento [#envía-un-documento] `/documents/push` crea el documento o lo actualiza si ya existe uno con el mismo `id` en el origen de datos. ```bash curl https://nordvec.com/api/v1/documents/push \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: page-4711-2026-09-28" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "document": { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/markdown", "content": "# Travel expenses\n..." }, "permissions": {}, "sourceUrl": "https://wiki.example.com/pages/4711", "type": "policy" } }' ``` ```json { "documentId": "page-4711", "status": "queued", "updated": false } ``` * `id` es tu id estable para el documento dentro del origen de datos. Enviar el mismo `id` de nuevo lo actualiza; el contenido sin cambios se reconoce por su hash y no se indexa dos veces. * `body.mimeType` es uno de `text/plain`, `text/markdown`, `text/html`, `application/pdf` o los tipos de Word, Excel y PowerPoint (`.docx`, `.xlsx`, `.pptx`). El contenido binario se envía codificado en base64. * `sourceUrl` se convierte en el enlace "ir a la fuente" en cada cita del documento. Omítelo en un reenvío para mantener el almacenado, o envía `null` para borrarlo. * `type` establece el `content_type` del documento, que la búsqueda y los filtros de lista utilizan. Todo el cuerpo de la solicitud está limitado a 1 MB, por lo que un archivo grande o un lote grande responde con `413`; divídelo. ## Elige quién puede leerlo [#elige-quién-puede-leerlo] `permissions` es obligatorio en cada push, por lo que nunca se toma una decisión de compartición al omitir un campo. En un origen de datos visible para el espacio de trabajo: | `permissions` | Quién puede leer el documento | | ----------------------------------------- | ----------------------------------------------------------------------------- | | `{}` | Todos los miembros del espacio de trabajo | | `{ "allowedUsers": ["ana@example.com"] }` | Solo las personas enumeradas | | `{ "allowedGroups": ["GROUP_ID"] }` | Miembros de esos grupos del espacio de trabajo, incluidos los grupos anidados | | `{ "allowAllTenantMembers": false }` | Rechazado: un documento que nadie puede leer es un borrado | Para cambiar quién puede leer un documento sin enviar su contenido de nuevo, usa `POST /documents/push/permissions`. Hacer que un documento ya restringido sea visible para todo el espacio de trabajo además requiere el ámbito `index:acl-widen`, por lo que una sincronización rutinaria no puede deshacer silenciosamente una restricción que alguien estableció manualmente. ## Envía en lotes [#envía-en-lotes] `/documents/push/bulk` acepta hasta 100 documentos para un origen de datos por llamada. La respuesta cuenta `accepted` y `rejected` y da un resultado por documento, por lo que un documento incorrecto no hace fallar el lote. El límite de 1 MB en el cuerpo se aplica por llamada, así que divide las subidas grandes en varias llamadas bajo el mismo `uploadId`. ```bash curl https://nordvec.com/api/v1/documents/push/bulk \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "uploadId": "nightly-2026-09-28", "datasource": "confluence-export", "documents": [ { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export", "body": { "mimeType": "text/plain", "content": "..." }, "permissions": {} } ] }' ``` ## Reemplazar un origen de datos completo [#reemplazar-un-origen-de-datos-completo] Cuando tu sistema puede listar todo lo que debe contener un origen de datos, envía el listado completo como una **sesión de subida**, y los documentos que ya no contiene se mueven a la papelera cuando la sesión se cierra. Las sesiones necesitan una clave API de indexación que tenga `index:delete` además de `index:write`, porque el cierre elimina documentos; la clave que abre una es la única que puede continuarla. 1. Envía la primera página con `"isFirstPage": true`. Es la página `0`. 2. Envía cada página siguiente con su `pageIndex` (`1`, `2`, ...), en cualquier orden. Una página enviada dos veces se cuenta una sola vez, por lo que un reintento siempre es seguro. 3. Envía la última página con `"isLastPage": true` y su `pageIndex`. Un listado que quepa en una sola página envía `isFirstPage` y `isLastPage` juntos. La última página puede no llevar documentos. Todas las páginas usan el mismo `uploadId`, y cada respuesta incluye el progreso de la sesión en `upload`. La sesión solo se cierra cuando ha llegado cada página desde `0` hasta la última. Cerrarla mueve a la papelera cada documento en el origen de datos que ninguna página de la sesión nombró y que existía antes de que la sesión se abriera. Cualquier otro push al origen de datos mientras la sesión está activa mantiene el documento que nombra: un único push, un lote sin campos de sesión, una actualización de permisos y un reenvío de contenido sin cambios por igual. La papelera guarda lo que el cierre movió allí durante 30 días; enviar un documento de nuevo lo recupera, y lo mismo ocurre al restaurar toda la sesión (ver más abajo). Una sesión que no recibe ninguna página durante 24 horas caduca y se cierra sin eliminar nada. Una página rechazada se responde con `409 Conflict`, no escribe nada, y su `data.reason` indica el motivo: | `reason` | Qué hacer | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_incomplete` | Envía las páginas listadas en `missingPageIndexes` y, después, la última página de nuevo | | `deletion_confirmation_required` | El cierre movería a la papelera más del 20% del origen de datos. Si es correcto, envía la última página de nuevo con `"confirmDeletions"` establecido en `wouldTombstone` | | `deletion_confirmation_too_large` | `confirmDeletions` es mayor que el número de documentos que el origen de datos contenía cuando se abrió la sesión. Envía el recuento que esperas eliminar | | `upload_in_progress` | Hay una sesión abierta en este origen de datos. Si es de tu clave, termínala, espera a que expire o empieza de nuevo con `"forceRestartUpload": true` en tu primera página. Si la abrió otra clave, `forceRestartUpload` la reemplaza solo una vez que no haya recibido ninguna página durante una hora, desde la hora en `restartableAt` | | `upload_expired`, `upload_missing`, `upload_restarted` | La sesión ha desaparecido; empieza una nueva con un nuevo `uploadId` | | `upload_closed`, `upload_id_reused` | El `uploadId` está agotado; usa uno nuevo | | `page_index_required` | Tu clave tiene una sesión abierta en este origen de datos; envía `pageIndex` con la página | Para reanudar después de un fallo, lee la sesión con `GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (ámbito `index:status`). Su `missingPageIndexes` lista las páginas que aún faltan por enviar. ### Deshacer el cierre de una sesión [#deshacer-el-cierre-de-una-sesión] Si una sesión eliminó documentos que no debería haber eliminado, por ejemplo porque el listado que envió estaba incompleto, restáuralos en una sola llamada: ```bash curl https://nordvec.com/api/v1/documents/push/upload/restore \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "tenantId": "YOUR_WORKSPACE_ID", "datasource": "confluence-export", "uploadId": "nightly-2026-09-28" }' ``` La clave que abrió la sesión puede restaurarla, y también puede hacerlo un administrador del espacio de trabajo que haya iniciado sesión en Nordvec, para una sesión abierta por cualquier clave. Todos los documentos que el cierre movió a la papelera vuelven con el contenido que tenían, y la respuesta cuenta cuántos: `restored` están activos de nuevo, `purged` ya habían sido eliminados definitivamente por la papelera, y `skipped` habían cambiado desde el cierre (se volvieron a enviar o se eliminaron de nuevo) y se dejaron como están. Restaurar una sesión dos veces responde con los mismos recuentos de la primera restauración y `"replayed": true`, y pone en cola cualquier documento restaurado que aún esté esperando a ser indexado, por lo que repetir una restauración que no respondió es seguro. Una sesión puede restaurarse hasta 35 días después de su cierre, y mientras la papelera aún conserve algún documento que eliminó. Una restauración rechazada se responde con `409 Conflict` y su `data.reason`: | `reason` | Qué significa | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_not_closed` | La sesión nunca se cerró, por lo que no eliminó nada | | `upload_in_progress` | Hay una sesión abierta en el origen de datos. Restaura una vez que se haya cerrado o expirado | | `restore_purged` | Han pasado más de 30 días y la papelera ha eliminado todos los documentos. Vuelve a enviarlos | | `workspace_not_entitled` | El plan actual del espacio de trabajo no permite restaurar desde la papelera | | `corpus_cap_exceeded` | Restaurar los documentos superaría el límite de documentos del espacio de trabajo, por lo que ninguno se recuperó. `data.wouldRestore` es cuántos necesita y `data.headroom` cuántos caben. Libera espacio y, después, restaura de nuevo | ## Rastrea la ingesta [#rastrea-la-ingesta] Un push responde tan pronto como el documento se pone en cola. Pregunta por su progreso con `GET /documents/push/status` (ámbito `index:status`), filtrado por origen de datos o id de documento. Un documento pasa de `queued` a `processing`, luego a `completed`, o a `failed` con un `error`. ## Cuando un push es rechazado [#cuando-un-push-es-rechazado] Un push que nombra un origen de datos desconocido o pausado se responde con `422 Unprocessable Content`. El mensaje nombra el slug y enlaza a **Configuración del espacio de trabajo > Orígenes de datos** en tu espacio de trabajo, y el error `data` explica por qué y qué hacer: ```json { "defined": true, "code": "UNPROCESSABLE_CONTENT", "status": 422, "message": "Datasource \"confluence-export\" is paused and accepts no documents. A workspace admin resumes it under Workspace settings > Datasources: https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources", "data": { "why": "The datasource \"confluence-export\" is paused", "fix": "Resume it at https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources, then retry the push", "link": "https://nordvec.com/docs/guides/how-to/push-documents" } } ``` No reintentes estos automáticamente: solo tendrán éxito después de que un administrador cree o reanude el origen de datos. ## Elimina un documento [#elimina-un-documento] `POST /documents/push/delete` (ámbito `index:delete`) elimina un documento enviado mediante su `datasource` y `id`. Los documentos que dejas de enviar no se eliminan por sí solos: borra cada uno que retires, o envía el listado completo del origen de datos como una sesión de subida, descrita anteriormente. ## Pausa, reanuda y elimina [#pausa-reanuda-y-elimina] * **Pausar** rechaza cualquier push adicional en el origen de datos. Sus documentos siguen siendo buscables. Un push que ya se estaba escribiendo cuando lo pausas se completa. * **Reanudar** acepta pushes de nuevo. * **Eliminar** borra el origen de datos y todos los documentos enviados a él, junto con su índice de búsqueda. Tu propio sistema conserva su copia, por lo que volver a enviar después de recrear el origen de datos los restaura. Una eliminación no se puede deshacer. Si otro administrador cambió el origen de datos después de que se cargara tu lista, la acción se rechaza y la lista se recarga, para que decidas de nuevo en función de lo que hay ahora. Cada creación, pausa, reanudación y eliminación queda registrada en el registro de auditoría del espacio de trabajo. La lista de configuración muestra a quién es visible cada origen de datos. Quién puede leer un documento enviado lo decide el `permissions` enviado con él; crear, pausar o eliminar un origen de datos nunca amplía el acceso a nada. Las escrituras de push son idempotentes: repite el mismo `Idempotency-Key` en cada reintento de una escritura, y un duplicado se responde desde el primer intento en lugar de aplicarse dos veces. Consulta [Errores y límites de tasa](/docs/guides/errors-and-rate-limits). ## Pasos siguientes [#pasos-siguientes] --- # Filtra y ajusta la búsqueda Source: https://nordvec.com/es/docs/guides/how-to/filter-search Reduce una búsqueda de documentos con filtros de origen de datos, proveedor, tipo y fecha, y lee los resultados ordenados. `/documents/search` realiza una búsqueda de texto completo en el título y en todo el texto de tus documentos y devuelve las mejores coincidencias, cada una con una puntuación de relevancia y el documento de origen del que proviene. Esta guía explica cómo coincide la consulta, cómo acotar los resultados con filtros y cómo interpretar la respuesta. ## La solicitud [#la-solicitud] Solo `query` es obligatorio. Todo lo demás acota o limita los resultados. ```bash curl https://nordvec.com/api/v1/documents/search \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "renewal terms", "limit": 20, "datasource": "contracts", "sourceProvider": "google", "createdAfter": "2026-01-01T00:00:00Z", "createdBefore": "2026-07-01T00:00:00Z" }' ``` | Campo | Tipo | Notas | | ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Obligatorio. De 1 a 500 caracteres. Se entienden frases entre comillas, `or` y un `-` inicial para excluir una palabra. | | `limit` | integer | Opcional. De 1 a 50, valor por defecto 20. Cuántos resultados devolver. | | `datasource` | string | Opcional. Restringe a un único origen de datos por su slug (hasta 200 caracteres). | | `sourceProvider` | string | Opcional. Restringe a un único proveedor de conector, por ejemplo `google`, `sharepoint` o `slack`. | | `createdAfter` | string | Opcional. Marca de tiempo ISO 8601 con desplazamiento; solo documentos creados en o después de esta. | | `createdBefore` | string | Opcional. Marca de tiempo ISO 8601 con desplazamiento; solo documentos creados en o antes de esta. | | `contentType` | string | Opcional. Restringe a un único tipo de conocimiento, el que declara un documento enviado o un archivo de conocimiento (por ejemplo `policy` o `runbook`). | Todos los filtros se combinan con AND: un documento debe coincidir con la consulta **y** con todos los filtros que proporciones. Omite un filtro para ampliar la búsqueda. ## Cómo coincide la consulta [#cómo-coincide-la-consulta] * **Se busca en todo el documento.** El título y cada pasaje del texto cuentan, sin importar la longitud del documento. * **Las palabras coinciden en la forma en que las escribes, en cualquier idioma.** No hay lematización: `invoice` no coincide con `invoices`, y `tilbagebetaling` no coincide con `tilbagebetalingen`. Para capturar varias formas, únelas con `or`. * **Se ignoran los acentos en ambos lados.** `cafe` encuentra `café`, y `børnehave` y `bornehave` se encuentran entre sí. También se ignora el uso de mayúsculas y minúsculas. * **Operadores.** Pon palabras entre comillas dobles para buscarlas como frase, escribe `or` entre palabras para coincidir con cualquiera, y pon `-` antes de una palabra para excluir documentos que la contengan. ## Pruébalo [#pruébalo] Si has iniciado sesión, puedes ejecutar una búsqueda en tus propios documentos desde esta página. Cambia la consulta en la referencia de la API para probar con tus propios términos. Try it in the API reference: [`POST /api/v1/documents/search`](https://nordvec.com/docs/api#tag/documents/POST/documents/search) (Search documents). ## La respuesta [#la-respuesta] ```json { "results": [ { "id": "0198f2a4-6c1e-7d30-b6a1-2f9d54c08a11", "title": "Acme Corp Master Services Agreement", "snippet": "Automatic **renewal**: the agreement continues for successive twelve month **terms** unless…", "score": 0.82, "datasource": "contracts", "source_provider": "google", "source_type": null, "mime_type": "application/pdf", "content_type": null, "status": "indexed", "created_at": "2026-02-14T09:00:00Z", "updated_at": "2026-02-14T09:00:00Z" } ], "totalCount": 7 } ``` Cada resultado es un documento. Su `snippet` se extrae del pasaje que mejor coincidió, dondequiera que esté en el texto, con las palabras coincidentes envueltas en `**`; una palabra que escribiste sin acentos se encuentra y clasifica, pero puede aparecer sin marcar en el fragmento. El `score` va de 0 hasta, pero sin llegar a, 1 (mayor es más relevante), y los metadatos del documento de origen te permiten rastrear el resultado. `totalCount` es cuántos documentos coincidieron en total, lo que puede ser mayor que el número de `results` que solicitaste con `limit`. ## Interpretación de los resultados [#interpretación-de-los-resultados] * **Los resultados se ordenan por relevancia**, los más relevantes primero. Un documento se clasifica según su pasaje de mejor coincidencia. Usa `score` para descartar coincidencias débiles dentro de un mismo conjunto de resultados; las puntuaciones de diferentes consultas no están en la misma escala. * **`totalCount` vs `results.length`**: `results` contiene hasta `limit` elementos; `totalCount` es el recuento total de coincidencias. Si `totalCount` es mucho mayor que tu `limit`, ajusta la `query` o añade un filtro; no hay una segunda página de resultados de búsqueda. * **`status` te indica en qué fase del procesamiento está el documento.** Un documento se empareja con su texto almacenado, por lo que uno aún `processing` puede aparecer; `indexed` significa que se completaron todos los pasos. Consulta [Documentos y búsqueda](/docs/guides/concepts/documents) para ver el ciclo de vida. La búsqueda solo devuelve documentos que el llamante tiene permitido ver. El acceso se aplica en la base de datos, no en el código de la aplicación, por lo que un filtro nunca puede ampliar lo que el llamante ve. Para una clave API, esto es lo que el espacio de trabajo comparte; consulta [Quién ve un documento](/docs/guides/concepts/documents#who-sees-a-document). ## Pasos siguientes [#pasos-siguientes] --- # Lista y recupera documentos Source: https://nordvec.com/es/docs/guides/how-to/list-documents Navega por tus documentos con paginación por cursor, filtra y ordénalos, y obtén uno o varios por id. Cuando la [búsqueda](/docs/guides/how-to/filter-search) ordena los documentos por relevancia respecto a una consulta, el listado recorre todo tu corpus en orden. Úsalo para sincronizar, auditar o construir tu propio índice sobre lo que Nordvec almacena. El listado devuelve solo metadatos, sin el contenido del documento. ## Listar con paginación por cursor [#listar-con-paginación-por-cursor] `/documents/list` devuelve una página de documentos junto con un `nextCursor` opaco. Pasa ese cursor de vuelta para obtener la página siguiente y detente cuando `hasMore` sea `false`. ```bash curl "https://nordvec.com/api/v1/documents/list?limit=50" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` ```json { "items": [ { "id": "…", "title": "Q3 Financial Report", "status": "indexed", "datasource": "finance", "created_at": "2026-04-01T10:00:00Z" } ], "nextCursor": "eyJrIjoi…", "hasMore": true } ``` Una vez iniciada la sesión, puedes listar la primera página de tus documentos desde aquí: Try it in the API reference: [`GET /api/v1/documents/list`](https://nordvec.com/docs/api#tag/documents/GET/documents/list) (List documents). Para recorrer todas las páginas, repite el proceso hasta que `hasMore` sea `false`, pasando cada vez el `nextCursor` de la respuesta anterior, con los mismos `sort` y `direction`: ```bash curl "https://nordvec.com/api/v1/documents/list?limit=50&cursor=eyJrIjoi…" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` El cursor es opaco, no lo analices ni lo construyas. Pásalo exactamente como lo devolvió la respuesta anterior. Un cursor no válido, o uno de un orden de clasificación diferente, será rechazado. ## Filtrar y ordenar [#filtrar-y-ordenar] Todos los filtros son opcionales y se combinan con AND. El orden predeterminado es de más reciente a más antiguo. | Campo | Tipo | Notas | | -------------------------------- | ------- | ---------------------------------------------------------------------------- | | `limit` | integer | De 1 a 200 (50 por defecto). | | `cursor` | string | Cursor opaco de la página anterior. | | `datasource` | string | Restringe a un único origen de datos por su slug (hasta 200 caracteres). | | `status` | enum | `indexed`, `processing` o `failed`. | | `sourceProvider` | string | Restringe a un único proveedor de conector, por ejemplo `google` o `slack`. | | `contentType` | string | Restringe a un único tipo de conocimiento, por ejemplo `policy` o `runbook`. | | `createdAfter` / `createdBefore` | string | Marcas de tiempo ISO 8601 con desplazamiento, ambas inclusivas. | | `sort` | enum | `createdAt` (predeterminado), `updatedAt` o `title`. | | `direction` | enum | `desc` (predeterminado) o `asc`. | ```bash curl "https://nordvec.com/api/v1/documents/list?status=indexed&datasource=finance&sort=updatedAt&direction=desc&limit=100" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` ### Qué orden usar para recorrer [#qué-orden-usar-para-recorrer] * **Enumeración completa en una sola pasada**: `sort=createdAt`. La hora de creación nunca cambia, por lo que cada documento aparece exactamente una vez. * **Actualización incremental desde una marca de agua**: `sort=updatedAt&direction=asc`. Un documento actualizado mientras lo recorres puede aparecer dos veces, así que haz upsert por `id`. * **Orden de visualización**: `updatedAt` o `title` descendente. Un documento actualizado entre dos páginas puede moverse más allá del cursor y ser omitido, así que no lo uses para enumerar. ## Obtener un único documento [#obtener-un-único-documento] `/documents/{id}` devuelve los metadatos, el estado de procesamiento y el texto de un documento. Un texto largo puede leerse en ventanas: `contentOffset` y `contentMaxChars` (contadas en unidades de código UTF-16) seleccionan una ventana, y `content_range` informa sobre la ventana y la longitud total, así que sigue leyendo hasta que `offset + length` alcance `total`. ```bash curl "https://nordvec.com/api/v1/documents/DOCUMENT_ID?contentMaxChars=100000" \ -H "Authorization: Bearer $NORDVEC_API_KEY" ``` ## Obtener varios a la vez [#obtener-varios-a-la-vez] Para resolver hasta 200 IDs en una sola llamada, envíalos por POST a `/documents/batch` en lugar de hacer una solicitud por ID. El lote devuelve metadatos y estado de procesamiento; `content` siempre es `null`, así que lee el texto con la llamada de documento único. ```bash curl https://nordvec.com/api/v1/documents/batch \ -H "Authorization: Bearer $NORDVEC_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "ids": ["DOCUMENT_ID_1", "DOCUMENT_ID_2"] }' ``` El listado, al igual que la búsqueda, solo devuelve documentos que el llamante tiene permiso para ver. `status` te indica en qué fase del procesamiento se encuentra un documento: `processing` mientras aún se está indexando, `failed` si no se pudo procesar. Consulta [Documentos y búsqueda](/docs/guides/concepts/documents) para ver el ciclo de vida. ## Pasos siguientes [#pasos-siguientes]