File Forge

Documentação da API

Guia completo para integrar e utilizar o serviço de upload de arquivos do File Forge.

Upload de Arquivo

Envia um arquivo para um projeto específico. Se o projeto não existir, ele será criado automaticamente.

POST
https://uploader.nativespeak.app/upload

Parâmetros

ParâmetroTipoObrigatórioDescrição
projectStringNãoNome do projeto. Se não informado, usa "default".
fileFileSimO arquivo a ser enviado.

Resposta de Sucesso (200 OK)

{
  "message": "Arquivo enviado com sucesso",
  "url": "https://uploader.nativespeak.app/files/meu-projeto/arquivo-20240101-120000.jpg",
  "project": "meu-projeto",
  "file": "arquivo-20240101-120000.jpg"
}

Exemplos de Código

curl -X POST "https://uploader.nativespeak.app/upload" \
 -H "Content-Type: multipart/form-data" \
 -F "project=meu-projeto-incrivel" \
 -F "file=@/caminho/para/seu/arquivo.jpg"

Listar Projetos

Retorna a lista de todos os projetos disponíveis com informações sobre quantidade de arquivos e tamanho total.

GET
https://uploader.nativespeak.app/projects

Resposta de Sucesso (200 OK)

{
  "projects": [
    {
      "name": "meu-projeto",
      "file_count": 15,
      "total_size": 2048576
    },
    {
      "name": "outro-projeto",
      "file_count": 8,
      "total_size": 1024000
    }
  ],
  "total": 2
}

Exemplos de Código

curl "https://uploader.nativespeak.app/projects"

Listar Arquivos de um Projeto

Lista todos os arquivos de um projeto específico com informações detalhadas.

GET
https://uploader.nativespeak.app/list?project={nome}

Parâmetros

ParâmetroTipoObrigatórioDescrição
projectStringSimNome do projeto a ser consultado.

Resposta de Sucesso (200 OK)

{
  "project": "meu-projeto",
  "files": [
    {
      "name": "imagem-20240101-120000.jpg",
      "url": "https://uploader.nativespeak.app/files/meu-projeto/imagem-20240101-120000.jpg",
      "size": 204800,
      "uploaded_at": "2024-01-01 12:00:00"
    },
    {
      "name": "documento-20240101-120100.pdf",
      "url": "https://uploader.nativespeak.app/files/meu-projeto/documento-20240101-120100.pdf",
      "size": 512000,
      "uploaded_at": "2024-01-01 12:01:00"
    }
  ],
  "total": 2
}

Exemplos de Código

curl "https://uploader.nativespeak.app/list?project=meu-projeto"

Deletar Arquivo

Remove um arquivo específico de um projeto.

DELETE
https://uploader.nativespeak.app/delete?project={nome}&file={arquivo}

Parâmetros

ParâmetroTipoObrigatórioDescrição
projectStringSimNome do projeto que contém o arquivo.
fileStringSimNome do arquivo a ser deletado.

Resposta de Sucesso (200 OK)

{
  "message": "Arquivo deletado com sucesso",
  "project": "meu-projeto",
  "file": "arquivo-20240101-120000.jpg"
}

Exemplos de Código

curl -X DELETE "https://uploader.nativespeak.app/delete?project=meu-projeto&file=arquivo-20240101-120000.jpg"

Acessar/Baixar Arquivo

Acessa ou baixa um arquivo específico através de sua URL pública.

GET
https://uploader.nativespeak.app/files/{projeto}/{arquivo}

Exemplo de Uso

Você pode usar a URL diretamente em elementos HTML como imagens, vídeos ou links de download:

<!-- Exibir imagem -->
<img src="https://uploader.nativespeak.app/files/meu-projeto/imagem-20240101-120000.jpg" alt="Imagem" />

<!-- Link para download -->
<a href="https://uploader.nativespeak.app/files/meu-projeto/documento-20240101-120000.pdf" download>
  Baixar Documento
