Integrar o Bluestone PIM com o BigCommerce é fazer com que o conteúdo de produto, que nasce e é revisto no PIM, chegue ao catálogo da loja de forma controlada e repetível. Segundo a página de produto da Bluestone, os conectores de comércio nomeados são o commercetools, o Adobe Commerce e o Shopify; o BigCommerce não aparece na lista. Na prática, a ligação constrói-se sobre as APIs dos dois sistemas, diretamente ou através de uma ferramenta de integração.
Para o negócio, o que está em causa é saber quem manda em cada dado. Se descrições, atributos e imagens forem editados em dois sítios, a loja acaba com versões diferentes do mesmo produto e cada correção dá trabalho duplicado. Tratamos este tema na nossa área de integração de PIM com ecommerce, onde o ponto de partida é sempre o mesmo: uma fonte única para o conteúdo.
Neste artigo vê o que cada plataforma permite, como desenhar o fluxo, que dados vão em cada sentido, que limites técnicos pesam, uma matriz para escolher a forma de ligação e uma lista de verificação antes de começar.
O que permite cada plataforma antes de desenhar a ligação?
A Bluestone oferece duas APIs com papéis diferentes e o BigCommerce tem uma API de catálogo própria; o desenho parte destes três contratos. Segundo o centro de ajuda da Bluestone, a Public API é só de leitura, foi pensada para servir grandes volumes de dados a muitos sistemas externos e só devolve conteúdo que já tenha sido publicado a partir do PIM. A Management API usa OAuth2, as credenciais pedem-se ao suporte da Bluestone e dão acesso alargado aos dados e operações do PIM, pelo que devem ser tratadas como muito sensíveis.
Do lado do BigCommerce, a API de catálogo v3 permite criar e atualizar produtos, variantes, imagens e campos personalizados. A documentação oficial indica que a atualização de produtos em lote está limitada a 10 produtos por pedido e que cada objeto tem de incluir o identificador do produto.
| API | Característica | Papel na ligação |
|---|---|---|
| Bluestone Public API | Só leitura, conteúdo publicado | Fonte do conteúdo de produto |
| Bluestone Management API | OAuth2, acesso alargado | Só se for mesmo necessário |
| BigCommerce Catalog v3 | Escrita, lotes de 10 produtos | Destino do catálogo |
Daqui sai uma regra simples: a integração lê da Public API, que é segura por ser só de leitura, e escreve na API de catálogo do BigCommerce. Usar a Management API para alimentar uma loja aumenta o risco sem trazer vantagem.
Como se desenha o fluxo do Bluestone PIM para o BigCommerce?
O fluxo mais robusto é incremental: a camada de integração pergunta à Bluestone o que mudou e só envia ao BigCommerce essas diferenças. A ajuda da Bluestone descreve este padrão: consultar o endpoint de sincronizações com o parâmetro createdAfter, ou usar webhooks para saber quando uma sincronização termina, e depois pedir os endpoints de diferenças, que listam produtos, categorias, atributos e relações novos, atualizados ou removidos para um dado identificador de sincronização.
- Publicar no PIM o conteúdo que deve seguir para a loja, porque a Public API só serve conteúdo publicado.
- Detetar a sincronização nova, por consulta periódica ou por webhook.
- Pedir as diferenças dessa sincronização.
- Obter o detalhe dos produtos alterados, no contexto certo (na Bluestone, os contextos correspondem normalmente às línguas).
- Converter para o modelo do BigCommerce: produto, variantes, categorias, campos personalizados e imagens.
- Enviar em lotes de até 10 produtos e registar o resultado de cada lote.
- Guardar a correspondência entre o identificador do PIM e o do BigCommerce, para atualizar em vez de duplicar.
A ajuda da Bluestone indica ainda que a Public API segue o padrão de leitor tolerante: não tem um esquema JSON rígido, porque o modelo de dados vai crescendo, e podem surgir campos novos sem aviso. O código da integração deve ignorar o que não conhece em vez de falhar.
Que dados devem ir em cada sentido?
O conteúdo segue do PIM para a loja; encomendas e stock não passam pelo PIM. A tabela resume uma divisão que usamos como ponto de partida e que deve ser validada em cada projeto.
| Dado | Sistema mestre | Sentido |
|---|---|---|
| Nome, descrição e atributos | Bluestone | PIM para loja |
| Imagens e outros media | Bluestone | PIM para loja |
| Variantes e opções | Bluestone | PIM para loja |
| Categorias | A definir no projeto | Acordar antes |
| Preço | ERP ou loja | Fora do PIM |
| Stock | ERP | ERP para loja |
| Encomendas | BigCommerce | Loja para ERP |
Os tipos de produto da Bluestone (simples, grupo, variante e pacote) têm de ser mapeados com regras explícitas para o modelo do BigCommerce, que trabalha com produtos e variantes. Convém decidir esse mapeamento por escrito antes de qualquer desenvolvimento, porque é aqui que nascem os produtos duplicados e as variantes órfãs.
Preço e stock são uma decisão de projeto. Se vivem no ERP, o PIM não deve sobrepor-se; se a empresa gere preços no PIM, a integração tem de o assumir e a regra deve ficar documentada.
Que limites técnicos condicionam a integração?
Os limites mais frequentes estão no BigCommerce e obrigam a desenhar a integração para lotes pequenos e repetições controladas. Os pontos a ter em conta são estes:
- Os lotes de atualização de produtos têm um máximo de 10 produtos, pelo que um catálogo grande exige muitos pedidos e uma fila.
- Quando o cliente OAuth excede o limite de pedidos, o BigCommerce responde com o código 429 e cabeçalhos como X-Rate-Limit-Requests-Left e X-Retry-After, que a integração deve respeitar.
- Os códigos 409, 413 e 422 indicam conflito, pedido demasiado grande e dados que não passam a validação; cada um pede tratamento próprio.
- O código 507 pode surgir quando se atinge um limite de recursos do plano da loja.
- Do lado da Bluestone, árvores de categorias grandes devem ser lidas em vários pedidos, e cada pedido deve indicar o contexto (língua) pretendido.
Nada disto impede a integração, mas explica porque é que uma exportação única e uma sincronização contínua são projetos diferentes. A segunda precisa de fila, registo de erros e política de repetição.
Ligação por medida, ferramenta de integração ou ficheiros?
Depende da frequência de alteração, do número de línguas e do número de sistemas envolvidos. A matriz seguinte é a que usamos para a primeira conversa.
| Opção | Quando serve | Esforço | Risco principal |
|---|---|---|---|
| API por medida | Catálogo grande, regras próprias | Alto | Manutenção contínua |
| Plataforma de integração | Vários sistemas ligados | Médio | Custo de licença |
| Importação por ficheiro | Catálogo pequeno e estável | Baixo | Erro manual |
A Bluestone refere importação e exportação por Excel, CSV e API, pelo que a via de ficheiros existe, mas deixa de compensar quando as alterações são diárias ou quando há várias línguas. Nesses casos, a ligação por API com sincronização incremental evita retrabalho.
Lista de verificação antes de arrancar o projeto
- Confirmar com a Bluestone se existe conector para o BigCommerce no seu contrato, em vez de assumir que existe.
- Definir o sistema mestre de cada dado: conteúdo, preço, stock, categorias e imagens.
- Escrever o mapeamento entre tipos de produto da Bluestone e produtos e variantes do BigCommerce.
- Decidir que línguas e contextos seguem para a loja.
- Garantir que o conteúdo é publicado no PIM antes de ser lido pela Public API.
- Prever fila, limite de 10 produtos por lote e tratamento dos códigos 429, 409, 413 e 422.
- Guardar a correspondência de identificadores entre PIM e loja.
- Testar com um subconjunto de produtos, incluindo casos com variantes, e só depois alargar.
- Definir quem recebe os alertas quando um lote falha.
Como trabalhamos na Avafa
Começamos por mapear dados e responsáveis, e só depois escolhemos a forma de ligação. Revemos o modelo de produto da Bluestone e o catálogo do BigCommerce lado a lado, escrevemos as regras de mapeamento e testamos com um grupo pequeno de produtos antes de alargar. Se quiser ver como abordamos este tipo de projetos, comece pela página de integração de PIM com ecommerce.
Guias relacionados do mesmo cluster
Se a plataforma de destino ainda não está decidida, estes guias comparam o mesmo tipo de projeto com outras opções:
- Bluestone PIM com Adobe Commerce
- Bluestone PIM com Magento
- Bluestone PIM com Salesforce Commerce Cloud
- Plytix com BigCommerce
- Pimcore com BigCommerce
Perguntas frequentes
O Bluestone PIM tem conector oficial para o BigCommerce?
Na página de produto da Bluestone, os conectores de comércio nomeados são o commercetools, o Adobe Commerce e o Shopify. O BigCommerce não é mencionado, por isso a ligação deve ser confirmada com a Bluestone e, se não existir, construída sobre as APIs.
Posso escrever no Bluestone PIM a partir do BigCommerce?
A Public API é só de leitura. Escrever no PIM exigiria a Management API, cujas credenciais se pedem ao suporte da Bluestone. Em geral, o conteúdo deve fluir do PIM para a loja, e não ao contrário.
Quantos produtos posso atualizar de cada vez no BigCommerce?
Segundo a documentação oficial, a atualização de produtos em lote está limitada a 10 produtos por pedido. Um catálogo grande implica, por isso, muitos pedidos organizados numa fila.
A sincronização pode ser feita em tempo real?
A ajuda da Bluestone prevê consulta de sincronizações e webhooks para saber quando uma sincronização termina. Isso permite reagir rapidamente, mas o ritmo final depende dos limites de pedidos do BigCommerce e da fila da integração.
Quanto tempo demora um projeto destes?
Depende do número de atributos, variantes e línguas e da qualidade dos dados no PIM. O que mais atrasa não é o código, é a decisão de mapeamento; por isso a primeira fase é sempre o desenho e o teste com poucos produtos.