Enriquecimento

O upload para enriquecimento é usado para enviar bases de CPF ou CNPJ que serão analisadas e enriquecidas pelos datasets selecionados. Após o upload, a Lazy Data valida o arquivo, identifica a estrutura da planilha, detecta a coluna de documento e prepara o enriquecimento para configuração.

Endpoint técnico

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

Endpoint

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

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

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 enriquecimento.

Como obter a assinatura

A assinatura é gerada no fluxo de criação ou preparação do enriquecimento. Antes do upload, a aplicação cria o enriquecimento informando tipo da base, nome e metadados do arquivo. A resposta retorna:

Campo	Descrição
`upload_url`	URL do serviço de upload. Para enriquecimento, usa `https://upload.lazydata.com.br/enrichment`.
`signature`	Assinatura temporária usada no header `X-LazyData-Upload-Signature`.
`signature_expires_at`	Data de expiração da assinatura.
`id`	Identificador do enriquecimento criado.

Criar enriquecimento

Crie o registro inicial e gere a assinatura temporária para enviar o arquivo.

A assinatura deve ser usada apenas para o upload atual. Se expirar ou o envio falhar, gere uma nova assinatura antes de tentar novamente.

Formatos aceitos

O upload de enriquecimento aceita arquivos de base nos formatos:

Extensão	Uso
`csv`	Recomendado para bases grandes e integrações automatizadas.
`xls`	Planilhas legadas do Excel.
`xlsx`	Planilhas modernas do Excel.

O arquivo deve conter ao menos uma coluna com CPF ou CNPJ, conforme o tipo do enriquecimento.

Limite por arquivo

Cada arquivo pode ter até 1024 MB.

Limite por arquivo: 1024 MB

Arquivos acima desse limite são recusados antes da análise.

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/enrichment" \
  --header "X-LazyData-Upload-Signature: <assinatura_de_upload>" \
  --form "file=@./base-clientes.csv"

Exemplo com JavaScript:

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

