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 pré-assinadas
• Download seguro com URLs temporarias
• Categorização de arquivos por tipo
• Associação de arquivos a entidades de negócio

Base URL

https://file-storage.stg.catalisa.app

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:

Etapas do Upload

1. Criar registro do arquivo

• Endpoint: POST /api/v1/files
• Cliente envia metadados (nome, mimeType, categoria, etc.)
• API cria registro no banco de dados com uploaded = false
• API gera URL pré-assinada do S3 para upload
• API retorna { uploadUrl } para o cliente

2. Upload direto para S3

• Endpoint: PUT {uploadUrl} (URL pré-assinada do S3)
• Cliente faz upload do arquivo binário diretamente para o S3
• Não requer autenticação adicional (URL já é assinada)
• S3 armazena o arquivo
• S3 retorna 200 OK ao cliente

3. Confirmar upload

• Endpoint: POST /api/v1/files/:id/confirm-upload
• Cliente confirma que o upload foi concluído
• API marca o registro como uploaded = true
• API retorna confirmação

Sequência Completa

Atores: Cliente, API, S3

Passo 1 - Criar registro:

• Cliente → API: POST /api/v1/files com metadados
  • API cria registro no banco
  • API gera URL pré-assinada do S3
  • API retorna { uploadUrl, id }

Passo 2 - Upload para S3:

• Cliente → S3: PUT {uploadUrl} com arquivo binário
  • S3 armazena o arquivo
  • S3 retorna 200 OK

Passo 3 - Confirmar upload:

• Cliente → API: POST /api/v1/files/:id/confirm-upload
  • API marca uploaded = true
  • API retorna confirmação { uploaded: true }

URLs Pre-assinadas

As URLs de upload e download são pré-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"
    }
  }
}