</a>

<!-- Vídeo -->
<video src="https://uploader.nativespeak.app/files/meu-projeto/video-20240101-120000.mp4" controls></video>

Download via cURL

curl "https://uploader.nativespeak.app/files/meu-projeto/arquivo-20240101-120000.jpg" -o arquivo-local.jpg

Respostas de Erro

A API retorna códigos de status HTTP apropriados e mensagens de erro em formato JSON.

400 Bad Request

Requisição inválida ou parâmetros faltando.

{
  "error": "Parâmetros 'project' e 'file' são obrigatórios"
}

404 Not Found

Recurso não encontrado (projeto ou arquivo inexistente).

{
  "error": "Projeto não encontrado"
}

500 Internal Server Error

Erro interno do servidor.

{
  "error": "Erro ao salvar o arquivo"
}

Casos de Uso

1. Galeria de Imagens por Projeto

// Criar galeria dinâmica
const createGallery = async (projectName) => {
  const response = await fetch(`https://uploader.nativespeak.app/list?project=${projectName}`);
  const data = await response.json();
  
  const gallery = document.getElementById('gallery');
  gallery.innerHTML = ''; // Limpar galeria
  
  data.files.forEach(file => {
    if (file.name.match(/\.(jpg|jpeg|png|gif|webp)$/i)) {
      const img = document.createElement('img');
      img.src = file.url;
      img.alt = file.name;
      img.className = 'w-64 h-64 object-cover rounded-lg shadow-lg';
      gallery.appendChild(img);
    }
  });
};

// Usar
createGallery('portfolio');

2. Upload com Múltiplos Arquivos

const uploadMultipleFiles = async (files, projectName) => {
  const uploadPromises = Array.from(files).map(file => {
    const formData = new FormData();
    formData.append('file', file);
    formData.append('project', projectName);
    
    return fetch('https://uploader.nativespeak.app/upload', {
      method: 'POST',
      body: formData
    }).then(res => res.json());
  });
  
  try {
    const results = await Promise.all(uploadPromises);
    console.log('Todos os arquivos foram enviados:', results);
    return results;
  } catch (error) {
    console.error('Erro no upload:', error);
    throw error;
  }
};

// Usar com input file
const fileInput = document.getElementById('fileInput');
fileInput.addEventListener('change', (e) => {
  uploadMultipleFiles(e.target.files, 'meu-projeto');
});

3. Dashboard de Estatísticas

const getDashboardStats = async () => {
  const response = await fetch('https://uploader.nativespeak.app/projects');
  const data = await response.json();
  
  const stats = {
    totalProjects: data.total,
    totalFiles: data.projects.reduce((sum, p) => sum + p.file_count, 0),
    totalSize: data.projects.reduce((sum, p) => sum + p.total_size, 0),
    projects: data.projects.map(p => ({
      name: p.name,
      files: p.file_count,
      size: (p.total_size / 1024 / 1024).toFixed(2) + ' MB'
    }))
  };
  
  console.log('Estatísticas:', stats);
  return stats;
};

Melhores Práticas

📁 Organização por Projetos

Use nomes de projeto significativos que reflitam a estrutura do seu aplicativo. Exemplo: "user-avatars", "product-images", "documents-2024".

🔒 Segurança

Nomes de projetos são automaticamente sanitizados para segurança. Caracteres especiais como "..", "/", "\" são removidos ou substituídos.

⏰ Timestamps Automáticos

Todos os arquivos recebem timestamps automáticos (formato: YYYYMMDD-HHMMSS) para evitar conflitos de nomes e facilitar a ordenação cronológica.

🚀 Performance

Para uploads de múltiplos arquivos, use Promise.all() para enviar em paralelo e melhorar a performance.

📊 Monitoramento

Use o endpoint /projects regularmente para monitorar o uso de espaço e quantidade de arquivos por projeto.