# Importação e Exportação CSV e XML para PrestaShop: guia completo
> Guia de instalação, configuração e utilização do módulo DF CSV & XML Pro para PrestaShop 8 e 9: perfis, mapeamento visual, formatos de colunas, fontes FTP/SFTP/URL, agendamento por cron, registos e resolução de problemas.
- Página:
- Idioma: pt
- Atualizado em: 2026-09-03
- Outros idiomas: [fr](https://www.datafirefly.com/documentation/import-export-csv-xml-prestashop/index.md), [en](https://www.datafirefly.com/en/documentation/import-export-csv-xml-prestashop/index.md), [es](https://www.datafirefly.com/es/documentation/import-export-csv-xml-prestashop/index.md), [de](https://www.datafirefly.com/de/documentation/import-export-csv-xml-prestashop/index.md), [it](https://www.datafirefly.com/it/documentation/import-export-csv-xml-prestashop/index.md), [pl](https://www.datafirefly.com/pl/documentation/import-export-csv-xml-prestashop/index.md), [nl](https://www.datafirefly.com/nl/documentation/import-export-csv-xml-prestashop/index.md)
- Índice:
O DF CSV & XML Pro é um motor de importação/exportação universal para PrestaShop 8 e 9. Liga qualquer ficheiro CSV ou XML à sua loja graças a um mapeamento visual das colunas, guarda cada configuração num perfil reutilizável, e pode recuperar automaticamente os seus feeds de fornecedores a partir de FTP, SFTP ou de um URL. Este guia cobre a instalação, a criação de perfis, os formatos de colunas esperados, o agendamento por cron, os registos e a resolução de problemas.
## Instalação
Vá a **Módulos > Gestor de módulos > Adicionar um módulo**, envie o ficheiro `dfcsvpro.zip` e clique em **Instalar**. Depois de instalado, aparece um separador **DF CSV Pro** em **Parâmetros avançados**.
O módulo não acrescenta nenhum override do núcleo do PrestaShop e desinstala-se de forma limpa. São criadas duas tabelas (perfis e registos) e algumas variáveis de configuração; são eliminadas na desinstalação.
## Criar um perfil
Um **perfil** descreve uma operação completa: sentido (importação ou exportação), entidade, formato, fonte, mapeamento das colunas, opções e agendamento. Relança-se num clique ou dispara automaticamente por cron. Clique em **Novo perfil**: um assistente guia-o em quatro etapas.
### 1. Geral
Escolha o **sentido** (importação / exportação), a **entidade**, o **formato** (CSV ou XML) e o **idioma** visado. Para o CSV, defina o delimitador (ou deixe em deteção automática: o Excel em português exporta em ponto e vírgula), a codificação (UTF-8, ISO-8859-1 ou Windows-1252), o número de linhas a ignorar antes do cabeçalho e o separador multivalor (vírgula por defeito). Para o XML, pode precisar o nó de item ou deixar o módulo detetá-lo.
Entidades disponíveis na **importação**: produtos, declinações, categorias, clientes, stock e preços. Na **exportação**: produtos, categorias, clientes, encomendas.
### 2. Fonte
Selecione de onde provém o ficheiro (importação) ou onde depositar o resultado (exportação): **carregamento manual**, **URL** (HTTP/HTTPS), **FTP**, **SFTP** ou **caminho local**. Para FTP/SFTP, preencha anfitrião, porta, utilizador e palavra-passe, e use depois o botão **Testar a ligação** para validar antes de guardar.
### 3. Mapeamento visual
Carregue um ficheiro de exemplo (ou recupere-o a partir da fonte remota): o módulo deteta as colunas, mostra uma pré-visualização das primeiras linhas e associa automaticamente cada coluna ao campo PrestaShop certo graças a um reconhecimento FR/EN (référence/SKU, prix/price, quantité/stock, EAN/gencod, TVA/VAT, etc.). Cabeçalhos em português (« referência », « preço », « quantidade ») não são reconhecidos automaticamente: ajuste as associações na tabela; qualquer coluna deixada em « não mapeada » é simplesmente ignorada.
A **chave de correspondência** (etapa 4) determina como um produto existente é encontrado: ID, referência/SKU, EAN-13 ou MPN. Certifique-se de que a coluna correspondente está mapeada.
### 4. Opções e agendamento
Defina o comportamento da importação: criar os elementos em falta, atualizar os existentes, criar as categorias na hora, descarregar as imagens a partir de URLs, substituir ou não as imagens existentes na atualização, e o tamanho do lote (linhas processadas por chamada AJAX). Ative eventualmente o **agendamento** e escolha a frequência (horária, diária ou semanal). Guarde: o perfil aparece na lista, pronto a ser lançado ou agendado.
## Formatos de colunas
O módulo compreende os formatos de negócio do PrestaShop. Eis as convenções esperadas nos seus ficheiros:
| Campo | Formato esperado |
| --- | --- |
| Preço | Decimal, vírgula ou ponto: `19,90` ou `19.90` |
| Booleanos (ativo, etc.) | `1/0`, `yes/no`, `oui/non`, `true/false` |
| Categorias | Nomes ou IDs separados pelo separador multivalor (por defeito `,`). Criação na hora em opção. |
| Imagens | URLs separados pelo separador multivalor. O primeiro torna-se a imagem de capa. |
| Características | `Nome:Valor\|Nome:Valor` |
| Declinações | `Grupo:Valor\|Grupo:Valor` (ex. `Tamanho:M\|Cor:Vermelho`) |
| Taxa de IVA | Valor numérico (ex. `23`), ligado ao grupo de impostos do país por defeito |
### Declinações
A coluna dos atributos segue o formato `Grupo:Valor|Grupo:Valor`. Os grupos e valores de atributos em falta são criados automaticamente, e a declinação é identificada pelo seu conjunto exato de atributos: relançar a importação não cria portanto duplicado. O produto pai é encontrado pela sua referência ou pelo seu ID segundo a chave de correspondência.
### Características
Use o formato `Nome:Valor|Nome:Valor`. Cada característica e o seu valor são criados se ainda não existirem.
### Categorias, imagens e tags
Estes campos aceitam vários valores, separados pelo separador multivalor definido no perfil. Para as categorias, pode misturar nomes e IDs; a primeira imagem listada serve de capa.
## Fontes remotas e segurança
Na importação, o módulo recupera o ficheiro a partir de um URL (HTTP/HTTPS, com autenticação básica se necessário), de um servidor FTP (modo passivo ou ativo), de um servidor SFTP ou de um caminho local restrito ao diretório da loja. Na exportação, pode depositar o ficheiro gerado em FTP/SFTP ou numa pasta local, ou propô-lo para descarregamento.
O **SFTP** requer a extensão PHP `ssh2`. Se estiver ausente do seu alojamento, a interface indica-o claramente e pode usar FTP ou um URL em alternativa.
As palavras-passe FTP/SFTP são cifradas em repouso na base de dados (AES-256-CBC, chave derivada da chave de cifragem da sua loja) e nunca são devolvidas ao navegador em claro.
## Importação por lotes e retoma
As importações manuais são feitas por lotes sucessivos em AJAX, com uma barra de progresso e contadores em tempo real (OK / erros / total). Depois de cada lote, a posição exata é memorizada: um ficheiro de várias dezenas de milhares de linhas importa-se sem provocar timeout PHP, mesmo num alojamento partilhado. Em modo cron, o processamento encadeia-se de forma síncrona até à última linha.
## Exportação
Crie um perfil de exportação escolhendo a entidade (produtos, categorias, clientes, encomendas), o formato (CSV ou XML) e os campos a incluir. O ficheiro gerado é proposto para descarregamento imediato e/ou depositado automaticamente no destino remoto configurado. As exportações são geradas por lotes para se manterem eficientes em grandes volumes.
## Agendamento (cron)
Para automatizar um perfil, ative o seu agendamento (etapa 4) e chame depois o URL de cron do módulo a intervalos regulares. A cada chamada, só os perfis cuja frequência venceu são executados.
```
*/15 * * * * curl -s "https://a-sua-loja.pt/index.php?fc=module&module=dfcsvpro&controller=cron&token=O_SEU_TOKEN" > /dev/null
```
O URL exato e o token encontram-se no separador **Scheduling / Cron** do módulo, com um botão para regenerar o token. Dois parâmetros facultativos:
- `&id_profile=N`: só executa o perfil indicado.
- `&force=1`: ignora a verificação de frequência e lança o perfil imediatamente.
A loja deve estar acessível para que o cron funcione: o modo de manutenção bloqueia os controladores front, incluindo este endpoint.
## Registos e alertas por e-mail
Cada execução é registada com o seu estado, os seus contadores e o detalhe dos erros linha a linha (as 200 primeiras). O separador **Logs** lista o histórico e permite consultar os erros de uma importação. Assim que uma importação falha ou contém linhas com erro, é enviado automaticamente um alerta por e-mail (modelo FR ou EN) para o endereço configurado nas definições.
## Definições
No separador **Definições**, ative ou desative os alertas por e-mail, defina o endereço destinatário, o tamanho do lote por defeito e a duração de retenção dos registos (os logs mais antigos são purgados automaticamente). Os ficheiros temporários de importação/exportação são limpos depois de 48 horas.
## Formato XML
Na importação XML, o nó de item repetido é detetado automaticamente (ou precisado no perfil). Os itens são aplanados: os elementos aninhados tornam-se colunas `pai/filho`, os atributos tornam-se `@atributo`, e os elementos repetidos recebem o sufixo `nome#1`, `nome#2`. Mapeia depois essas colunas aplanadas como para um CSV.
## Compatibilidade e notas técnicas
- Compatível com PrestaShop 8.0 a 9.x, PHP 7.4 a 8.3, multiloja.
- CSV: deteção automática do delimitador, gestão do BOM, conversão das codificações ISO-8859-1 e Windows-1252.
- Clientes importados com palavra-passe em hash bcrypt e associados a um grupo por nome.
- Nenhum override do núcleo; o AJAX legacy usa as convenções PS9.
## Resolução de problemas
**A interface do módulo fica vazia ou as listas pendentes não se preenchem.** Limpe a cache do PrestaShop e force o recarregamento do navegador (Ctrl+Shift+R). Se estiver ativo um gestor de cache/CCC, regenere os assets.
**O SFTP falha.** Verifique que a extensão PHP `ssh2` está instalada no servidor; caso contrário, use FTP ou um URL.
**O cron não dispara.** Verifique o token, que a loja não está em manutenção, e que o perfil tem um agendamento ativado e uma fonte automática (os perfis em carregamento manual não podem ser agendados).
**Há linhas com erro.** Abra o detalhe do log: cada erro indica o número da linha e a causa (coluna-chave em falta, valor inválido, etc.).