Armazenamento

O upload para armazenamento é usado para enviar arquivos ao espaço de arquivos da conta Lazy Data. Após o upload, o arquivo fica disponível na pasta selecionada e pode ser baixado, renomeado ou excluído pelo painel ou pela API.

Endpoint técnico

Consulte parâmetros, exemplos e respostas da rota de upload para armazenamento.

Endpoint

POST https://upload.lazydata.com.br/storage

Este endpoint não usa a URL base da API principal. O arquivo deve ser enviado para https://upload.lazydata.com.br/storage.

Header obrigatório

A requisição deve enviar a assinatura temporária de upload no header:

X-LazyData-Upload-Signature: <assinatura_de_upload>

O upload não usa Authorization: Bearer. A autenticação do envio é feita pela assinatura retornada na preparação do upload.

Como obter a assinatura

A assinatura é gerada antes do upload pela API principal ou pelo painel. Pela API, a preparação do upload usa:

POST /v1/storage/uploads

Essa etapa cria o registro inicial do arquivo com status waiting_upload e retorna:

Campo	Descrição
`upload_url`	URL do serviço de upload. Para armazenamento, usa `https://upload.lazydata.com.br/storage`.
`signature`	Assinatura temporária usada no header `X-LazyData-Upload-Signature`.
`signature_expires_at`	Data de expiração da assinatura.
`max_size`	Tamanho máximo aceito para o arquivo.
`file`	Metadados iniciais do arquivo preparado.

Preparar upload

Gere a assinatura temporária e o registro inicial do arquivo.

A assinatura deve ser usada somente para o arquivo preparado. Se expirar ou o upload falhar, gere uma nova assinatura.

Pasta de destino

O arquivo é salvo na pasta definida na preparação do upload. Use parent_id para indicar a pasta de destino:

{
  "name": "relatorio.pdf",
  "parent_id": "1e6c59aa-1b8e-4cf8-becb-49b2c1111111"
}

Quando parent_id for null, o arquivo será enviado para a raiz do armazenamento. Se a pasta de destino não existir, estiver indisponível ou não pertencer à conta autorizada, o upload é recusado.

Envio do arquivo

O arquivo deve ser enviado em multipart/form-data. O nome do campo do arquivo deve ser exatamente file.

curl --request POST \
  --url "https://upload.lazydata.com.br/storage" \
  --header "X-LazyData-Upload-Signature: <assinatura_de_upload>" \
  --form "file=@./relatorio.pdf"

Exemplo com JavaScript:

const formData = new FormData();
formData.append("file", file, file.name);

const response = await fetch("https://upload.lazydata.com.br/storage", {
  method: "POST",
  headers: {
    "X-LazyData-Upload-Signature": uploadSignature
  },
  body: formData
});

const data = await response.json();

Ao usar FormData no navegador, não defina manualmente o header Content-Type. O navegador adiciona o boundary correto do multipart/form-data.

Limite por arquivo

Cada arquivo pode ter até 1024 MB.

Limite por arquivo: 1024 MB

Arquivos acima desse limite são recusados. Também é necessário que a conta tenha espaço disponível suficiente para armazenar o arquivo.

Permissões e limites

Consulte limite por arquivo, cota da conta, subcontas e regras de acesso.

Tipos de arquivo

O armazenamento aceita diferentes tipos de arquivo, desde que respeitem o limite de tamanho, a cota da conta e as regras de segurança. O tipo MIME é normalizado a partir do arquivo enviado. Quando o navegador envia application/octet-stream, a API pode inferir o tipo com base no nome do arquivo. Exemplos comuns:

Tipo	Extensões comuns
Imagem	`.jpg`, `.jpeg`, `.png`, `.webp`
PDF	`.pdf`
Planilha	`.csv`, `.xls`, `.xlsx`
Documento	`.doc`, `.docx`, `.txt`
Compactado	`.zip`, `.rar`, `.7z`
Genérico	Outros formatos permitidos

Validações realizadas

Durante o upload, a Lazy Data valida:

assinatura temporária;
validade da assinatura;
conta responsável;
pasta de destino;
limite de armazenamento da conta;
tamanho do arquivo;
nome do arquivo;
tipo de conteúdo;
integridade inicial;
duplicidade na pasta;
status do registro preparado.

O arquivo enviado precisa manter o mesmo nome usado para gerar a assinatura. Se o nome for diferente, o upload pode ser recusado.

Registro do arquivo

Após o upload, a Lazy Data registra os metadados finais do arquivo. Exemplo de metadados:

