Saltar para o conteúdo principal

​
Ficheiros

Os ficheiros são documentos PDF enviados para o DokStamp antes de serem anexados a certificados ou documentos. Cada ficheiro só pode ser utilizado por um certificado — uma vez anexado, fica marcado como usado e não pode ser reutilizado.

​
O objeto ficheiro

{
  "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
  "original_name": "diploma-maria-silva.pdf",
  "mime_type": "application/pdf",
  "extension": "pdf",
  "size": 245760,
  "used_at": null,
  "file": "https://storage.dokstamp.eu/files/h8i9j0k1.pdf"
}
CampoTipoDescrição
uuidstringIdentificador único — utilize como file_uuid ao criar certificados
original_namestringNome original do ficheiro
mime_typestringTipo MIME (ex.: application/pdf)
extensionstringExtensão do ficheiro
sizeintegerTamanho do ficheiro em bytes
used_atdatetime|nullNulo = disponível. Não nulo = já anexado a um certificado.
filestringURL de transferência direta

​
Enviar ficheiros

POST /files
Aceita multipart/form-data. É possível enviar múltiplos ficheiros numa única requisição.
ParâmetroTipoObrigatórioDescrição
files[]fileSimUm ou mais ficheiros PDF
# Enviar um único ficheiro
curl -X POST https://api.dokstamp.eu/files \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}" \
  -F "files[]=@/caminho/para/diploma-maria-silva.pdf"

# Enviar múltiplos ficheiros de uma vez
curl -X POST https://api.dokstamp.eu/files \
  -H "Authorization: Bearer {TOKEN}" \
  -H "Accept: application/json" \
  -H "X-Tenant: {TENANT}" \
  -F "files[]=@diploma-1.pdf" \
  -F "files[]=@diploma-2.pdf" \
  -F "files[]=@diploma-3.pdf"
Resposta 201: 
{
  "data": [
    {
      "uuid": "h8i9j0k1-l2m3-4567-nopq-678901234567",
      "original_name": "diploma-maria-silva.pdf",
      "mime_type": "application/pdf",
      "size": 245760,
      "used_at": null
    }
  ]
}

​
Listar ficheiros

GET /files
Filtrar por ficheiros não utilizados (disponíveis para anexar a novos certificados): 
GET /files?where[used_at]=null

​
Obter metadados do ficheiro

GET /files/{uuid}

​
Transferir um ficheiro

GET /files/{uuid}/download
Este endpoint é público — nenhum cabeçalho Authorization é necessário. Partilhe este URL diretamente com signatários, estudantes ou empregadores.
curl "https://api.dokstamp.eu/files/h8i9j0k1-l2m3-4567-nopq-678901234567/download" \
  --output diploma.pdf

​
Atualizar metadados do ficheiro

PATCH /files/{uuid}
PUT   /files/{uuid}

​
Eliminar um ficheiro

DELETE /files/{uuid}
Não é possível eliminar um ficheiro que já está anexado a um certificado (used_at não é nulo). Elimine ou revogue o certificado primeiro.

​
Deduplicação

A API calcula um hash para cada ficheiro enviado. Se o mesmo conteúdo de ficheiro for enviado duas vezes, o segundo envio devolve o registo de ficheiro existente em vez de criar um duplicado. Isto evita a acumulação desnecessária de armazenamento em fluxos de envio em lote.