Instalação
Requisitos
Magento 2.4.x — testado na 2.4.9, compatível com versões 2.4.* anteriores. PHP 8.1–8.5. Compatível tanto com o tema Luma padrão quanto com o tema Hyvä.
Passos de configuração
- Adicione as credenciais recebidas por e-mail ao
auth.jsonna raiz do projeto Magento:{ "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } } composer config repositories.codingrow composer https://repo.codingrow.comcomposer require codingrow/module-mmisbin/magento module:enable Codingrow_Mmisbin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush- Cole a chave de licença em Admin → Stores → Configuration → Codingrow Extensions → MMIS → License → License Key, salve e depois
bin/magento cache:flush.
Toda a interface de administração — cada rótulo, dica e guia — está disponível em 7 idiomas, selecionados automaticamente por usuário admin:
Configuração admin
As definições partilhadas entre perfis estão em Stores → Configuration → Codingrow Extensions → MMIS (Global Settings): módulo on/off, visibilidade do menu, fila de imagens/watchdog partilhados. Cada perfil de importação tem os seus próprios separadores Definições / Mapeamento / Notificações / Log na lista de perfis MMIS.
Desinstalação
composer remove codingrow/module-mmis depois
bin/magento setup:upgrade && bin/magento setup:di:compile && bin/magento cache:flush.
Os produtos já importados nunca são tocados automaticamente — use antes a
ferramenta de rollback se quiser removê-los também.
Guia do usuário
Perfis de importação
Cada fornecedor/feed do qual você importa é um Perfil à parte: feed próprio, mapeamento próprio, agendamento próprio, configurações próprias — completamente independente de qualquer outro perfil. Você pode executar quantos perfis tiver de fornecedores, em paralelo, no mesmo catálogo, e cada um toca apenas os produtos que ele mesmo criou (nunca um produto criado manualmente por um operador, mesmo que compartilhe o mesmo prefixo de SKU).
Origem e formato do feed
Um perfil lê seu próprio feed a partir de uma de três origens:
| Origem | O que você configura |
|---|---|
| URL (padrão) | Um link HTTP/HTTPS direto. Suporta de forma transparente feeds compactados .zip (detectados pela assinatura do arquivo, não pela extensão). |
| Sistema de arquivos do Magento | Um caminho dentro da instalação do Magento (ex. var/import/feed.csv) — útil se o fornecedor deposita arquivos via SFTP em uma pasta que você controla. |
| Servidor FTP | Host + usuário + senha (salva criptografada) — o módulo se conecta e baixa o arquivo sozinho. |
São suportados três formatos de feed: CSV (delimitador configurável: vírgula, ponto e vírgula ou tab), XML (você indica qual elemento repetido representa um produto) e JSON (array de objetos).
https://codingrow.com/sample-feed.csvOpenAPI:
https://codingrow.com/sample-api.openapi.yamlMapeamento das colunas
Seis campos são sempre obrigatórios (Nome do produto, Preço, Quantidade/Estoque, Peso, EAN, Marca) — cada um tem sua própria linha com coluna de origem, valor padrão e transformação. Além desses seis, você pode adicionar quantas linhas de mapeamento livres quiser, para qualquer atributo real do Magento (não apenas uma lista fixa de campos históricos) — incluindo atributos personalizados criados por você.
preco_base
para o preço e peso_kg para o peso: mapeie "Preço" → coluna de origem
preco_base, "Peso" → coluna de origem peso_kg. O nome da
coluna nunca importa, importa apenas para qual coluna cada linha aponta.
Transformações e funções de texto
Cada linha de mapeamento tem um tipo de "Transformação":
| Transformação | O que faz |
|---|---|
| Nenhuma | Cópia direta do valor da coluna de origem. |
| Valor estático | Ignora a coluna de origem, sempre usa o texto fixo digitado em "Valor". |
| Template de texto | Texto livre com placeholder {NomeColuna} — veja as funções abaixo. |
| Buscar e substituir | Busca sem diferenciar maiúsculas/minúsculas no valor da coluna de origem, substituído pelo seu texto (exatamente como digitado). |
| Strip HTML tags | Remove as tags HTML e decodifica as entidades do valor da coluna de origem. Somente para atributos de texto. |
| Fórmula matemática | Uma expressão independente — veja Fórmulas matemáticas mais abaixo. |
Dentro de um Template de texto, além do simples placeholder {NomeColuna},
oito funções estão disponíveis (somente para campos de texto):
| Função | Efeito | Exemplo |
|---|---|---|
ucase{Coluna} | TUDO MAIÚSCULO | ucase{Marca} → "ACME" |
lcase{Coluna} | tudo minúsculo | lcase{Marca} → "acme" |
proper{Coluna} | Inicial Maiúscula Em Cada Palavra | proper{nome} → "barra vermelha" → "Barra Vermelha" |
trim{Coluna} | Remove espaços no início/fim | — |
left{Coluna,N} | Primeiros N caracteres | left{SKU,5} |
val{Coluna} | Normaliza um número em formato europeu ("1.234,56") para o formato padrão ("1234.56"), sem arredondar as casas decimais | — |
replace{Coluna,'buscar','novo'} | Busca/substitui somente dentro daquele valor (busca sem diferenciar maiúsculas/minúsculas), utilizável dentro de um template maior | replace{nome,'Ref.','Referência'} |
striphtml{Coluna} | Remove as tags HTML e decodifica as entidades daquele valor, utilizável dentro de um template maior | striphtml{descricao} |
{ucase{Marca}} - {proper{nome}}
em uma linha onde Marca="acme" e nome="barra vermelha" produz "ACME - Barra
Vermelha". Um nome de função escrito errado permanece visível, inalterado,
na saída em vez de desaparecer silenciosamente, então um erro de digitação sempre é percebido.
Fórmulas matemáticas
Somente para campos numéricos (Preço, Peso, Quantidade, ou um atributo personalizado
numérico): uma expressão independente com placeholder {NomeColuna}, os
quatro operadores básicos (+ - * /) e parênteses — nada mais (nenhuma
função, nenhuma comparação). O resultado é sempre arredondado para no máximo 2 casas decimais.
{Preço B2B} * 1.30
aplica uma margem de 30% sobre o preço de atacado do fornecedor.
({preco} + {custo_envio}) / 1.22 soma o frete e depois remove 22% de
IVA para obter um preço líquido.
Substituição de texto em múltiplos campos
Uma regra de buscar-e-substituir que pode atuar em várias colunas brutas do feed ao mesmo tempo, executada antes mesmo de o mapeamento começar. Limpar uma coluna na origem se propaga para toda linha de mapeamento que a lê — em vez de repetir a mesma correção em cada campo derivado separadamente.
Filtros de importação (Grupos/Regras)
Cada linha do feed passa por três filtros, sempre nesta ordem — um filtro seguinte vê apenas as linhas que sobreviveram ao anterior:
- Categorias de feed permitidas — sempre em primeiro lugar. Uma categoria fora da lista descarta a linha aqui, antes mesmo de um Grupo ser considerado.
- Grupos/Regras — opcional. Se nenhum Grupo estiver configurado, toda linha que sobreviveu ao passo 1 passa inalterada. Se existir ao menos um Grupo, passam somente as linhas capturadas por um Grupo — as linhas não capturadas por nenhum Grupo são descartadas (diferente de "nenhum filtro").
- Categoria de destino do Grupo — se definida dentro do Grupo que capturou a linha, substitui inteiramente o caminho de categoria; se deixada em branco, usa-se o caminho de categoria do feed como está.
Categorias
A árvore de categorias é criada automaticamente a partir do caminho de categoria de cada produto no feed — não é preciso pré-criar as categorias no Magento. A configuração "Categoria pai" permite aninhar toda a árvore de categorias de um perfil sob uma raiz compartilhada, útil quando vários perfis compartilham o mesmo catálogo e você quer manter suas árvores de categorias visualmente separadas. Categorias que ficam vazias (ex. depois que um fornecedor descontinua uma linha de produtos inteira) são limpas com um clique ou pela CLI.
Galeria de imagens
Mapeie qualquer número de colunas do feed para os papéis de imagem (base / small / thumbnail / gallery) — uma única coluna pode servir a vários papéis ao mesmo tempo. As imagens baixadas são opcionalmente comprimidas (redimensionadas se mais largas que 1200px, recomprimidas em JPEG qualidade 85, mantidas apenas se o resultado for de fato mais leve) com concorrência configurável e um watchdog de espaço em disco que suspende os downloads — nunca os dados do produto — se o espaço livre estiver escasso.
Produtos configurable (variantes)
As linhas do feed que compartilham o mesmo valor em uma "coluna de grupo/pai" se tornam variantes de um único produto configurable. Qualquer número de atributos pode variar ao mesmo tempo — tamanho, cor e um terceiro atributo juntos, por exemplo — bastando que cada um tenha sua própria linha de mapeamento com uma coluna que dá um valor diferente para cada variante.
Produtos grouped
Conceitualmente diferente do configurable: nenhum atributo de variante, nenhuma coluna de grupo — apenas uma ligação direta entre um "contêiner" pai e qualquer número de produtos simples que permanecem completamente independentes (preço, estoque e página navegável próprios), útil quando um fornecedor vende tanto os componentes individuais separadamente quanto um kit que os mostra juntos com um seletor de quantidade para cada um.
Gestão de estoque
As atualizações de estoque podem ser absolutas (substituem o valor) ou relativas (somam/subtraem em relação à quantidade atual) — útil para fornecedores cujo feed reporta variações em vez de totais. Backorder e "gerenciar estoque" seguem a configuração do perfil, não uma única configuração global.
Pré-visualização e arquivo de saída
Duas formas de ver o que uma sincronização realmente escreveria no catálogo — apenas os campos mapeados, nunca os filtros de categoria/vendabilidade/Grupo (a amostra é parcial de propósito):
| Pré-visualização | Reflete os valores atuais do formulário, mesmo não salvos — clique nela enquanto edita para ver o efeito na hora, sem tocar no perfil. |
|---|---|
| Baixar arquivo de saída | Usa a última configuração salva e gera um arquivo JSON para download. |
Agendamento e notificações
Cada perfil tem seu próprio agendamento cron (de 15 em 15 minutos até uma vez por dia, ou uma expressão cron personalizada) tanto para a sincronização completa do catálogo quanto para uma mais leve, somente de estoque/preços. As notificações por e-mail (sucesso/atenção/erro crítico) são configuradas por perfil, para que fornecedores diferentes possam ter políticas de alerta diferentes na mesma loja.
Ciclo de vida do produto: nada desaparece de surpresa
Um produto que some do feed, ou é excluído por um filtro, é sempre desativado primeiro — nunca excluído — e se reativa sozinho automaticamente se reaparecer em uma sincronização posterior. A exclusão definitiva é uma configuração separada, opcional (desativada por padrão): somente um produto que permaneceu desativado por mais de um número configurável de dias é de fato excluído, e somente então.
Comandos CLI
Cada ação também está disponível pela linha de comando (útil para cron, ou para uma primeira importação muito grande via SSH): executar a sincronização de um perfil, exportar/importar a configuração de um perfil, desfazer tudo o que um perfil já importou, limpar categorias órfãs e mais — cada um com uma pré-visualização dry-run por padrão quando é destrutivo.