Importação de arquivos — como o motor de layout funciona

Todas as opções do motor que lê arquivos do cliente e cria movimentos no WMS: onde configurar, como o layout localiza cada informação, e a diferença entre arquivo de texto (.txt/.csv) e planilha (.xlsx).

IntegraçõesAtualizado em 11/11/2026

Quando usar

Ao configurar um cliente novo que envia arquivo, ao adaptar um layout porque o arquivo do cliente mudou, ao investigar por que um arquivo não entrou, ou ao entender um aviso de pasta no Log de Integração.

Antes de começar

  • Um arquivo de exemplo REAL do cliente (não vale um modelo)
  • Cliente cadastrado no WMS
  • Produtos do cliente cadastrados em Produto do Cliente, com o código exatamente como vem no arquivo
  • Pasta definida no servidor onde o cliente vai depositar os arquivos

O WMS consegue criar recebimentos, devoluções, pedidos de expedição e cross-docking a partir de um arquivo que o cliente gera no sistema dele. Quem faz isso é o motor de layout: você descreve uma vez onde cada informação está dentro do arquivo, e a partir daí o sistema lê sozinho, de minuto em minuto, tudo que aparecer na pasta configurada. Este artigo cobre o motor inteiro — as opções comuns a qualquer arquivo e depois as particularidades de texto e de planilha.

1. Como o motor funciona

O sistema varre, a cada minuto, a pasta configurada em cada layout que tem Movimento. Ao encontrar um arquivo, ele lê linha a linha usando o que você descreveu no layout, monta uma integração (a fotografia do arquivo) e a partir dela cria o movimento no WMS. Dando certo, o arquivo é movido para a subpasta 'Importados' — é assim que você sabe, olhando a pasta, o que já entrou.

O mesmo arquivo não entra duas vezes: o controle é pelo nome. Se o cliente reenviar um arquivo com o nome que já foi importado, o sistema registra no log e ignora. Para reprocessar de propósito, renomeie o arquivo.

Quando algo dá errado — produto não cadastrado, pasta inexistente, coluna que não bate — nada é gravado pela metade: o arquivo fica onde está e o motivo vai para o Log de Integração. É lá que você deve olhar primeiro sempre que um arquivo 'não entrou'.

2. Configuração do layout (vale para qualquer arquivo)

Configurações → Importação de Texto (Layout) → Criar.

  1. 1

    Descrição — Nome do layout. Use algo que identifique cliente e finalidade, porque essa lista cresce.

  2. 2

    Tipo — Importação (arquivo que entra) ou Exportação (arquivo que o WMS gera para o cliente).

  3. 3

    Movimento — O que será criado: Recebimento, Devolução, Pedido de Expedição, Cross-Recebimento ou WMS Faturamento. É o que decide o tipo de movimento gerado.

  4. 4

    Cliente — Dono do arquivo. É por ele que o sistema procura o produto e resolve os parâmetros de conferência.

  5. 5

    Diretório do arquivo — Pasta no servidor que será varrida. Em servidor Linux o caminho é sensível a maiúsculas — /mnt em minúsculo. Cada layout precisa da sua pasta: não aponte um recebimento e um pedido para a mesma pasta, senão o arquivo de um pode ser importado pelo outro. Pasta que não existe gera no Log de Integração a linha 'Diretório ... não foi encontrado' (veja a seção 8).

  6. 6

    Agrupar arquivo — Sim = tudo que estiver no arquivo vira um único movimento. Não = o sistema quebra em vários movimentos conforme o agrupamento do arquivo. Para uma carga por arquivo, use Sim.

  7. 7

    Entrada na varredura — Não há chave para ligar: ao salvar, todo layout com Movimento passa a ser lido na varredura, mesmo que a pasta dele ainda não exista. Layout que não é mais usado deve ser excluído na lista de Importação de Texto (Layout), botão Excluir.

  8. 8

    Linha início itens — Número da primeira linha com dados. Use 2 quando a linha 1 for o cabeçalho de títulos.

  9. 9

    Tipo conferência — Sobrepõe o parâmetro do cliente. Integração = o coletor confere contra as caixas do arquivo. Manual = o operador informa produto e quantidade.

3. Campos — ligando o arquivo aos dados do WMS

Na aba Campos você diz qual pedaço do arquivo alimenta cada informação do WMS. Cada linha da configuração é um par: de um lado o campo do WMS (Código do Produto, Número Lote, Etiqueta Pallet, Data Fabricação, Quantidade, e assim por diante); do outro, onde encontrá-lo no arquivo.

