Arquivos

Gerenciamento de arquivos com upload e download via S3.

Endpoints

Método	Endpoint	Descrição	Permissão
POST	`/api/v1/files`	Criar arquivo	`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 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`

Criar Arquivo

POST /api/v1/files

Cria o registro do arquivo e retorna uma URL pré-assinada para upload.

Request

Campo	Tipo	Obrigatório	Descrição
`name`	string	Sim	Nome do arquivo
`mimeType`	string	Sim	Tipo MIME (`application/pdf`, `image/png`, `image/jpeg`)
`sizeBytes`	integer	Sim	Tamanho em bytes
`category`	string	Sim	Categoria do arquivo
`businessId`	string	Não	ID da entidade associada

cURL
JavaScript

curl -X POST 'https://file-storage.stg.catalisa.app/api/v1/files' \
  -H 'Authorization: Bearer SEU_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "documento-identidade.pdf",
    "mimeType": "application/pdf",
    "sizeBytes": 1048576,
    "category": "IDENTITY",
    "businessId": "origination-12345"
  }'

const response = await fetch('https://file-storage.stg.catalisa.app/api/v1/files', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'documento-identidade.pdf',
    mimeType: 'application/pdf',
    sizeBytes: 1048576,
    category: 'IDENTITY',
    businessId: 'origination-12345',
  }),
});

const { data, uploadUrl, expiresAt } = await response.json();

Response (201 Created)

{
  "data": {
    "type": "files",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "documento-identidade.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 1048576,
      "category": "IDENTITY",
      "businessId": "origination-12345",
      "uploaded": false,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  },
  "uploadUrl": "https://bucket.s3.amazonaws.com/files/...?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
  "expiresAt": "2024-01-15T10:45:00Z"
}

Fazer Upload para S3

Apos criar o registro, use a uploadUrl para enviar o arquivo diretamente ao S3.

cURL
JavaScript

curl -X PUT 'URL_DE_UPLOAD_RECEBIDA' \
  -H 'Content-Type: application/pdf' \
  --data-binary @documento-identidade.pdf

async function uploadFile(uploadUrl, file) {
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    body: file,
    headers: {
      'Content-Type': file.type,
    },
  });

  if (!response.ok) {
    throw new Error('Falha no upload');
  }

  return true;
}

// Uso com File API (browser)
const fileInput = document.querySelector('input[type="file"]');
const file = fileInput.files[0];
await uploadFile(uploadUrl, file);

Importante

O upload deve ser feito diretamente para a URL do S3
Use o mesmo Content-Type informado na criação
A URL expira em 15 minutos

Confirmar Upload

POST /api/v1/files/:fileId/confirm-upload

Confirma que o upload foi concluido com sucesso.

cURL
JavaScript

curl -X POST 'https://file-storage.stg.catalisa.app/api/v1/files/550e8400-e29b-41d4-a716-446655440000/confirm-upload' \
  -H 'Authorization: Bearer SEU_TOKEN'

const fileId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://file-storage.stg.catalisa.app/api/v1/files/${fileId}/confirm-upload`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const result = await response.json();

Response (200 OK)

{
  "data": {
    "type": "files",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "name": "documento-identidade.pdf",
      "mimeType": "application/pdf",
      "uploaded": true,
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  }
}

Listar Arquivos

GET /api/v1/files

Lista arquivos com suporte a paginação e filtros.

Query Parameters

Parâmetro	Tipo	Descrição
`page[number]`	integer	Número da página
`page[size]`	integer	Itens por página
`filter[category]`	string	Filtrar por categoria
`filter[businessId]`	string	Filtrar por businessId
`filter[uploaded]`	boolean	Filtrar por status de upload

cURL
JavaScript

curl 'https://file-storage.stg.catalisa.app/api/v1/files?filter[category]=IDENTITY&filter[uploaded]=true' \
  -H 'Authorization: Bearer SEU_TOKEN'

const params = new URLSearchParams({
  'filter[category]': 'IDENTITY',
  'filter[uploaded]': 'true',
});

