Conectar a sua loja Adobe Commerce

O módulo Bruxel_Sync mantém o seu catálogo do Adobe Commerce e o seu conteúdo do Bruxel alinhados: a loja envia os produtos, o Bruxel devolve as descrições.

Este tutorial tem vídeo em outros idiomas: em espanhol · em inglês

Como funciona

Instala-se um módulo na sua loja. É ele que chama o Bruxel; o Bruxel nunca entra no seu Magento. Duas coisas circulam, cada uma num sentido:

Da sua loja para o Bruxel: os produtos — SKU, nome, categoria e os atributos que você escolher. É a matéria-prima para gerar.
Do Bruxel para a sua loja: o conteúdo já publicado, escrito na ficha do produto, na visão de loja que corresponde a cada idioma.

A sua loja é a dona do catálogo. O que ela envia (nome, marca, categoria, atributos) sobrescreve o que houver no Bruxel; se você editar esses campos no Bruxel, o próximo envio da loja os sobrescreve. O que o Bruxel envia é o conteúdo gerado, e nada mais.

O que é preciso

Adobe Commerce ou Magento Open Source 2.4.7, 2.4.8 ou 2.4.9 — Cloud PaaS ou servidor próprio.
Uma chave de API do Bruxel (Conta → Chaves de API) com permissões de catálogo, atributos e exportação. Cria-se com papel de admin ou proprietário.
Alguém com acesso técnico à loja: o módulo instala-se com Composer e configura-se no painel de administração do Magento.
Os idiomas que o Bruxel sincroniza são espanhol, inglês, francês e português.

Os quatro passos de configuração

Tudo acontece no painel do Magento, em Stores → Configuration → Bruxel → Sincronização. O módulo instala-se desligado: nada se move até você habilitá-lo.

Cole a chave de API. O botão «Testar conexão» confirma que ela responde e diz a que conta está acessando.
Mapeie cada idioma para as suas visões de loja. Um idioma sem visões mapeadas simplesmente não é escrito: não é um erro, é uma decisão.
Escolha quais atributos do seu catálogo viajam para o Bruxel como contexto para gerar.
Mapeie os campos de conteúdo: qual campo do Bruxel se escreve em qual atributo do Magento. Os nomes dos campos são os da sua própria configuração de geração.

O aviso em tempo real

Para que a loja fique sabendo no momento em que você publica conteúdo, registra-se um webhook no Bruxel (Conta → Webhooks) apontando para o endereço do módulo, assinado no aviso de descrição atualizada. Esse registro é manual nesta versão.

Registre-o DEPOIS de habilitar o módulo e colar o segredo, não antes: se o endpoint falhar várias vezes seguidas, o Bruxel o desativa sozinho, e a reativação é feita aqui. Mesmo que o webhook falhe, o conteúdo chega igual: o módulo verifica por conta própria a cada hora.

O primeiro sync, sem sustos

A primeira vez que o Bruxel escreve num catálogo que já tem descrições é o momento delicado. O módulo vem com dois freios puxados:

Um modo de teste que mostra exatamente o que mudaria — produto, campo, visão de loja, valor atual e novo — sem escrever nada.
Uma opção ligada por padrão que NÃO sobrescreve os campos que já têm texto e que o Bruxel nunca tocou. Desliga-se quando você já revisou o diff e decidiu.

Além disso, antes de escrever um campo pela primeira vez, o módulo guarda o valor que havia. Há um comando de restauração que o devolve, exatamente como estava.

Quais produtos viajam

Os que estão habilitados e visíveis no catálogo. Com isso ficam de fora, de propósito, as variações ocultas de um produto configurável: gerar conteúdo para elas gastaria créditos em fichas que a sua loja não mostra. O configurável pai viaja, e uma variação que seja visível por si só também viaja, indicando qual é o seu pai.

O que escreve na sua loja, e o que não

Escreve apenas os atributos que você mapeou, e só se forem de texto e o seu escopo for «visão de loja» — um atributo global não pode ter um valor por idioma.
Nunca escreve a URL do produto. Mudá-la daqui deixaria o endereço anterior sem redirecionamento, e essa é uma forma silenciosa de perder tráfego.
Nunca apaga. Um campo que chega vazio, um produto sem conteúdo publicado ou despublicado no Bruxel deixam a sua ficha como está.

Cada escrita invalida o cache daquela ficha. Por isso o módulo escreve em lotes e só o que realmente mudou; e antes de um primeiro sync grande convém pôr os indexadores em «Update on Schedule».

O que esta versão não cobre

Lojas com vários sites: o módulo escreve por visão de loja, então esse mapeamento precisa de uma revisão manual.
Adobe Commerce as a Cloud Service (a versão SaaS).
As imagens não viajam para a loja.

Se você usa Content Staging, uma campanha programada que se aplica sobrescreve o que o Bruxel escreveu, sem avisar. Publique de novo a partir do Bruxel depois de aplicar campanhas.

Quando algo não bate

O módulo traz duas telas de diagnóstico no Magento, em System, e o seu próprio arquivo de registro. Quase tudo se explica ali:

O que você vê	O que costuma ser	O que fazer
Não chega nada ao Bruxel	O módulo está desabilitado, ou o cron do Magento não roda	Verifique a chave-interruptor e se o cron está ativo
A fila enche e nada avança	A chave deixou de funcionar e o módulo se pausou sozinho	Corrija a chave, teste-a e retome com o comando da fila
Uma linha falha e as demais seguem	Esse idioma não tem visões de loja mapeadas	Mapeie-o, ou ignore-o se você não vende nesse idioma
Todas as linhas falham com o mesmo erro	O mapeamento de campos tem um atributo que não existe, não é de texto ou não é por visão de loja	A mensagem diz qual linha e o que mudar
O conteúdo chega mas não aparece na loja	Falta reindexar ou limpar o cache	Espere o cron dos indexadores ou rode-o à mão
Pararam de chegar avisos há dias	O Bruxel desativou o webhook após várias falhas	Reative-o em Conta → Webhooks; o módulo avisa na tela de fila dele