Existem dois modos de localizar o valor. No modo por posição, você informa início e tamanho — bom para arquivos de largura fixa, em que cada campo sempre ocupa as mesmas colunas. No modo por título, você deixa início e tamanho zerados e escreve, em Campo Fixo, o título da coluna como ele aparece no cabeçalho do arquivo; o sistema procura esse título e descobre a posição sozinho, a cada arquivo. O segundo modo é mais robusto quando o cliente muda a largura das colunas conforme o conteúdo.

O Agrupamento diz em que altura do arquivo aquele campo aparece: Item (linha de detalhe, normalmente a caixa) ou Agrupamento Produto (linha que abre um produto). Campos de cabeçalho ficam na aba própria.

Casas decimais é para número sem vírgula. Um arquivo que grava 4080 quer dizer 4,080 quando você configura 3 casas. Já 'Remove zero à esquerda' resolve o caso clássico de o arquivo trazer 039721 e o cadastro do cliente ter 39721 — a busca do produto é por igualdade exata, então sem essa marcação o arquivo inteiro é recusado. Cuidado para não ligá-la em campos como o lote, porque um lote 010626QA viraria 10626QA.

4. Arquivo de texto (.txt e .csv)

É o formato mais comum: uma linha por registro. O motor aceita tanto largura fixa quanto separador. Com separador, preencha o caractere que divide os campos e liste os campos na mesma ordem em que aparecem na linha — a leitura é sequencial. Com largura fixa, informe início e tamanho de cada campo.

Arquivos com mais de um tipo de linha (um para o cabeçalho, outro para o produto, outro para a caixa) usam o Identificador: você declara um campo Identificador com o valor esperado, e o motor só aplica aquele conjunto de campos nas linhas que começam com ele.

Quando o cliente gera o arquivo com cabeçalho de títulos, prefira o modo por título — é o que evita ter que refazer o layout toda vez que a largura de uma coluna muda.

A codificação é detectada automaticamente (UTF-8, UTF-16 e Latin-1), então acento trocado normalmente não é problema de configuração.

5. Planilha (.xlsx)

Use quando o cliente envia um relatório em Excel — não uma tabela simples, mas aquele formato em blocos que se repetem.

A diferença é a forma. Um relatório desses não tem uma linha por registro: ele tem faixas que se repetem — a carga, dentro dela a entrega com a nota fiscal, dentro dela o item, o lote, o pallet — e no fim de cada bloco uma célula só com todos os códigos de caixa emendados. Não dá para ler isso como se fosse uma tabela.

O que o sistema faz é percorrer a planilha guardando o contexto de cada faixa: achou a carga, guarda a carga; achou a entrega, guarda a nota. Ao chegar na lista de caixas, gera uma linha por caixa repetindo tudo que estava guardado. A partir daí é um arquivo comum, e vale exatamente o que foi explicado sobre Campos — os campos são localizados pelo título da coluna.

A configuração fica no próprio layout, no bloco 'Leitura de planilha', montado em tela: você declara cada bloco (em que coluna procurar, com que texto ele começa, qual o nível de profundidade) e, dentro dele, o que capturar. O Nome que você der a cada campo é o título da coluna gerada — é esse nome que você usa depois em Campo Fixo, na aba Campos. Os nomes são livres; só precisam ser iguais nos dois lugares.

O Nível merece atenção: ao entrar num bloco de nível 2, tudo que foi guardado nos níveis 2 ou mais internos é descartado. É isso que impede o próximo item de herdar o lote do anterior.

Campo marcado como Apoio entra no cálculo mas não vira coluna. É o caso do peso e do volume do pallet, que existem só para dividir o peso entre as caixas. Isso não é detalhe: toda coluna gerada precisa estar mapeada na aba Campos, senão ela é engolida pela coluna anterior e o valor sai grudado com o vizinho.

6. Quando o arquivo não traz tudo

Alguns relatórios não informam o peso de cada caixa, nem data de fabricação, nem validade. Em vez de recusar, o sistema deduz o que der: o peso de cada caixa sai da divisão do peso do pallet pela quantidade de caixas dele, e a data de fabricação sai do começo do código do lote, quando esse código começa com uma data.

O formato da data no lote aceita alternativas separadas por barra vertical, e a ordem importa — ddMMyyyy antes de ddMMyy faz um lote 11122025 ser lido como 11/12/2025 em vez de 11/12/2020. Data que caia no futuro é descartada, porque fabricação futura trava a conferência.

