Integrar Bluestone PIM com Adobe Commerce: extensão ou API

Integrar o Bluestone PIM com o Adobe Commerce é ligar o sítio onde o conteúdo de produto é trabalhado ao catálogo da loja, por uma de duas vias: a extensão da Bluestone publicada no Adobe Commerce Marketplace ou uma integração por API. A Bluestone nomeia o Adobe Commerce, através da Vaimo, entre os conectores de comércio da sua página de produto, o que faz desta uma das ligações mais bem documentadas da plataforma.

Para uma empresa com catálogo grande, a escolha entre extensão e API decide o custo de manutenção dos próximos anos, sobretudo se o projeto for headless ou composable, isto é, se o frontend e o catálogo forem peças separadas. Tratamos estas decisões na nossa área de integração de PIM com ecommerce.

Neste artigo vê o que a extensão sincroniza e o que deixou de sincronizar, quando a API é melhor, como funciona a Bulk API do Adobe Commerce, um desenho headless possível e uma lista de verificação.

O que sincroniza a extensão da Bluestone para o Adobe Commerce?

A extensão Bluestone PIM Sync Product Data exporta conteúdo de produto do PIM para o Adobe Commerce e para o Magento Open Source. Segundo a ficha no Marketplace, na versão 3.0.6 o conteúdo sincronizado inclui descrições, media, traduções e relações de produto (relacionados, up-sell e cross-sell), além de produtos agrupados em variantes, pacotes e criação de variantes. Os tipos de atributo suportados incluem booleano, texto formatado, data, seleção simples e múltipla, inteiro e decimal.

A ficha indica também que é possível escolher o atributo do PIM usado como SKU, definir campos de correspondência e acompanhar as atualizações num painel com histórico de sincronizações. A extensão é gratuita, mas exige uma conta ativa na Bluestone PIM, com custos próprios.

Há dois limites a conhecer. O registo de versões indica que a sincronização de preços foi removida na versão 3.0.0, pelo que o preço tem de vir de outra fonte. E a ficha refere que a sincronização do atributo de descrição foi desativada numa versão anterior (1.7.3) sem esclarecer se voltou, algo a confirmar em teste antes de prometer ao negócio.

Quando é melhor usar a API em vez da extensão?

A API compensa quando o modelo de dados, os fluxos ou a arquitetura saem do que a extensão cobre. Os casos mais comuns são estes:

• O frontend é headless e lê o conteúdo diretamente do PIM, em vez de o copiar para a loja.
• Há regras de transformação que a extensão não faz, como juntar atributos ou aplicar regras por canal.
• O catálogo passa por outros sistemas, como um ERP, e a Adobe Commerce é só um dos destinos.
• É preciso controlar a frequência, a fila e os alertas de erro com mais detalhe do que o painel da extensão oferece.

Segundo a ajuda oficial da Bluestone, a Public API é só de leitura, serve grandes volumes de dados a muitos sistemas e só expõe conteúdo publicado. Tem endpoints de produtos, categorias, sincronizações e diferenças, o que permite um fluxo incremental: perguntar o que mudou desde a última sincronização e tratar só isso.

Como funciona a Bulk API do Adobe Commerce?

A Bulk API recebe um array de pedidos e coloca cada item numa fila de mensagens, em vez de os processar na hora. Segundo a documentação da Adobe, em instalações PaaS o prefixo /async/bulk vem antes de /V1, por exemplo em POST /rest/código-da-vista/async/bulk/V1/products, e a resposta inclui um bulk_uuid e o estado de cada item.

O ponto crítico está no estado: um item aceite não é um item processado com sucesso. A própria documentação refere que um pedido pode ser aceite e falhar depois, ao ser processado. A integração tem de verificar o resultado e não pode dar o lote por concluído ao receber a resposta.

• É preciso um broker de mensagens configurado; a documentação indica o RabbitMQ como predefinição.
• Em PaaS, os consumidores de filas arrancam normalmente por cron; arrancá-los à mão, com a linha de comandos, não é recomendado.
• Pedidos GET não são suportados nos endpoints em massa.
• Em SaaS, o máximo de entidades por pedido depende de uma definição da configuração da loja.

