Adjuntos

Sistema de archivos adjuntos

Keirost permite adjuntar archivos a cualquier documento o registro del sistema. Los archivos se almacenan en el storage configurado (local o S3-compatible).

Modelo

interface Attachment {
  id: string;
  filename: string;           // Nombre original del archivo
  stored_name: string;        // Nombre en storage (UUID)
  mime_type: string;         // "application/pdf", "image/png"
  size: number;               // Tamanio en bytes
  storage_path: string;      // Ruta en storage
  resource_type: string;      // "sales_invoice", "item", "plugin"
  resource_id: string;        // ID del documento/registro asociado
  uploaded_by: string;
  uploaded_at: string;
}

---

Subir archivo

POST /api/attachments/upload
Authorization: Bearer <token>
Content-Type: multipart/form-data

file: <archivo>
resource_type: sales_invoice
resource_id: inv_2026_0012
description: Factura escaneada

Respuesta:

{
  "data": {
    "id": "att_001",
    "filename": "factura-2026-0012.pdf",
    "stored_name": "a1b2c3d4-e5f6.pdf",
    "mime_type": "application/pdf",
    "size": 456789,
    "storage_path": "/attachments/sales_invoice/inv_2026_0012/a1b2c3d4-e5f6.pdf",
    "created_at": "2026-05-08T10:00:00Z"
  }
}

Tamaños máximos

Tipo	Tamano máximo
Documento PDF	20 MB
Imagen	5 MB
Otro	10 MB

---

Listar adjuntos

GET /api/attachments?resource_type=sales_invoice&resource_id=inv_2026_0012

{
  "data": [
    {
      "id": "att_001",
      "filename": "factura-2026-0012.pdf",
      "size": 456789,
      "mime_type": "application/pdf",
      "uploaded_by": "admin",
      "uploaded_at": "2026-05-08T10:00:00Z"
    }
  ]
}

---

Descargar archivo

GET /api/attachments/:id/download

Devuelve el archivo con el Content-Type correcto y el nombre original como filename.

---

Eliminar adjunto

DELETE /api/attachments/:id

Solo lo puede eliminar el usuario que lo subio o un admin.

---

Configuración de storage

Adaptadores disponibles

Adaptador	Descripción
local	Almacenamiento en disco (por defecto)
s3	Amazon S3 o compatible (MinIO, Backblaze B2)
gcs	Google Cloud Storage
azure	Azure Blob Storage

Configurar S3

PATCH /api/config/storage
Content-Type: application/json

{
  "adapter": "s3",
  "bucket": "keirost-storage",
  "region": "eu-west-1",
  "access_key_id": "AKIA...",
  "secret_access_key": "...",
  "endpoint": "https://s3.eu-west-1.amazonaws.com"
}

Configurar storage local

PATCH /api/config/storage
Content-Type: application/json

{
  "adapter": "local",
  "base_path": "/data/storage"
}

---

Panel de adjuntos en la UI

El componente AttachmentsPanel muestra los archivos adjuntos de un documento:

<AttachmentsPanel
  resourceType="sales_invoice"
  resourceId="inv_2026_0012"
  onUpload={(file) => uploadFile(file)}
  onDelete={(id) => deleteAttachment(id)}
/>

Incluye:

• Lista de archivos con icono según tipo
• Tamanio y fecha de subida
• Botón de descarga
• Botón de eliminación (con confirmación)
• Zona de drop para arrastrar archivos

---

Resumen de endpoints

Método	Ruta	Descripción
POST	/api/attachments/upload	Subir archivo
GET	/api/attachments	Listar adjuntos (con filtros)
GET	/api/attachments/:id	Ver metadatos
GET	/api/attachments/:id/download	Descargar archivo
DELETE	/api/attachments/:id	Eliminar adjunto
GET	/api/config/storage	Ver config de storage
PATCH	/api/config/storage	Guardar config de storage