A validade, quando não vem no arquivo, é calculada somando à fabricação os dias de validade cadastrados no produto — a mesma conta que a conferência usa para criticar validade.

7. Conferir se deu certo

  1. 1

    Pasta — O arquivo saiu da pasta e foi para 'Importados'? Então entrou.

  2. 2

    Log de Integração — Toda recusa tem uma linha com o motivo e a linha do arquivo.

  3. 3

    Movimento — Abra o movimento gerado e confira os itens, as quantidades e a carga.

  4. 4

    Caixas — Nos itens, abra 'Caixas do Produto' para ver caixa a caixa: lote, pallet, nota fiscal, fabricação e validade.

8. Avisos de pasta no Log de Integração

Além das recusas de arquivo, o Log de Integração (Menu Wms > Log de Integração) mostra avisos sobre a pasta de cada layout. Neles a coluna Arquivo fica vazia, porque nenhum arquivo foi lido, e a coluna Tipo mostra o Movimento do layout. Cada aviso aparece uma vez por dia para cada layout: nas varreduras seguintes do mesmo dia o sistema só atualiza o horário da coluna Data, sem criar linha nova.

Log de Integração: a linha 'Diretório ... não foi encontrado' do layout de pedido sem pasta (uma por dia, com Arquivo vazio e o caminho na Descrição) e o aviso de pasta lida por dois layouts, uma linha com o Tipo de cada movimento
Avisos de pasta
Mensagem na coluna DescriçãoO que quer dizerO que fazer
Diretório (caminho) configurado no layout (nome) não foi encontradoA pasta informada em Diretório do arquivo não existe no servidorConfira o caminho no layout (no Linux, maiúsculas e minúsculas contam) e crie a pasta. Se o layout não é mais usado, exclua-o
Nenhum diretório configurado no layout (nome)O layout está sem Diretório do arquivoPreencha o Diretório do arquivo ou exclua o layout
A pasta (caminho) do layout (nome) também é lida por layout (outro nome): um arquivo deixado nela pode ser importado pelo layout erradoLayouts de movimentos diferentes, como um recebimento e um pedido, leem a mesma pastaDê a cada layout a sua pasta. O aviso não bloqueia nada: a importação continua como está

Parâmetros que mudam esta tela

Parâmetros
OndeParâmetroO que muda
ClienteConferência por integração (Cadastro do Cliente → WMS)Coletor confere contra as caixas do arquivo
ProdutoDias de validade (Cadastro de Produto)Calcula a validade quando o arquivo não traz
ProdutoTipo de peso (Cadastro de Produto)Define como quantidade e volume são interpretados
LayoutMovimento (Configurações → Importação de Texto (Layout))Layout salvo com Movimento entra na varredura automática

Perguntas frequentes

O arquivo continua na pasta e nada aconteceu. Olhe o Log de Integração. As causas mais comuns são produto não cadastrado para o cliente e diretório errado no layout (o log mostra 'Diretório ... não foi encontrado').

Todo dia aparece no log 'Diretório ... não foi encontrado' de um layout que ninguém usa. Enquanto o layout existir, ele é lido na varredura. Exclua-o em Importação de Texto (Layout) ou crie a pasta indicada na mensagem.

Preciso reimportar o mesmo arquivo. O controle de duplicidade é pelo nome. Renomeie o arquivo e coloque de novo na pasta.

O produto existe, mas o arquivo é recusado dizendo que não. A busca é por igualdade exata no código do cliente. Compare caractere a caractere — zeros à esquerda e sufixos como '-0' são a causa mais frequente. Para zeros à esquerda, marque 'Remove zero à esquerda' só no campo do código do produto.

Uma coluna da planilha veio grudada com a seguinte. Alguma coluna está sendo gerada sem estar mapeada na aba Campos. Marque-a como Apoio na configuração da planilha ou mapeie-a.

Posso usar o mesmo layout para dois clientes? Não. O layout é por cliente, porque a busca de produto e os parâmetros de conferência dependem dele. Copie a configuração da planilha pelo JSON e troque o cliente.

Telas relacionadas

Importação de Texto (Layout) (/apes-local/configuracoes/layout-text)

Log de Integração (/apes-local/wms/log-integration/grid)

Produto do Cliente (/apes-local/cadastros/product)

Artigos relacionados

Importação de arquivos — como o motor de layout funciona · Central de Ajuda Hap