const response = await fetch(`https://file-storage.stg.catalisa.app/api/v1/files?${params}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const { data, meta } = await response.json();

Response (200 OK)

{
  "data": [
    {
      "type": "files",
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "attributes": {
        "name": "documento-identidade.pdf",
        "mimeType": "application/pdf",
        "category": "IDENTITY",
        "uploaded": true
      }
    }
  ],
  "meta": {
    "totalItems": 25,
    "totalPages": 2,
    "currentPage": 1
  }
}

Obter Arquivo

GET /api/v1/files/:fileId

Obtém detalhes de um arquivo específico.

cURL
JavaScript

curl 'https://file-storage.stg.catalisa.app/api/v1/files/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const fileId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://file-storage.stg.catalisa.app/api/v1/files/${fileId}`, {
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

const file = await response.json();

Obter URL de Upload

GET /api/v1/files/:fileId/upload-url

Obtém uma nova URL pré-assinada para upload (caso a anterior tenha expirado).

cURL
JavaScript

curl 'https://file-storage.stg.catalisa.app/api/v1/files/550e8400-e29b-41d4-a716-446655440000/upload-url' \
  -H 'Authorization: Bearer SEU_TOKEN'

const fileId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://file-storage.stg.catalisa.app/api/v1/files/${fileId}/upload-url`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const { uploadUrl, expiresAt } = await response.json();

Response (200 OK)

{
  "uploadUrl": "https://bucket.s3.amazonaws.com/files/...?X-Amz-Algorithm=...",
  "expiresAt": "2024-01-15T11:00:00Z"
}

Obter URL de Download

GET /api/v1/files/:fileId/download-url

Obtém uma URL pré-assinada para download do arquivo.

cURL
JavaScript

curl 'https://file-storage.stg.catalisa.app/api/v1/files/550e8400-e29b-41d4-a716-446655440000/download-url' \
  -H 'Authorization: Bearer SEU_TOKEN'

const fileId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(
  `https://file-storage.stg.catalisa.app/api/v1/files/${fileId}/download-url`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  }
);

const { downloadUrl, expiresAt } = await response.json();

// Abrir em nova aba ou fazer download
window.open(downloadUrl, '_blank');

Response (200 OK)

{
  "downloadUrl": "https://bucket.s3.amazonaws.com/files/...?X-Amz-Algorithm=...",
  "expiresAt": "2024-01-15T11:00:00Z"
}

Excluir Arquivo

DELETE /api/v1/files/:fileId

Remove um arquivo do sistema e do S3.

cURL
JavaScript

curl -X DELETE 'https://file-storage.stg.catalisa.app/api/v1/files/550e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer SEU_TOKEN'

const fileId = '550e8400-e29b-41d4-a716-446655440000';

const response = await fetch(`https://file-storage.stg.catalisa.app/api/v1/files/${fileId}`, {
  method: 'DELETE',
  headers: {
    'Authorization': `Bearer ${token}`,
  },
});

// Status 204 No Content = sucesso

Response (204 No Content)

Sem corpo de resposta.

Exemplo Completo de Upload

async function uploadDocument(token, file, category, businessId) {
  // 1. Criar registro do arquivo
  const createResponse = await fetch('https://file-storage.stg.catalisa.app/api/v1/files', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: file.name,
      mimeType: file.type,
      sizeBytes: file.size,
      category,
      businessId,
    }),
  });

  const { data, uploadUrl } = await createResponse.json();
  const fileId = data.id;

  // 2. Upload para S3
  const uploadResponse = await fetch(uploadUrl, {
    method: 'PUT',
    body: file,
    headers: {
      'Content-Type': file.type,
    },
  });

  if (!uploadResponse.ok) {
    throw new Error('Falha no upload para S3');
  }

  // 3. Confirmar upload
  await fetch(
    `https://file-storage.stg.catalisa.app/api/v1/files/${fileId}/confirm-upload`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${token}`,
      },
    }
  );

  return fileId;
}

// Uso
const fileId = await uploadDocument(
  token,
  document.querySelector('input[type="file"]').files[0],
  'IDENTITY',
  'origination-123'
);

Erros Comuns

Código	Erro	Descrição
400	`VALIDATION`	MIME type inválido ou campos ausentes
404	`NOT_FOUND`	Arquivo não encontrado
409	`CONFLICT`	Arquivo já confirmado

Endpoints​

Criar Arquivo​

Request​

Response (201 Created)​

Fazer Upload para S3​

Confirmar Upload​

Response (200 OK)​

Listar Arquivos​

Query Parameters​

Response (200 OK)​

Obter Arquivo​

Obter URL de Upload​

Response (200 OK)​

Obter URL de Download​

Response (200 OK)​

Excluir Arquivo​

Response (204 No Content)​

Exemplo Completo de Upload​

Erros Comuns​

Endpoints

Criar Arquivo

Request

Response (201 Created)

Fazer Upload para S3

Confirmar Upload

Response (200 OK)

Listar Arquivos

Query Parameters

Response (200 OK)

Obter Arquivo

Obter URL de Upload

Response (200 OK)

Obter URL de Download

Response (200 OK)

Excluir Arquivo

Response (204 No Content)

Exemplo Completo de Upload

Erros Comuns