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

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 ativo. 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. Caminho errado gera 'diretório não encontrado' no log a cada varredura.

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

   **Sincronização por Api** — Precisa estar Sim. É esta chave que coloca o layout na varredura — layout com ela desligada nunca é lido.

8. 8

   **Início do item** — 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.

Parâmetros que mudam esta tela

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, diretório errado no layout e 'Sincronização por Api' desligada.

**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)