Envie arquivos você mesmo

Pelo painel

Arquivos e depois Enviar um arquivo. O que você escolher cai na pasta que está aberta e você recebe o link. Bytes idênticos são guardados uma vez só, então reenviar o mesmo arquivo não custa nada.

Crie um token

Tokens e depois Novo token. Amarre ele a um servidor em vez do workspace inteiro, para que uma chave vazada não escreva em todo lugar. O segredo aparece uma vez só.

O token de API começa com fd_live_. Ele não é a chave de agente fda_live_ que vai no server.cfg: essa só conecta o resource fivedock, e a API de upload não a aceita.

files:write envia, files:read lê de volta, files:delete apaga, folders:write cria pastas, usage:read lê armazenamento e tráfego. logs:write é para mandar erros de um aplicativo, não para arquivos.

Enviar por HTTP

Envie o arquivo como multipart/form-data para POST /api/v3/file, o mesmo endereço que o Fivemanage usa. path é a pasta, criada na hora, e filename substitui o nome do arquivo vindo da parte.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=/branding"

{
  "status": "ok",
  "data": { "id": "8Kq2nR4t", "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png" },
  "url": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
  "filename": "logo.png",
  "mime_type": "image/png",
  "size": 48213,
  "fivedock": {
    "fileUrl": "https://cdn.fivedock.dev/f/8Kq2nR4t.png",
    "deduplicated": false,
    "folder": "/branding"
  }
}

url é o link da CDN, pronto para colar numa tela de carregamento ou num embed do Discord, e funciona assim que a resposta chega. fivedock.deduplicated diz que aqueles bytes já estavam guardados, então nada novo foi cobrado. A resposta acima está resumida.

Arquivos com nome e links fixos

Dê uma chave a um arquivo, como items/burger.png, e ele fica num link que nunca muda: https://cdn.fivedock.dev/o/my-city/items/burger.png, onde my-city é o nome curto do seu workspace. Envie de novo com a mesma chave e o arquivo por trás do link é trocado, então um ícone de inventário ou uma imagem de tela de carregamento muda sem mexer em script nem em banco de dados.

curl -X POST https://api.fivedock.dev/api/v3/file \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "key=items/burger.png"

# served at https://cdn.fivedock.dev/o/my-city/items/burger.png
# run it again with a new burger.png and the same link shows the new file

As chaves vêm do campo key da API de upload, de “Manter nomes dos arquivos” no painel, de arquivos compactados e do endpoint S3, onde um objeto em s3://my-city/items/burger.png é o arquivo com chave items/burger.png. No painel, um arquivo com chave aparece na pasta da chave dele, aqui /items.

O arquivo substituído é guardado por 7 dias e depois apagado de vez. Links com chave ficam em cache por 5 minutos, então os jogadores veem a versão nova em uns 5 minutos. Todo arquivo também mantém o próprio link /f/, cujo conteúdo nunca muda.

Chaves feitas a partir de nomes de arquivo são limpas para você: espaços viram - e qualquer outro caractere que uma chave não aceita vira _. Uma chave que você mesmo manda para a API já precisa seguir as regras, ou é recusada.

Envie uma pasta inteira como .zip ou .rar

Solte um .zip ou .rar na área de upload do painel, ou envie para POST /api/v3/file/archive, e cada arquivo dentro dele é guardado. “Manter nomes dos arquivos” vem ligado por padrão para arquivos compactados, então burger.png extraído em items ganha o link fixo …/o/my-city/items/burger.png. As pastas do compactado são mantidas.

curl -X POST https://api.fivedock.dev/api/v3/file/archive \
  -H "Authorization: Bearer fd_live_…" \
  -F "[email protected]" \
  -F "path=items"

Um arquivo compactado pode ter até 512 MiB, com no máximo 5.000 arquivos e 4 GiB descompactado. Arquivos que não conseguimos guardar, como os de um tipo que não aceitamos ou os protegidos por senha, voltam numa lista com o motivo. Para conjuntos maiores, sincronize pelo endpoint S3.

Do seu próprio uploader em HTML e JS

Nunca coloque um token no JavaScript do navegador: quem abrir a página lê ele e envia para o seu workspace. Receba o arquivo no seu próprio servidor e guarde o token lá.

// your server, never the browser: the token stays here
app.post('/upload', upload.single('file'), async (req, res) => {
  const body = new FormData();
  body.append('file', new Blob([req.file.buffer]), req.file.originalname);
  body.append('path', '/player-shots');

  const answer = await fetch('https://api.fivedock.dev/api/v3/file', {
    method: 'POST',
    headers: { Authorization: `Bearer ${process.env.FIVEDOCK_TOKEN}` },
    body,
  });
  res.json(await answer.json());
});

// your page talks to your server, which holds the token
const body = new FormData();
body.append('file', input.files[0]);

const answer = await fetch('/upload', { method: 'POST', body });
const file = await answer.json();
image.src = file.url;

Se o arquivo nasce num navegador ou numa página NUI do FiveM, seu servidor pode criar um link de upload de uso único e repassar esse link. O navegador envia direto para o FiveDock e nunca vê o token.

Se o que você quer é que jogadores mandem arquivos sem você escrever código, use um portal de envio: é uma página pública, com limite por endereço, teto diário e moderação na frente.

O endpoint compatível com S3

O mesmo token também é uma credencial S3, então rclone, a CLI da aws e a maioria das ferramentas de backup conseguem escrever nele. Use endereçamento path-style.

rclone config create fivedock s3 \
  provider=Other \
  endpoint=https://s3.fivedock.dev \
  access_key_id=AKFD… \
  secret_access_key=… \
  force_path_style=true \
  region=auto

rclone copy ./branding fivedock:my-city/branding

aws --endpoint-url https://s3.fivedock.dev \
  s3 cp logo.png s3://my-city/branding/logo.png

Todo objeto que você envia é um arquivo com chave, então s3://my-city/branding/logo.png fica em https://cdn.fivedock.dev/o/my-city/branding/logo.png.

Pastas e retenção

Crie pastas no painel e mova arquivos entre elas. A chave de um arquivo vai junto com ele: items/a.png movido para /icons vira icons/a.png, e se essa chave já estiver em uso, a mudança é recusada para esse arquivo. A lista de arquivos tem visão em lista e em grade, busca por nome e filtros por tipo e por quando o arquivo foi adicionado: últimas 24 horas, 7 dias, 30 dias ou todo o período.

Cada pasta tem uma regra de retenção que decide quando os arquivos dela são apagados.

Servindo o que você enviou

Todo arquivo ganha um link de CDN que funciona assim que o upload responde. Os arquivos são aprovados no upload; se a moderação derrubar algum depois, o link dele responde 404. Em Configurações a lista de permissões limita quais sites podem incorporar seus arquivos.