File Storage

O Building Block File Storage fornece funcionalidades para upload, download e gerenciamento de arquivos usando Amazon S3.

Visão Geral

O módulo File Storage e tenant-scoped e oferece:

• Upload de arquivos via URLs pre-assinadas
• Download seguro com URLs temporarias
• Categorização de arquivos por tipo
• Associação de arquivos a entidades de negócio

Base URL

https://api.catalisa.io/file-storage

Recursos

Recurso	Descrição
Arquivos	Upload, download e gerenciamento de arquivos

Endpoints

Método	Endpoint	Descrição	Permissão
POST	/api/v1/files	Criar arquivo (obter URL de upload)	FILES_CREATE
GET	/api/v1/files	Listar arquivos	FILES_READ
GET	/api/v1/files/:id	Obter arquivo	FILES_READ
POST	/api/v1/files/:id/confirm-upload	Confirmar upload	FILES_CREATE
GET	/api/v1/files/:id/upload-url	Obter nova URL de upload	FILES_CREATE
GET	/api/v1/files/:id/download-url	Obter URL de download	FILES_READ
DELETE	/api/v1/files/:id	Excluir arquivo	FILES_DELETE

Tipos de Arquivo Suportados

MIME Type	Extensão	Descrição
application/pdf	.pdf	Documentos PDF
image/png	.png	Imagens PNG
image/jpeg	.jpg, .jpeg	Imagens JPEG
application/octet-stream	*	Binario generico

Categorias de Arquivo

Categoria	Descrição	Uso Comum
IDENTITY	Documentos de identidade	RG, CNH, passaporte
ADDRESS	Comprovante de endereço	Conta de luz, extrato
INCOME	Comprovante de renda	Holerite, IR, extrato
CONTRACT	Contratos	CCB, termos
COLLATERAL	Garantias	Documentos de garantia
OTHER	Outros	Documentos diversos

Fluxo de Upload

O upload de arquivos segue um fluxo de 3 etapas:

1. Criar registro    ──►  2. Upload para S3   ──►  3. Confirmar upload
   POST /files              PUT {uploadUrl}          POST /files/:id/confirm-upload
   ↓                        ↓                        ↓
   Recebe uploadUrl         Arquivo no S3            uploaded = true

Diagrama de Sequencia

Cliente              API                  S3
   │                  │                   │
   │ POST /files      │                   │
   │─────────────────►│                   │
   │                  │                   │
   │ { uploadUrl }    │                   │
   │◄─────────────────│                   │
   │                  │                   │
   │ PUT uploadUrl (arquivo)              │
   │─────────────────────────────────────►│
   │                  │                   │
   │                  │         200 OK    │
   │◄─────────────────────────────────────│
   │                  │                   │
   │ POST /confirm    │                   │
   │─────────────────►│                   │
   │                  │                   │
   │ { uploaded: true}│                   │
   │◄─────────────────│                   │

URLs Pre-assinadas

As URLs de upload e download são pre-assinadas pelo S3, o que significa:

• Validas por tempo limitado (15 minutos)
• Não requerem autenticação adicional
• Permitem acesso direto ao S3

Atenção

• URLs de upload expiram em 15 minutos
• URLs de download expiram em 15 minutos
• Se a URL expirar, solicite uma nova

Estrutura de Dados

Arquivo

{
  "data": {
    "type": "files",
    "id": "uuid",
    "attributes": {
      "name": "documento.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 1048576,
      "category": "IDENTITY",
      "businessId": "origination-123",
      "uploaded": true,
      "createdBy": "user-uuid",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  }
}