Attachments
Upload e download de arquivos (S3/MinIO), com metadados vinculáveis a entidades.
Arquivos armazenados em object storage (S3-compatível — ex.: MinIO). Cada attachment
guarda o metadado no banco (filePath, originalFilename, tipo, vínculo opcional a uma
entidade) e o binário no storage. Base path: /api/attachments · autenticação de
usuário.
| Método | Rota | Scope | Resource | Sucesso |
|---|---|---|---|---|
POST | /api/attachments | create | resource:attachments | 201 |
GET | /api/attachments | read | resource:attachments | 200 |
GET | /api/attachments/:id | read | resource:attachments_id | 200 |
PUT | /api/attachments/:id | update | resource:attachments_id | 200 |
DELETE | /api/attachments/:id | delete | resource:attachments_id | 204 |
O arquivo é salvo em {S3_BASE_PATH}/{entityType}/{uuid}.{ext}. O filePath retornado é
a chave no bucket; o download é feito pelo próprio endpoint (o binário não é exposto por
URL pública).
Upload (criar attachment)
POST /api/attachments — multipart/form-data. Faz o upload do arquivo para o storage
e cria o registro.
Campos (form-data)
| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
file | binary | sim | o arquivo em si |
entityType | enum | não | padrão DOCUMENT |
entityId | uuid | não | vincula o arquivo a uma entidade; pode ser null |
description | string | não | pode ser null |
Tipos permitidos: image/jpg, image/jpeg, image/png, image/webp, application/pdf.
curl -X POST http://localhost:3000/api/attachments \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-F "file=@documento.pdf" \
-F "description=Contrato assinado"201 Created
{
"id": "a1b2c3d4-e5f6-4789-a123-456789abcdef",
"entityType": "DOCUMENT",
"filePath": "ancat/document/9f8e...c1.pdf",
"originalFilename": "documento.pdf",
"description": "Contrato assinado",
"external": false,
"entityId": null,
"userId": "u1b2c3d4-e5f6-4789-a123-456789abcdef",
"createdAt": "2026-07-13T12:00:00.000Z",
"updatedAt": "2026-07-13T12:00:00.000Z"
}400 Bad Request — arquivo ausente, tipo não permitido (InvalidAttachmentTypeError) ou
falha no upload ao storage (FailedToUploadFileError).
Download (baixar o arquivo)
GET /api/attachments/:id — busca o binário no storage e o retorna como stream, com
Content-Type do arquivo e Content-Disposition: attachment (nome original, se houver).
curl -L http://localhost:3000/api/attachments/a1b2c3d4-e5f6-4789-a123-456789abcdef \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-o documento.pdf404 Not Found — attachment não encontrado. · 400 Bad Request — falha ao baixar do
storage (FailedToDownloadFileError).
Listar attachments (metadados)
GET /api/attachments — retorna os metadados (não os binários).
Filtros opcionais
| Param | Tipo | Descrição |
|---|---|---|
entityType | enum | filtra por tipo (DOCUMENT) |
entityId | uuid | attachments vinculados a uma entidade |
userId | uuid | attachments de um usuário |
startDate | date | criados a partir de (ISO 8601) |
endDate | date | criados até (ISO 8601) |
curl "http://localhost:3000/api/attachments?entityId=e1b2c3d4-...&startDate=2026-07-01" \
-H "Authorization: Bearer $ACCESS_TOKEN"Editar metadados
PUT /api/attachments/:id — atualiza apenas metadados (não troca o arquivo).
| Campo | Tipo | Regras |
|---|---|---|
entityId | uuid | ou null |
description | string | ou null |
Retorna 200 com o attachment; 404 se não existir.
Remover attachment
DELETE /api/attachments/:id — remove o arquivo do storage e o registro (soft delete).
Retorna 204 No Content; 404 se não existir.