Criar enriquecimento

A criação de um enriquecimento é feita em etapas para reduzir erros de configuração e garantir que a base enviada esteja pronta para processamento. O fluxo começa com a escolha do tipo da base, passa pelo upload e análise do arquivo, seleção dos datasets e finaliza com o processamento em segundo plano.

Criar enriquecimento pela API

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

Fluxo completo

Crie o enriquecimento

Informe tipo da base (pf ou pj), nome do enriquecimento e metadados do arquivo.

Envie o arquivo

Use upload_url e signature para enviar o arquivo em https://upload.lazydata.com.br/enrichment.

Aguarde a análise

A plataforma identifica colunas, amostras, quantidade de linhas e possível coluna de CPF ou CNPJ.

Selecione datasets

Liste datasets disponíveis para o tipo da base e escolha os IDs que serão usados no processamento.

Configure e execute

Envie a coluna do documento, datasets e campos adicionais para colocar o enriquecimento na fila.

Acompanhe e baixe saídas

Consulte progresso, custos, status final e gere links temporários para os arquivos de saída.

Etapa 1: Tipo de enriquecimento

Escolha o tipo da base antes de enviar o arquivo.

Tipo	Quando usar
`pf`	Arquivo com CPFs.
`pj`	Arquivo com CNPJs.

Essa escolha define como a Lazy Data valida os documentos e quais datasets ficam disponíveis na etapa de configuração.

Etapa 2: Nome e arquivo

Informe um nome para identificar o enriquecimento e os metadados do arquivo.

{
  "type": "pf",
  "name": "Base de clientes",
  "file": {
    "name": "base-clientes.csv",
    "extension": "csv"
  }
}

Formatos aceitos:

csv
xls
xlsx

O arquivo precisa conter ao menos uma coluna com CPF ou CNPJ, conforme o tipo escolhido.

Etapa 3: Assinatura e upload

A criação retorna upload_url, signature e signature_expires_at. O arquivo não é enviado para a URL base da API principal. O envio é feito no serviço de upload:

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

curl --request POST \
  --url "https://upload.lazydata.com.br/enrichment" \
  --header "X-LazyData-Upload-Signature: <assinatura_de_upload>" \
  --form "file=@./base-clientes.csv"

A assinatura é temporária. Se expirar antes do envio, gere uma nova assinatura usando o mesmo enrichment_id.

Etapa 4: Análise do arquivo

Após o upload, o arquivo passa por validação e análise. A análise identifica:

formato e tipo do arquivo;
tamanho;
quantidade de linhas;
presença de cabeçalho;
delimitador, quando aplicável;
colunas disponíveis;
possível coluna de CPF ou CNPJ;
amostras das primeiras linhas.

Consulte o status até o enriquecimento chegar em waiting_configuration.

{
  "status": "waiting_configuration",
  "analysis": {
    "document_column": 0,
    "document_column_name": "cpf",
    "columns": [
      {
        "index": 0,
        "name": "cpf",
        "sample": "00000000000"
      }
    ]
  }
}

Etapa 5: Revisão da coluna do documento

Revise a coluna identificada como CPF ou CNPJ antes de iniciar o processamento. Se a coluna detectada automaticamente não for a correta, envie manualmente o índice correto em document_column. Quando o arquivo não possui cabeçalho, as colunas podem aparecer com nomes genéricos. Use analysis.columns[] e amostras para escolher a coluna certa.

Etapa 6: Seleção dos datasets

Liste os datasets habilitados para enriquecimento usando o tipo da base.

Datasets disponíveis

Liste datasets PF ou PJ disponíveis para processamento em massa.

Nenhum dataset deve ser assumido como padrão. Escolha explicitamente os IDs retornados nessa rota. A estimativa de custo considera:

quantidade de linhas válidas;
datasets selecionados;
preço de cada dataset;
descontos aplicáveis ao plano;
regras de estorno, como debit_only_if_found.

Etapa 7: Configurar e executar

Quando o enriquecimento estiver em waiting_configuration, envie a coluna do documento e os datasets escolhidos.

{
  "document_column": 0,
  "datasets": ["person_basic_data"],
  "additional": {}
}

Ao iniciar, a API reserva o valor estimado quando aplicável e coloca o processamento em fila.

Configurar e executar

Envie coluna, datasets e campos adicionais para iniciar o processamento.

Etapa 8: Acompanhamento

Durante a execução, o status retorna progresso e métricas.

Campo	Descrição
`total_rows`	Total de linhas identificadas.
`processed_rows`	Registros processados.
`enriched_documents`	Documentos enriquecidos com sucesso.
`invalid_documents`	Documentos inválidos.
`not_found_documents`	Documentos sem retorno encontrado.
`failed_rows`	Registros que falharam.
`cost.consumed`	Valor consumido até o momento.
`cost.refunded`	Valor estornado, quando houver.

Consultar status

Acompanhe análise, progresso, custo e arquivos de saída.

Status do enriquecimento

Status	Descrição
`waiting_upload`	Enriquecimento criado e aguardando envio do arquivo.
`receiving_upload`	Arquivo sendo recebido pelo serviço de upload.
`validating_file`	Arquivo recebido e validação inicial em andamento.
`analyzing_file`	Arquivo em análise para identificação de colunas e amostras.
`uploading_storage`	Arquivo validado sendo salvo no storage.
`waiting_configuration`	Arquivo pronto para configuração.
`reserving_balance`	Valor estimado sendo reservado antes da execução.
`queued`	Enriquecimento aguardando processamento.
`processing`	Enriquecimento em execução.
`uploading_outputs`	Arquivos finais sendo enviados para storage.
`completed`	Enriquecimento concluído.
`completed_with_errors`	Enriquecimento concluído com falhas parciais.
`failed`	Enriquecimento falhou.

Arquivos de saída

Após conclusão, o enriquecimento pode gerar até quatro saídas.

Tipo	Arquivo	Descrição
`success`	`registros_enriquecidos.csv`	Registros enriquecidos com sucesso.
`not_found`	`nao_encontrados.csv`	Registros sem retorno nos datasets selecionados.
`failed`	`falhas.csv`	Registros com falha de processamento.
`invalid`	`documentos_invalidos.csv`	Registros ignorados por documento inválido.

Arquivos sem registros não são gerados. Consulte outputs para saber quais downloads estão disponíveis.

Arquivos de saída

Gere links temporários para baixar os arquivos finais.

Continuação de enriquecimentos

Se o usuário sair da tela antes de concluir o fluxo, o enriquecimento permanece salvo. Ao abrir novamente o item, use status e resume_step para retomar a etapa correta, como upload, revisão da análise, configuração ou progresso.

Regras importantes

O arquivo deve conter documentos válidos para o tipo escolhido.
CPFs e CNPJs inválidos são contabilizados como registros inválidos.
Registros válidos sem retorno nos datasets selecionados podem ser classificados como não encontrados.
Datasets com falha podem gerar estorno conforme a regra de cobrança aplicável.
Datasets disponíveis para consulta individual podem não estar habilitados para enriquecimento.
O processamento ocorre em segundo plano e pode ser acompanhado depois pela listagem ou status.

Próximos passos