{
  "id": "8c30d4a1-b1ac-4d18-a8f9-b4cb77771111",
  "type": "file",
  "name": "relatorio.pdf",
  "parent_id": "1e6c59aa-1b8e-4cf8-becb-49b2c1111111",
  "extension": "pdf",
  "content_type": "application/pdf",
  "size": 187392,
  "status": "uploaded",
  "uploaded_at": "2026-06-21T12:00:00+00:00"
}

Resposta de upload concluído

Quando o arquivo é salvo com sucesso, a API retorna:

{
  "code": 200,
  "message": "Arquivo enviado.",
  "result": {
    "id": "8c30d4a1-b1ac-4d18-a8f9-b4cb77771111",
    "type": "file",
    "name": "relatorio.pdf",
    "parent_id": "1e6c59aa-1b8e-4cf8-becb-49b2c1111111",
    "extension": "pdf",
    "content_type": "application/pdf",
    "size": 187392,
    "status": "uploaded"
  }
}

Status de upload

Status	Descrição
`waiting_upload`	Registro criado e aguardando envio do arquivo.
`receiving_upload`	Upload em andamento.
`uploaded`	Arquivo recebido e salvo com sucesso.
`failed`	Upload falhou ou foi recusado.

Disponibilidade no painel

Após o upload, o arquivo aparece na pasta de destino com status uploaded. No painel, é possível:

baixar o arquivo;
renomear o arquivo;
excluir o arquivo;
organizar arquivos em pastas;
visualizar metadados básicos.

Pastas e arquivos

Veja como navegar, organizar, renomear e excluir itens no armazenamento.

Download

Arquivos enviados ao armazenamento podem ser baixados por link temporário.

GET /v1/storage/files/{file_id}/download

Gerar download

Gere um link temporário para baixar um arquivo armazenado.

Falhas comuns

Possíveis falhas no upload para armazenamento:

assinatura ausente, inválida ou expirada;
pasta de destino não encontrada;
arquivo acima de 1024 MB;
limite de armazenamento excedido;
espaço disponível insuficiente;
nome de arquivo duplicado na pasta;
nome do arquivo diferente do nome assinado;
arquivo vazio ou inválido;
upload já enviado para o registro preparado;
falha ao receber ou salvar o arquivo;
conexão interrompida.

Códigos de erro de upload

Veja os erros possíveis durante assinatura, envio e armazenamento do arquivo.

Boas práticas

Envie arquivos para a pasta correta.
Use nomes claros e objetivos.
Verifique summary.available_bytes antes de arquivos grandes.
Evite enviar arquivos duplicados na mesma pasta.
Aguarde o upload finalizar antes de atualizar a página.
Gere uma nova assinatura quando o upload falhar ou expirar.
Não exponha assinaturas de upload em logs públicos.
Renomeie arquivos quando necessário para facilitar a organização.

Próximos passos

Entenda como organizar pastas, arquivos e limites de armazenamento.

Upload e download

Veja o fluxo completo de envio e download de arquivos.

Endpoint de upload

Consulte a documentação técnica da rota de upload.

Preparar upload

Gere assinatura temporária para envio.

Primeiros passos

Utilidades

Funcionalidades

Webhook

Armazenamento

Endpoint técnico

Endpoint

Header obrigatório

Como obter a assinatura

Preparar upload

Pasta de destino

Envio do arquivo

Limite por arquivo

Permissões e limites

Tipos de arquivo

Validações realizadas

Registro do arquivo

Resposta de upload concluído

Status de upload

Disponibilidade no painel

Pastas e arquivos

Download

Gerar download

Falhas comuns

Códigos de erro de upload

Boas práticas

Próximos passos

Armazenamento

Upload e download

Endpoint de upload

Preparar upload

Endpoint técnico

​Endpoint

​Header obrigatório

​Como obter a assinatura

Preparar upload

​Pasta de destino

​Envio do arquivo

​Limite por arquivo

Permissões e limites

​Tipos de arquivo

​Validações realizadas

​Registro do arquivo

​Resposta de upload concluído

​Status de upload

​Disponibilidade no painel

Pastas e arquivos

​Download

Gerar download

​Falhas comuns

Códigos de erro de upload

​Boas práticas

​Próximos passos

Armazenamento

Upload e download

Endpoint de upload

Preparar upload

Endpoint

Header obrigatório

Como obter a assinatura

Pasta de destino

Envio do arquivo

Limite por arquivo

Tipos de arquivo

Validações realizadas

Registro do arquivo

Resposta de upload concluído

Status de upload

Disponibilidade no painel

Download

Falhas comuns

Boas práticas

Próximos passos