const response = await fetch("https://upload.lazydata.com.br/enrichment", {
  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.

Validações realizadas

Durante o upload, a Lazy Data valida:

assinatura temporária;
validade da assinatura;
enriquecimento relacionado;
se o arquivo já foi enviado;
se o enriquecimento ainda aceita upload;
nome e extensão do arquivo;
tamanho do arquivo;
tipo de conteúdo;
integridade inicial;
estrutura mínima da planilha.

O arquivo enviado precisa manter o mesmo nome e extensão usados para gerar a assinatura. Se forem diferentes, o upload pode ser recusado.

Análise do arquivo

Após o upload, a Lazy Data inicia a validação e análise do arquivo. A análise pode identificar:

total de linhas;
presença de cabeçalho;
delimitador, no caso de CSV;
colunas disponíveis;
possível coluna de CPF ou CNPJ;
amostra das primeiras linhas;
formato de dados das colunas;
documentos inválidos ou ausentes.

Essa etapa continua em segundo plano após a resposta inicial do upload.

Resposta de upload recebido

Quando o arquivo é aceito, a resposta indica que a validação e análise foram iniciadas.

{
  "code": 202,
  "message": "Arquivo recebido. O processamento foi iniciado.",
  "result": {
    "id": "8a1f7229-7cf0-48f8-912f-97ff6a4b1111",
    "type": "pf",
    "name": "Base de clientes",
    "status": "validating_file",
    "status_label": "Validando arquivo"
  }
}

O retorno 202 não significa que o enriquecimento já pode ser executado. Aguarde o status waiting_configuration antes de selecionar coluna e datasets.

Status após upload

O enriquecimento pode passar por estados como:

Status	Descrição
`receiving_upload`	Arquivo sendo recebido pelo serviço de upload.
`validating_file`	Arquivo recebido e validação inicial em andamento.
`analyzing_file`	Arquivo validado e amostra em análise.
`uploading_storage`	Arquivo validado e sendo salvo no storage.
`waiting_configuration`	Arquivo pronto para configurar coluna e datasets.
`failed`	Arquivo recusado ou análise falhou.

Arquivo sem cabeçalho

Quando a Lazy Data não identifica cabeçalho válido, as colunas podem ser exibidas por índice ou com nomes genéricos. Exemplo:

Coluna 1
Coluna 2
Coluna 3

Nesse caso, use a amostra retornada em analysis.columns[] para selecionar manualmente a coluna de CPF ou CNPJ.

Coluna de documento

A coluna de documento é usada como chave do enriquecimento.

Tipo de enriquecimento	Documento esperado
`pf`	CPF
`pj`	CNPJ

Se a coluna selecionada possuir documentos inválidos, esses registros serão contabilizados como invalid_documents durante o processamento.

Arquivos de entrada e saída

Veja regras de estrutura, cabeçalho, coluna de documento e arquivos gerados.

Próxima etapa

Depois que o enriquecimento chegar em waiting_configuration, selecione:

coluna do documento;
datasets disponíveis para o tipo da base;
campos adicionais exigidos pelos datasets, quando houver.

Em seguida, inicie o processamento.

Configurar e executar

Envie document_column, datasets e additional para colocar o enriquecimento na fila.

Falhas comuns

Possíveis falhas no upload de enriquecimento:

assinatura ausente, inválida ou expirada;
enriquecimento não encontrado;
arquivo já enviado;
enriquecimento em status incompatível com upload;
arquivo acima de 1024 MB;
formato não permitido;
tipo de conteúdo incompatível;
arquivo vazio ou inválido;
falha ao ler a planilha;
nome ou extensão diferente do arquivo assinado.

Códigos de erro de upload

Veja os erros possíveis durante assinatura, envio, validação e análise do arquivo.

Boas práticas

Use arquivos CSV para bases muito grandes.
Use cabeçalhos claros.
Evite colunas duplicadas.
Remova linhas vazias antes do upload.
Não misture CPF e CNPJ no mesmo arquivo.
Envie o arquivo com o mesmo nome usado na preparação.
Revise a coluna detectada antes de iniciar o enriquecimento.
Solicite uma nova assinatura caso o upload expire ou falhe.

Próximos passos

Criar enriquecimento

Veja o fluxo completo para criar, enviar e configurar um enriquecimento.

Endpoint de upload

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

Consultar status

Acompanhe validação, análise e progresso do enriquecimento.

Datasets disponíveis

Liste datasets PF ou PJ habilitados para enriquecimento.

Primeiros passos

Utilidades

Funcionalidades

Webhook

Endpoint técnico

Endpoint

Header obrigatório

Como obter a assinatura

Criar enriquecimento

Formatos aceitos

Limite por arquivo

Envio do arquivo

Validações realizadas

Análise do arquivo

Resposta de upload recebido

Status após upload

Arquivo sem cabeçalho

Coluna de documento

Arquivos de entrada e saída

Próxima etapa

Configurar e executar

Falhas comuns

Códigos de erro de upload

Boas práticas

Próximos passos

Criar enriquecimento

Endpoint de upload

Consultar status

Datasets disponíveis

Endpoint técnico

​Endpoint

​Header obrigatório

​Como obter a assinatura

Criar enriquecimento

​Formatos aceitos

​Limite por arquivo

​Envio do arquivo

​Validações realizadas

​Análise do arquivo

​Resposta de upload recebido

​Status após upload

​Arquivo sem cabeçalho

​Coluna de documento

Arquivos de entrada e saída

​Próxima etapa

Configurar e executar

​Falhas comuns

Códigos de erro de upload

​Boas práticas

​Próximos passos

Criar enriquecimento

Endpoint de upload

Consultar status

Datasets disponíveis

Endpoint

Header obrigatório

Como obter a assinatura

Formatos aceitos

Limite por arquivo

Envio do arquivo

Validações realizadas

Análise do arquivo

Resposta de upload recebido

Status após upload

Arquivo sem cabeçalho

Coluna de documento

Próxima etapa

Falhas comuns

Boas práticas

Próximos passos