Guía de la API de archivos

Los archivos (denominados recursos en algunos esquemas) contienen las evidencias adjuntas a las Fichas: imágenes, archivos PDF, documentos y artefactos de escaneo. Un archivo se puede adjuntar directamente a una Ficha o como valor de un campo de tipo recurso.

Hay dos vías de carga: una solicitud POST sencilla de una sola operación para archivos pequeños y el protocolo tus reanudable para los grandes. Esquemas completos: referencia de la API.

Resumen de los endpoints

Operación	Método y ruta
Carga sencilla	POST /api/v1/files
Carga reanudable (tus)	POST /api/v1/files/upload, después PATCH /api/v1/files/upload/{id}
Finalizar cargas tus	POST /api/v1/files/finalize
Descargar	GET /api/v1/files/{resource_id}/download
URL firmadas	POST /api/v1/files/urls
Buscar archivos	GET /api/v1/files/search
Enumerar archivos (cursor)	GET /api/v1/files
Enumerar los archivos de una Ficha	GET /api/v1/threads/{thread_id}/files

Las solicitudes de archivos requieren una pertenencia vigente al Equipo seleccionado, que debe pertenecer a la organización seleccionada. Esto se aplica tanto a las personas como a las Cuentas de Servicio. Cargar en una Ficha requiere acceso de edición; las cargas privadas deben dirigirse a una Ficha y requieren permiso para gestionar sus activos privados. Los archivos no adjuntos solo son legibles por el Equipo propietario cuando no son privados.

Carga sencilla

Para los archivos que se puedan enviar cómodamente en una sola solicitud, envía mediante POST un multipart/form-data con file y los destinos de adjunto opcionales. La respuesta incluye el recurso creado con una URL firmada:

curl

curl -fsS "$APID_URL/api/v1/files" \
  -H "Authorization: Bearer $DUST_TOKEN" \
  -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
  -F "file=@inspection-report.pdf" \
  -F "threadId=$THREAD_ID"

TypeScript

const resources = await client.files.upload({
  file,               // a File
  threadId,           // optional: attach to a Thread
  // fieldId,         // optional: attach as a field value
  // isPrivate: true, // optional
});

fieldId adjunta el archivo como valor de un campo de tipo recurso; isPrivate restringe su visibilidad.

Carga reanudable (tus)

Los archivos grandes utilizan el protocolo de carga reanudable tus 1.0 en /api/v1/files/upload, seguido de una llamada de finalización que convierte la carga completada en un registro de recurso. El flujo es carga → finalización → (ya adjunto o adjuntar mediante campos).

1. Crea la carga. Envía una solicitud POST con las cabeceras de tus; los valores de Upload-Metadata están codificados en base64 y filename es obligatorio (fieldId, threadId e isPrivate son opcionales):

   curl -i -X POST "$APID_URL/api/v1/files/upload" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Length: 52428800" \
     -H "Upload-Metadata: filename $(printf 'video.mp4' | base64),threadId $(printf %s "$THREAD_ID" | base64)"
   # → 201 Created
   # → Location: …/api/v1/files/upload/<upload-id>

   Conserva el <upload-id> de Location para la finalización. La respuesta final proporciona el ID permanente del recurso, que puede ser distinto. Declara la Ficha, el campo y la privacidad previstos al crear la carga; no se pueden cambiar durante la finalización. Upload-Length debe ser un número de bytes positivo y conocido.

2. Envía los bytes (de forma reanudable: las solicitudes PATCH sucesivas continúan desde Upload-Offset):

   curl -i -X PATCH "$APID_URL/api/v1/files/upload/$UPLOAD_ID" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Tus-Resumable: 1.0.0" \
     -H "Upload-Offset: 0" \
     -H "Content-Type: application/offset+octet-stream" \
     --data-binary @video.mp4

   Las solicitudes de carga toleran periodos de inactividad más largos. Para reanudar después de una interrupción, envía HEAD a la misma URL para leer el valor actual de Upload-Offset y, después, continúa con PATCH desde ese punto. Cualquier biblioteca cliente compatible con tus 1.0 (por ejemplo, tus-js-client) gestiona este protocolo por ti.

3. Finaliza. Las cargas solo se convierten en registros de recursos después de la finalización:

   curl -fsS "$APID_URL/api/v1/files/finalize" \
     -H "Authorization: Bearer $DUST_TOKEN" \
     -H "Dust-Ctx-Org-Id: $DUST_ORG_ID" \
     -H "Content-Type: application/json" \
     -d '{
       "threadId": "'"$THREAD_ID"'",
       "requests": [
         { "resId": "'"$UPLOAD_ID"'", "filename": "video.mp4", "size": 52428800 }
       ]
     }'

   POST /api/v1/files/finalize acepta varias cargas a la vez; cada elemento de la solicitud recibe el ID de carga tus como resId, además de filename y size (fieldId e isPrivate son opcionales). El nombre del archivo, el tamaño, la Ficha, el campo y la privacidad deben coincidir con la solicitud de creación de la carga. Utiliza la misma identidad autenticada y el mismo contexto de organización/Equipo para la creación, los fragmentos, HEAD, DELETE y la finalización. Las sesiones de carga caducan siete días después de su creación. Solo se pueden finalizar las cargas completadas.

   Si se vuelve a intentar una finalización idéntica dentro de ese periodo, se devuelven los recursos originales con URL firmadas nuevas. Un lote debe contener únicamente cargas nuevas completadas o únicamente cargas finalizadas con anterioridad. Las cargas finalizadas no se pueden modificar mediante PATCH ni cancelar a través de tus.

Nota

Los endpoints de tus utilizan el protocolo de comunicación tus en lugar de JSON, por lo que solo aparecen de forma resumida en la referencia de la API. El comportamiento anterior está definido por la configuración de tus del servidor (/upload y /upload/{id} bajo /api/v1/files).

Descargas y URL firmadas

• GET /api/v1/files/{resource_id}/download — redirige a una URL firmada del archivo.
• POST /api/v1/files/urls?ids=<id>&ids=<id> — genera URL firmadas de corta duración para acceder directamente al almacenamiento de objetos; utilízalas cuando un navegador o sistema posterior necesite los bytes sin pasar por un proxy.

Precaución

Las URL firmadas caducan. Almacena los ID de los recursos, nunca las URL firmadas; vuelve a solicitar las URL cuando necesites acceso actualizado.

Búsqueda y enumeración

Existen dos estilos de consulta:

• GET /api/v1/files/search — búsqueda indexada por páginas con q, threadId, mimeFilters e includeArchived.
• GET /api/v1/files — enumeración paginada mediante cursor (cursor, pageSize; includeArchived es obligatorio), filtrada por threadId o createdBy.

Para los archivos en el contexto de una sola Ficha, utiliza preferentemente GET /api/v1/threads/{thread_id}/files (consulta la guía de Fichas).

Páginas relacionadas

• Guía de la API de Fichas — adjuntar archivos a campos y miniaturas de Fichas
• Modelo principal — dónde se sitúan los archivos en el dominio
• Referencia de la API — información completa sobre parámetros y esquemas