Skip to main content
O upload de arquivos na Lazy Data usa um fluxo com assinatura temporária para garantir que cada envio seja autorizado antes de o arquivo ser recebido e processado. Esse fluxo é usado em recursos que precisam receber arquivos maiores ou arquivos que serão processados em segundo plano, como bases de enriquecimento e arquivos enviados ao armazenamento da conta.
O arquivo binário não é enviado para a URL base da API principal. Uploads usam o serviço dedicado https://upload.lazydata.com.br.

​
Onde o upload é usado

Atualmente, o upload de arquivos é usado em dois fluxos principais:

Enriquecimento

Envio de bases CSV, XLS ou XLSX para enriquecimento de CPF ou CNPJ.

Armazenamento

Envio de arquivos para o espaço de armazenamento da conta.

​
Como funciona

O fluxo geral é dividido em etapas para separar autorização, envio do arquivo e processamento final.
1

Prepare o upload

A aplicação chama a API principal para criar ou preparar o recurso que receberá o arquivo.
2

Receba a assinatura

A resposta retorna uma assinatura temporária, a URL de upload e a data de expiração.
3

Envie o arquivo

O arquivo é enviado em multipart/form-data para o domínio de upload usando a assinatura no header.
4

Acompanhe o processamento

A Lazy Data valida, processa e registra o arquivo conforme o recurso de destino.

​
Domínios de upload

Cada destino possui uma rota específica no serviço de upload.
Não envie arquivos para endpoints comuns da API principal. Use sempre o upload_url retornado na etapa de preparação.

​
Assinatura temporária

Antes de enviar um arquivo, é necessário obter uma assinatura de upload. A assinatura define:
  • conta responsável pelo envio;
  • recurso de destino;
  • validade da autorização;
  • operação permitida;
  • identificador relacionado ao upload;
  • nome esperado do arquivo;
  • contexto necessário para validação.
A assinatura deve ser usada somente para o upload solicitado.

​
Header de assinatura

A assinatura deve ser enviada no header:
O serviço de upload não usa Authorization: Bearer. A autenticação do envio é feita pela assinatura temporária.

​
Envio do arquivo

O arquivo deve ser enviado em multipart/form-data. O nome do campo do arquivo deve ser exatamente file.
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

O limite atual por arquivo é de até 1024 MB, quando o destino permitir.
Arquivos acima desse limite são recusados antes do processamento.
O recurso de destino pode aplicar regras adicionais. Enriquecimento aceita apenas arquivos compatíveis com processamento de bases, enquanto armazenamento aceita mais tipos de arquivo conforme cota e política da conta.

​
Validações realizadas

Durante o upload, a Lazy Data pode validar:
  • assinatura enviada;
  • validade da assinatura;
  • permissão da conta;
  • recurso de destino;
  • nome do arquivo;
  • tamanho do arquivo;
  • formato permitido;
  • tipo de conteúdo;
  • integridade do arquivo;
  • duplicidade;
  • disponibilidade para processamento.
As validações específicas dependem do tipo de upload.

​
Processamento em segundo plano

Alguns uploads exigem processamento posterior. Exemplos:
  • análise de colunas em arquivos de enriquecimento;
  • cálculo de linhas processáveis;
  • identificação de CPF ou CNPJ;
  • armazenamento definitivo do arquivo;
  • registro de metadados;
  • atualização do status do recurso;
  • geração de arquivos finais.
Nesses casos, a resposta inicial indica que o arquivo foi recebido, mas etapas dependentes devem aguardar o status correto do recurso.

​
Resposta padrão

Quando o arquivo é aceito, a resposta segue o contrato base da Lazy Data.
Em enriquecimentos, a resposta pode usar 202 quando o arquivo é recebido e a análise continua em segundo plano.

​
Quando não usar upload

Nem todo endpoint que recebe dados usa o fluxo de upload.

​
Falhas comuns

Possíveis causas de falha no upload:
  • assinatura ausente;
  • assinatura inválida;
  • assinatura expirada;
  • arquivo acima do limite;
  • nome do arquivo diferente do nome assinado;
  • formato não permitido;
  • tipo de conteúdo incompatível;
  • recurso de destino não encontrado;
  • arquivo já enviado;
  • espaço insuficiente no armazenamento;
  • falha ao salvar no storage;
  • interrupção de conexão.

Códigos de erro de upload

Veja os erros possíveis durante assinatura, envio, validação e armazenamento de arquivos.

​
Boas práticas

  • Solicite uma nova assinatura antes de cada upload.
  • Não reutilize assinaturas expiradas, inválidas ou já usadas.
  • Não envie arquivos acima de 1024 MB.
  • Mantenha a página aberta durante uploads grandes.
  • Use conexão estável para arquivos grandes.
  • Envie o arquivo com o mesmo nome usado na preparação.
  • Aguarde o status final antes de iniciar etapas dependentes do arquivo.
  • Não exponha assinaturas de upload em logs públicos.

​
Próximos passos

Upload para enriquecimento

Veja o fluxo de envio de bases para enriquecimento.

Upload para armazenamento

Veja o fluxo de envio de arquivos para o armazenamento.

Endpoint de enriquecimento

Consulte a rota técnica de upload para bases de enriquecimento.

Endpoint de armazenamento

Consulte a rota técnica de upload para arquivos do storage.