Como desenhar uma arquitetura headless ou composable com a Bluestone?

Num desenho headless, o conteúdo rico vem do PIM e o Adobe Commerce fica com o que é transacional. Esta divisão é uma proposta nossa, coerente com o que a documentação descreve: a Public API foi feita para servir muitos sistemas externos, e a loja trata de preço, stock, carrinho e encomendas.

O risco de um desenho destes é a dependência de duas fontes em cada página. Convém definir o que acontece quando o PIM não responde: mostrar a última versão guardada em cache é, em geral, melhor do que mostrar uma página sem conteúdo.

Como se mantém a sincronização depois de arrancar?

Depois do arranque, o trabalho passa a ser vigiar a qualidade do conteúdo e as falhas, não escrever código novo. A extensão regista o histórico de sincronizações no painel, o que ajuda a perceber o que foi enviado e quando, mas não substitui uma rotina de controlo.

• Rever o histórico de sincronizações com regularidade e investigar os produtos que falham.
• Comparar uma amostra de produtos entre o PIM e a loja, em texto, imagens e relações.
• Acompanhar as atualizações da extensão e testá-las num ambiente de teste antes de produção.
• Documentar quem pode alterar o mapeamento de atributos e como se regista essa alteração.

Quando a integração é por API, a mesma disciplina aplica-se a registos próprios: cada pedido, cada resposta e cada repetição devem ficar guardados, para que um erro de dados se explique em minutos e não em dias.

Lista de verificação antes de arrancar o projeto

1. Confirmar a versão do Adobe Commerce e a compatibilidade da versão da extensão, porque as notas da ficha não são uniformes.
2. Decidir se a extensão chega ou se o projeto exige API.
3. Definir de onde vem o preço, já que a extensão deixou de o sincronizar.
4. Escolher o atributo do PIM que serve de SKU e confirmar que é único.
5. Testar o atributo de descrição e as traduções com produtos reais.
6. Se usar a Bulk API, confirmar RabbitMQ e consumidores ativos, e verificar o estado de cada item.
7. Decidir a política de cache se o frontend ler diretamente do PIM.
8. Começar por um subconjunto de produtos com variantes e pacotes.
9. Definir quem recebe os alertas de falha.

Como trabalhamos na Avafa

Começamos por perceber se a extensão cobre o caso ou se a arquitetura pede API, e só depois fixamos o desenho. Escrevemos o mapeamento de atributos e definimos o sistema mestre de cada dado antes de qualquer desenvolvimento. Para ver como abordamos estes projetos, comece pela página de integração de PIM com ecommerce.

Guias relacionados do mesmo cluster

Se ainda está a decidir a plataforma, estes guias cobrem opções próximas:

• Bluestone PIM com Magento
• Bluestone PIM com BigCommerce
• Bluestone PIM com Salesforce Commerce Cloud
• Akeneo com Adobe Commerce
• Plytix com Adobe Commerce

Perguntas frequentes

A Bluestone tem extensão oficial para o Adobe Commerce?

Sim. A extensão Bluestone PIM Sync Product Data está publicada no Adobe Commerce Marketplace. É gratuita, mas exige uma conta ativa na Bluestone PIM, com custos próprios.

A extensão sincroniza preços?

Não nas versões recentes. O registo de versões indica que a sincronização de preços foi removida na versão 3.0.0, por isso o preço deve vir do ERP ou ser gerido na própria loja.

Posso usar a Public API da Bluestone para escrever no PIM?

Não. A Public API é só de leitura. A escrita faz-se pela Management API, com credenciais OAuth2 pedidas ao suporte da Bluestone.

A Bulk API do Adobe Commerce garante que os produtos foram criados?

Não. A resposta confirma que os itens foram aceites na fila, não que foram processados com sucesso. É preciso verificar o estado de cada item depois.

Quanto tempo demora a integração?

Com a extensão, a instalação é rápida e o tempo vai para o mapeamento e os testes. Com API, depende do número de atributos, variantes e línguas. Em ambos os casos, a decisão de mapeamento pesa mais do que o código.