Guia da API de ficheiros

Os ficheiros (designados por recursos em alguns esquemas) contêm a evidência associada aos Registos: imagens, PDFs, documentos e artefactos de digitalização. Um ficheiro pode ser associado diretamente a um Registo ou usado como valor de um campo do tipo recurso.

Existem dois métodos de carregamento: um pedido POST único e simples para ficheiros pequenos e o protocolo tus, retomável, para ficheiros grandes. Esquemas completos: referência da API.

Resumo dos endpoints

Operação	Método e caminho
Carregamento simples	POST /api/v1/files
Carregamento retomável (tus)	POST /api/v1/files/upload, seguido de PATCH /api/v1/files/upload/{id}
Finalizar carregamentos tus	POST /api/v1/files/finalize
Transferir	GET /api/v1/files/{resource_id}/download
URLs assinados	POST /api/v1/files/urls
Procurar ficheiros	GET /api/v1/files/search
Listar ficheiros (cursor)	GET /api/v1/files
Listar os ficheiros de um Registo	GET /api/v1/threads/{thread_id}/files

Os pedidos relativos a ficheiros exigem que a identidade atual pertença à Equipa selecionada, que, por sua vez, tem de pertencer à organização selecionada. Isto aplica-se a pessoas e a Contas de Serviço. O carregamento para um Registo exige acesso de edição; os carregamentos privados têm de se destinar a um Registo e exigem permissão para gerir os respetivos ativos privados. Os ficheiros não associados só podem ser lidos pela Equipa proprietária quando não são privados.

Carregamento simples

Para ficheiros que possam ser enviados facilmente num único pedido, envie um POST multipart/form-data com o file e destinos de associação opcionais. A resposta inclui o recurso criado com um URL assinado:

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 associa o ficheiro como valor de um campo do tipo recurso; isPrivate restringe a visibilidade.

Carregamento retomável (tus)

Os ficheiros grandes utilizam o protocolo de carregamento retomável tus 1.0 em /api/v1/files/upload, seguido de uma chamada de finalização que transforma o carregamento concluído num registo de recurso. O fluxo é carregamento → finalização → (já associado ou associação através de campos).

1. Criar o carregamento. Envie um POST com cabeçalhos tus; os valores de Upload-Metadata são codificados em base64 e filename é obrigatório (fieldId, threadId e isPrivate são opcionais):

   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>

   Guarde o <upload-id> de Location para a finalização. A resposta final fornece o identificador permanente do recurso, que pode ser diferente. Declare o Registo, o campo e a privacidade pretendidos durante a criação; estes não podem ser alterados durante a finalização. Upload-Length tem de ser uma contagem de bytes positiva e conhecida.

2. Enviar os bytes (retomável — pedidos PATCH repetidos continuam a partir de 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

   Os pedidos de carregamento toleram períodos de inatividade mais longos. Para retomar após uma interrupção, envie um pedido HEAD para o mesmo URL a fim de ler o Upload-Offset atual e, em seguida, envie um PATCH a partir dessa posição. Qualquer biblioteca de cliente tus 1.0 (por exemplo, tus-js-client) comunica através deste protocolo por si.

3. Finalizar. Os carregamentos só se tornam registos de recurso após a finalização:

   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 aceita vários carregamentos de uma só vez; cada item do pedido recebe o identificador de carregamento tus como resId, juntamente com filename e size (fieldId e isPrivate são opcionais). O nome do ficheiro, o tamanho, o Registo, o campo e a privacidade têm de corresponder ao pedido de criação do carregamento. Utilize a mesma identidade autenticada e o mesmo contexto de organização/Equipa para a criação, os fragmentos, os pedidos HEAD e DELETE e a finalização. As sessões de carregamento expiram sete dias após a criação. Só os carregamentos concluídos podem ser finalizados.

   Uma nova tentativa de finalização idêntica dentro desse período devolve os recursos originais com novos URLs assinados. Um lote tem de conter apenas carregamentos concluídos novos ou apenas carregamentos anteriormente finalizados. Os carregamentos finalizados não podem receber pedidos PATCH nem ser terminados através de tus.

Nota

Os endpoints tus utilizam o protocolo de comunicação tus em vez de JSON, pelo que aparecem apenas de forma resumida na referência da API. O comportamento acima é definido pela configuração tus do servidor (/upload e /upload/{id} em /api/v1/files).

Transferências e URLs assinados

• GET /api/v1/files/{resource_id}/download — redireciona para um URL assinado do ficheiro.
• POST /api/v1/files/urls?ids=<id>&ids=<id> — gera URLs assinados de curta duração para acesso direto ao armazenamento de objetos; utilize-os quando um navegador ou sistema a jusante necessitar dos bytes sem passar por um proxy.

Cuidado

Os URLs assinados expiram. Guarde os identificadores dos recursos, nunca os URLs assinados — solicite novamente os URLs quando precisar de renovar o acesso.

Pesquisa e listagem

Existem dois tipos de consulta:

• GET /api/v1/files/search — pesquisa indexada por página com q, threadId, mimeFilters e includeArchived.
• GET /api/v1/files — listagem paginada por cursor (cursor, pageSize; includeArchived é obrigatório), filtrada por threadId ou createdBy.

Para ficheiros no contexto de um único Registo, prefira GET /api/v1/threads/{thread_id}/files (consulte o guia de Registos).

Páginas relacionadas

• Guia da API de Registos — associar ficheiros a campos e miniaturas de Registos
• Modelo principal — onde os ficheiros se enquadram no domínio
• Referência da API — detalhes completos dos parâmetros e esquemas