1.0 Introdução
Gerenciar dados de pedidos entre lojas e sistemas parceiros é uma das tarefas mais demoradas para um administrador do PrestaShop. Migrar para uma nova loja significa recriar o histórico de pedidos manualmente. Enviar arquivos de pedidos diários para o armazém ou para a equipe financeira exige fazer login, exportar e enviar os arquivos de acordo com uma programação que precisa ser mantida por alguém. Corrigir registros corrompidos após uma transferência malsucedida significa horas de limpeza sem um registro claro do que deu errado. As Complemento Knowband para importação e exportação de pedidos, clientes e endereços do PrestaShop. Serve como um poderoso módulo de migração em massa para PrestaShop, lidando com todos os três desafios com facilidade. Ele transfere pedidos, clientes e endereços entre lojas PrestaShop e sistemas externos em CSV, XLSX, JSON e XML, com resolução de identidade entre lojas, entrega via FTP/SFTP, automação agendada e um registro de auditoria completo. Nenhum desenvolvedor é necessário em nenhuma etapa.
Este guia abrange todas as abas, etapas do assistente e configurações para que você possa configurar o Addon de Importação e Exportação de Pedidos, Clientes e Endereços do PrestaShop e começar a transferir dados de pedidos desde o primeiro dia. Compatível com PrestaShop 1.7.x até 9.x.
1.1 Para quem é o módulo de migração em massa do PrestaShop
O complemento Knowband PrestaShop Order, Customer and Address Import Export foi desenvolvido para:
- Lojistas que estão migrando de uma instalação existente do PrestaShop e precisam transferir todo o histórico de pedidos.
- Equipes operacionais que dependem da exportação de pedidos agendados do PrestaShop para enviar arquivos regularmente a armazéns, parceiros de logística ou sistemas de contabilidade.
- Administradores que precisam de gerenciamento de pedidos em massa no PrestaShop para corrigir registros, exportar um conjunto, editar no Excel e reimportar o arquivo corrigido.
- Qualquer organização que necessite de um registro verificável de cada movimentação de dados de pedidos para fins de auditoria ou conformidade.
Guia de Instalação 2.0 do Módulo de Migração em Massa do PrestaShop
Requerimentos do sistema
- PrestaShop 1.7.x, 8.x ou 9.x
- PHP 7.2 ou superior
Instalando o Módulo
Acesse o painel administrativo do PrestaShop, vá para Módulos e, em seguida, para Gerenciador de Módulos. Encontre a opção de upload no canto superior direito da tela. Selecione o arquivo ZIP da sua conta e confirme. O PrestaShop processará o upload automaticamente.
Após a conclusão do upload, clique em Instalar na janela que aparecer. A tela de configuração do módulo será aberta logo em seguida. Se o módulo não aparecer, digite “Importação e Exportação de Pedidos” na busca do Gerenciador de Módulos e clique em Configurar.
Problemas comuns de instalação
- O upload falhou: O servidor está rejeitando o arquivo devido ao tamanho. Peça ao seu provedor de hospedagem para aumentar os parâmetros upload_max_filesize e post_max_size para pelo menos 32 MB.
- Módulo não visível após a instalação: Limpe o cache do PrestaShop em Parâmetros Avançados, depois em Desempenho e pesquise novamente.
- A página de configuração parece estar com problemas: Limpe o cache do seu navegador e o cache do tema do PrestaShop em Design, depois em Tema e Logotipo e, por fim, em Configurações Avançadas.
Visão geral do painel de administração 3.0
O complemento Knowband PrestaShop Order, Customer and Address Import Export adiciona quatro abas principais ao painel administrativo:
- Configurações Gerais: Preferências de módulos, downloads de modelos de exemplo, limites de desempenho e configuração do CRON.
- Exportar: Crie e execute perfis de exportação usando o assistente de três etapas.
- Importar: Crie e execute perfis de importação usando o assistente de três etapas.
- Registros de transferência: Um histórico completo de cada execução de importação e exportação, incluindo status, contagem de registros e detalhes de erros em nível de linha.
4.0 Guia Configurações Gerais
A aba Configurações Gerais possui quatro subabas: Preferências, Arquivos de Modelo, Limites e Velocidade e Limpeza Agendada.
4.1 Preferências
Ativar/Desativar módulo: A opção principal para todo o Módulo de Migração em Massa do PrestaShop. Quando definida como Desativada, todas as tarefas agendadas de importação e exportação via CRON são pausadas automaticamente. Os assistentes manuais de Exportação e Importação no painel administrativo continuam funcionando normalmente, independentemente dessa configuração.
Número máximo de colunas visíveis: Define quantas colunas aparecem por vez na tabela de mapeamento de importação. O intervalo é de 1 a 20. Use as setas na interface de mapeamento para percorrer as colunas restantes.
Número máximo de linhas visíveis: Controla quantas linhas de dados de amostra aparecem na pré-visualização do mapeamento de importação. O intervalo é de 1 a 50.
Tamanho do lote de importação: O número de linhas que o módulo processa por requisição AJAX durante uma importação. O intervalo é de 10 a 500. Valores menores reduzem o risco de timeout em ambientes de hospedagem compartilhada, onde grandes importações atingem os limites de execução do PHP.
Clique Salvar configurações aplicar.
4.2 Arquivos de modelo
A subguia Arquivos de Modelo fornece arquivos de exemplo prontos para preenchimento para cada entidade compatível em todos os quatro formatos. Baixe um modelo antes de criar seu primeiro arquivo de importação para confirmar o layout das colunas.
Três entidades estão disponíveis:
- Formatos de pedido: CSV, JSON, XML, XLSX
- Clientes: CSV, JSON, XML, XLSX
- Formatos de entrada: CSV, JSON, XML, XLSX
Cada exemplo contém dados realistas e totalmente preenchidos em todas as colunas suportadas. Os modelos são gerados a partir do catálogo de colunas em tempo real e permanecem atualizados com quaisquer alterações de esquema.
4.3 Limites e Velocidade
Número máximo de registros por download: Número máximo de registros exportados por arquivo. O intervalo é de 100 a 50,000. Aumente somente quando a memória do servidor permitir.
Tamanho máximo de upload (MB): O tamanho máximo de arquivo de importação aceito pelo módulo. O intervalo é de 1 a 200 MB.
Clique Salvar configurações aplicar.
4.4 Limpeza Programada
Manter arquivos por (dias): Arquivos de importação com mais de 30 dias são excluídos automaticamente pelo CRON de limpeza. O intervalo é de 1 a 30 dias.
URL de limpeza do CRON: Cole este URL no gerenciador de tarefas (cron) do seu servidor para excluir arquivos temporários de importação antigos de acordo com uma programação. O exemplo é executado diariamente às 2h da manhã.
URL CRON para exportação de perfis: Cole este URL no gerenciador de cron do seu servidor para executar todos os perfis de exportação marcados como habilitados para CRON. Escolha a frequência que melhor se adequa às suas necessidades de exportação de pedidos agendados do PrestaShop, por exemplo, diariamente às 3h da manhã.
URL CRON para importação de perfis: Cole este URL no gerenciador de tarefas (cron) do seu servidor para executar todos os perfis de importação de origem FTP marcados como habilitados para CRON. Os perfis de origem de upload são apenas manuais e são ignorados automaticamente quando este URL é executado. Exemplo: diariamente às 4h da manhã.
Todas as três URLs são protegidas por token. Somente as solicitações que contêm o token correto acionam a operação.
5.0 Aba Exportar: Assistente de Três Etapas
A guia Exportar lista todos os perfis de exportação salvos e fornece o assistente para criar novos. Cada linha da lista mostra o nome do perfil, o tipo de dados, o formato do arquivo e o status da última execução. Clique no botão Executar para executar um perfil imediatamente. Clique em Editar para alterar as configurações.
Etapa 1: Transferir configurações
Nome do perfil: Uma etiqueta única que identifica este perfil na lista de exportação.
Rótulo do arquivo de saída: Nome base do arquivo gerado. A extensão é adicionada automaticamente. Suporta tokens dinâmicos (consulte a Seção 10).
Tipo de dados: Escolha o que exportar: Pedidos, Clientes ou Endereços.
Formato de arquivo: CSV, XLSX, XML ou JSON. Os formatos CSV e XLSX abrem diretamente em qualquer aplicativo de planilha. Os formatos XML e JSON são adequados para integração com outros sistemas.
Shop: Em uma configuração com várias lojas, limita a exportação aos registros pertencentes à loja selecionada.
Intervalo de datas (opcional): Filtre por data de criação do pedido. Deixe em branco para exportar todos os registros.
Ordem de gravação (opcional): Controle a sequência das linhas no arquivo de saída. Classifique por ID, Referência, Data de Criação, Data de Atualização, Total Pago ou Estado, em ordem crescente ou decrescente. Deixe a configuração padrão para usar a ordem do banco de dados.
Seções de coluna opcionais: Três opções independentes controlam se os blocos de coluna inteiros são incluídos na exportação.
- Incluir detalhes do endereço da fatura: Quando desativado, apenas o ID do endereço da fatura é exportado. Quando ativado, todas as colunas do endereço da fatura são incluídas.
- Incluir detalhes do endereço de entrega: Quando desativado, apenas o ID do endereço de entrega é exportado. Quando ativado, todas as colunas do endereço de entrega são incluídas.
- Incluir detalhes de pagamento: Quando desativado, apenas o nome do módulo de pagamento é exportado. Quando ativado, as colunas de valor do pagamento, moeda, método e ID da transação são incluídas.
Execução agendada (ativar CRON): Quando ativada, a URL CRON de Exportação de Perfis executa este perfil automaticamente e armazena o arquivo gerado na guia Logs de Transferência.
Destino da exportação: Selecione Sistema de Arquivos para salvar o arquivo localmente e baixá-lo na página de Registros de Transferência. Selecione FTP/SFTP para enviar o arquivo para um servidor remoto após cada execução. Uma cópia local também é mantida como opção de download alternativo quando FTP/SFTP é selecionado.
Configurações de FTP/SFTP (quando o destino FTP/SFTP estiver selecionado):
- Protocolo de transferência: FTP, FTPS (FTP sobre TLS) ou SFTP (SSH). O SFTP é recomendado para ambientes de produção.
- Servidor, Porta (atualiza automaticamente quando o protocolo muda: 21 para FTP, 990 para FTPS, 22 para SFTP).
- Nome de usuário e senha (armazenados criptografados em repouso).
- Caminho absoluto para a pasta no servidor remoto. A pasta deve existir e ter permissão de escrita.
- Modo passivo: Ativado por padrão. Recomenda-se mantê-lo ativado para que os firewalls não bloqueiem as transferências.
- Botão Testar Conexão: valida as credenciais no servidor ativo antes de salvar o perfil.
Estilo de saída: Vírgula universal para a maioria das aplicações, ponto e vírgula para o Excel europeu ou separador de tabulação para ferramentas de dados.
Lista de cola: O separador usado para campos com múltiplos valores. Barra vertical (|), barra invertida (|) ou vírgula (|).
Filtrar pedidos por (filtros opcionais):
- Status do pedido: filtre por um ou mais status.
- Operadora: filtre por uma ou mais operadoras.
- Moeda: filtre por uma ou mais moedas.
- Método de pagamento: filtre por um ou mais módulos de pagamento.
- Faixa de valor total pago: inclui apenas pedidos dentro de um valor total pago mínimo e máximo (impostos incluídos).
Deixe qualquer filtro vazio para incluir todos os registros dessa dimensão.
Clique Próximo Passo para prosseguir.
Etapa 2: Selecione os campos
Selecione os campos que deseja incluir na exportação dentre as 155 colunas disponíveis. Use Selecionar Tudo, Desmarcar Tudo ou Restaurar aos Padrões, conforme necessário. Os campos obrigatórios não podem ser desmarcados. Arraste as linhas para reordenar as colunas no arquivo de saída.
Os 155 campos disponíveis estão distribuídos em seis seções: dados do pedido, dados do cliente, dados do endereço, dados de pagamento e dados da linha de produtos.
Etapa 3: Gerar arquivo
Analise o resumo da exportação, o tipo de dados, o formato do arquivo, o rótulo do arquivo e a quantidade de campos. Clique em “Criar e baixar” para gerar o arquivo imediatamente ou salve o perfil e deixe que a execução do CRON o processe conforme agendado.
6.0 Aba Importar: Assistente de Três Etapas
A aba Importar lista todos os perfis de importação salvos e fornece o assistente para criar novos.
Passo 1: Configurações da fonte
Nome do perfil: Uma etiqueta exclusiva para este perfil na lista de importações.
Tipo de dados: Pedidos, Clientes ou Endereços. Clientes e endereços atualizam os registros existentes quando há correspondência. Os pedidos são sempre criados do zero; pedidos existentes não podem ser atualizados por meio deste módulo.
Formato de arquivo: CSV, XLSX, JSON ou XML.
Estilo de saída e lista de junção: Deve corresponder às configurações utilizadas quando o arquivo foi exportado.
Shop: Os pedidos importados são sempre criados na loja selecionada.
Fonte: Carregar arquivo para importação manual única a partir de um arquivo local. FTP/SFTP para obter o arquivo de um servidor remoto. A origem FTP/SFTP é necessária para execuções de importação controladas por CRON.
Configurações de FTP/SFTP: Os campos são os mesmos do assistente de exportação: protocolo, servidor, porta, nome de usuário, senha, caminho do arquivo remoto, modo passivo e teste de conexão.
CRONO: Disponível apenas para perfis de origem FTP. Quando ativada, a URL CRON de Importação de Perfis busca o arquivo no caminho remoto e executa a importação automaticamente, sem intervenção manual.
Clique Salvar perfil para salvar sem executar, ou Próximo Passo Para prosseguir com o mapeamento.
Etapa 2: Mapear colunas
O módulo de migração em massa do PrestaShop lê o arquivo carregado e associa automaticamente os cabeçalhos das colunas aos campos do PrestaShop. No módulo em produção, 154 das 155 colunas são associadas automaticamente a partir dos nomes de cabeçalho reconhecidos.
A tela de mapeamento exibe as primeiras linhas do arquivo como uma pré-visualização em tempo real, permitindo que o administrador verifique os dados antes de confirmá-los. Os campos obrigatórios são marcados com um asterisco. Pesquise colunas por nome usando o campo de pesquisa acima da tabela.
Analise as atribuições automáticas e ajuste as que precisarem de correção. Na maioria dos casos, as variantes de nomenclatura comuns provenientes de sistemas externos são reconhecidas automaticamente.
Etapa 3: Executar a importação
Mapeamento confirmado. Clique Iniciar importação Para começar, o módulo processa o arquivo em lotes com base na configuração “Tamanho do Lote de Importação” em Preferências. Um indicador de progresso mostra o status atual.
Clique Salvar perfil antes de começar a preservar o mapeamento de colunas para execuções futuras da mesma estrutura de arquivo.
7.0 Resolução de Identidade entre Lojas
A migração de pedidos entre instalações do PrestaShop é o caso de uso mais complexo para qualquer módulo de migração de lojas PrestaShop. Os IDs brutos do banco de dados para clientes, endereços e produtos diferem entre as lojas e não podem ser usados como identificadores de transferência.
O complemento de migração de pedidos do PrestaShop resolve todos os três tipos de entidade usando identificadores que permanecem estáveis entre instalações:
Clientes são identificadas por endereço de e-mail. Caso não haja correspondência, uma nova conta é criada utilizando o nome, o e-mail e uma senha gerada pelo sistema. O cliente redefine suas credenciais e acessa sua conta na nova loja imediatamente.
Endereços são correspondidos por um hash composto construído a partir do nome, sobrenome, primeiro parágrafo do endereço, código postal, cidade e telefone. Se não houver correspondência, um novo registro de endereço é criado a partir dos dados importados.
Produtos e combinações são correspondidas por referência de produto e referência de combinação. Uma referência não resolvida rejeita todo o pedido; não são permitidas gravações parciais nem itens de linha que apontem para produtos ausentes.
Uma exportação completa de uma loja é importada sem problemas para uma instalação separada usando este módulo de migração de lojas PrestaShop, sem qualquer remapeamento manual de contas, endereços ou IDs de produtos.
8.0 Integridade e Validação de Dados
O importador impõe atomicidade em nível de pedido. Se algum item de um pedido falhar na validação, o pedido inteiro é excluído do lote. Nenhum registro parcial de pedido é gravado no banco de dados.
Cada rejeição gera um registro preciso no log:
Linha 23: a coluna “currency_iso” contém “USDD”, quando era esperado um código ISO 4217 de 3 letras (ex.: USD, EUR, GBP). Linha 41: a coluna “customer_email” contém “not-an-email”; um endereço de e-mail válido é necessário.
Corrija apenas as linhas afetadas no arquivo de origem e importe-as novamente. O restante do lote não será afetado.
9.0 Aba de Registros de Transferência
Cada operação de importação e exportação registra uma entrada no guia “Registros de Transferência”. Cada linha mostra:
- IDENTIDADE: Número de execução sequencial.
- Tipo: Exportar ou importar.
- Entidade: Pedidos, Clientes ou Endereços.
- Formato: CSV, XLSX, JSON ou XML.
- Estado: Concluído ou reprovado.
- Registros: Quantos registros foram processados pela execução?
- arquivo: O nome do arquivo, com um link para download dos arquivos exportados.
- Data: Quando a corrida começou.
Filtre o registro por ID, tipo, entidade, formato, status ou intervalo de datas usando os controles na parte superior da tabela.
Os arquivos de exportação anteriores podem ser baixados novamente diretamente do registro, sem a necessidade de executar a exportação novamente. Os detalhes de erro em nível de linha estão acessíveis para qualquer execução que tenha apresentado falhas.
10.0 Tokens de nome de arquivo dinâmicos
Os rótulos dos arquivos de saída suportam nove tokens de tempo de execução que se expandem no momento da geração:
- O arquivo orders_{DATE}.xlsx gera o arquivo orders_20260608.xlsx.
- {COMPRAR}ordensO arquivo {DATETIME}.csv gera o arquivo mystore_orders_20260608_143215.csv.
Tokens disponíveis: {DATE}, {DATETIME}, {TIME}, {YEAR}, {MONTH}, {DAY}, {ENTITY}, {FORMAT}, {SHOP}.
11.0 perguntas frequentes
P: O que é o complemento Knowband PrestaShop Order, Customer and Address Import Export e qual a sua função?
O módulo Knowband PrestaShop Bulk Migration é uma ferramenta de transferência em massa de dados de pedidos que importa e exporta pedidos, clientes e endereços do PrestaShop em formatos CSV, XLSX, JSON e XML. Ele lida com a resolução de identidade entre lojas, perfis de transferência reutilizáveis com mapeamento de colunas salvo, entrega de arquivos via FTP e SFTP, automação agendada via CRON, 155 campos exportáveis, notificações por e-mail e um registro completo da transferência com detalhes de erros em nível de linha. Compatível com PrestaShop 1.7.x até 9.x.
P: Como faço para migrar pedidos de uma loja PrestaShop para outra?
Crie um perfil de exportação na loja de origem e baixe o arquivo de pedidos. Na loja de destino, crie um perfil de importação, carregue o arquivo, confirme o mapeamento de colunas e execute a importação. O complemento de migração de pedidos do PrestaShop resolve os clientes por e-mail, os endereços por hash composto e os produtos por referência. Não é necessário remapear manualmente contas, endereços ou IDs de produtos entre as duas lojas.
P: O que acontece se uma referência de produto no arquivo de importação não existir na loja de destino?
O pedido inteiro que contém esse item é excluído da importação. Nenhum registro parcial do pedido é gravado. A guia “Logs de Transferência” registra o número da linha, o nome da coluna e o valor específico que não pôde ser resolvido. Corrija apenas as linhas afetadas e importe-as novamente.
P: Quais formatos de arquivo o módulo de migração em massa do PrestaShop suporta?
CSV, XLSX, JSON e XML, todos os quatro formatos disponíveis tanto para importação quanto para exportação. Os formatos CSV e XLSX podem ser abertos em qualquer aplicativo de planilha. Os formatos JSON e XML são adequados para integrações de sistemas e parceiros baseados em API.
P: Como funciona a exportação agendada de pedidos do PrestaShop via CRON?
Habilite o CRON em qualquer perfil de exportação, defina o destino como FTP/SFTP e copie o URL do CRON dos perfis de exportação das Configurações Gerais para o gerenciador de cron do seu servidor com o intervalo necessário. Todos os perfis de gerenciamento de pedidos em massa do PrestaShop com CRON habilitado são executados automaticamente nesse agendamento, enviam o arquivo para o servidor configurado e enviam uma notificação de conclusão. Os perfis de importação com upload a partir de uma fonte são apenas manuais e são ignorados automaticamente quando o URL do CRON dos perfis de importação é acionado.
P: Posso filtrar quais pedidos serão exportados?
Sim. O assistente de exportação inclui filtros para status do pedido, transportadora, moeda, método de pagamento e intervalo de valor total pago. Um filtro de intervalo de datas restringe as exportações a um período de criação específico. Aplique qualquer combinação de filtros e deixe o restante em branco para incluir todos os registros dessas dimensões.
P: Como funciona a transferência de arquivos via FTP e SFTP?
Os perfis de exportação enviam arquivos para FTP (porta 21), FTPS (FTP sobre TLS, porta 990) ou SFTP (SSH, porta 22). Os perfis de importação baixam arquivos de FTP ou SFTP de acordo com um agendamento. As credenciais são armazenadas criptografadas. Um botão de teste de conexão valida a conexão antes que o perfil seja salvo. Se o envio falhar, o arquivo é salvo localmente e um e-mail de notificação explica a falha.
P: O que é a funcionalidade do módulo de backup de pedidos do PrestaShop?
Cada execução de importação e exportação registra uma entrada no guia “Registros de Transferência” com data, nome do arquivo, tipo de entidade, status e contagem de registros. Arquivos de exportação anteriores são baixados novamente do registro sem a necessidade de executar a exportação novamente. Isso fornece às organizações com requisitos de auditoria ou conformidade um registro completo e com data e hora de todas as movimentações de dados de pedidos.
P: Quantos campos podem ser exportados por pedido usando o módulo de migração em massa do PrestaShop?
Estão disponíveis 155 campos distribuídos entre dados de pedidos, dados de clientes, dados de linhas de produtos, dados de endereços e dados de pagamentos. Opções por seção permitem que os administradores incluam ou excluam o bloco de endereço completo da fatura, o bloco de endereço de entrega e o bloco de detalhes de pagamento de forma independente, para manter os arquivos compactos quando colunas inteiras não forem necessárias.
P: O complemento de importação e exportação de pedidos, clientes e endereços do PrestaShop é compatível com o PrestaShop 9?
Sim. O Add-on para Importação e Exportação de Pedidos, Clientes e Endereços do PrestaShop Compatível com PrestaShop 1.7.x até 9.x. Consulte a página do produto para obter os detalhes de compatibilidade mais recentes.
Conclusão 12.0
Este complemento abrange todas as necessidades de transferência de dados de pedidos a partir de um único painel administrativo. Exporte qualquer combinação de pedidos, clientes e endereços para o formato exigido por cada sistema de recebimento. Importe o histórico completo de pedidos para uma nova loja sem a necessidade de remapeamento manual de contas. Agende tudo via CRON e envie arquivos automaticamente via FTP ou SFTP.
Cada execução é registrada com o módulo de backup de pedidos do PrestaShop, mantendo o carimbo de data/hora de cada entrada. Cada falha gera uma mensagem de erro precisa e solucionável. Todos os arquivos de exportação permanecem disponíveis para download novamente. Para suporte, requisitos de desenvolvimento personalizado ou serviços de complementos para PrestaShop, entre em contato com a equipe de suporte da Knowband ou visite a página do produto Knowband diretamente.