Integrar o Salsify com o BigCommerce é enviar o conteúdo de produto gerido no Salsify para o catálogo da loja BigCommerce, de forma automática e repetível. Na prática, faz-se através da API de catálogo do BigCommerce, alimentada por dados exportados do Salsify. O artigo da Salsify sobre integrações destaca ligações pré-construídas para Shopify e Salesforce Commerce Cloud e, para os restantes sistemas, as suas APIs REST e GraphQL e os webhooks. Por isso, confirme diretamente com a Salsify se existe um conector para o seu caso.
Para a empresa, o ganho está em deixar de editar produtos em dois sítios. Quando o catálogo cresce, as variantes, os campos personalizados e as imagens são onde os erros se acumulam. Na Avafa tratamos estas ligações dentro da nossa área de integração de PIM com ecommerce.
Neste guia vê quando compensa integrar, como se liga por API, que dados vão em cada sentido, que limites e erros esperar do BigCommerce e uma lista de verificação antes de arrancar.
Quando compensa ligar o Salsify ao BigCommerce?
Compensa quando o conteúdo de produto muda com frequência e a edição manual na loja já é o gargalo. Os sinais mais claros são estes:
- os produtos têm muitas variantes e a criação à mão demora e falha;
- há campos personalizados que a equipa preenche produto a produto;
- o mesmo catálogo alimenta mais do que uma loja ou canal;
- o tempo entre aprovar um conteúdo e vê-lo online é longo;
- as importações por ficheiro já não aguentam o volume de referências.
Não compensa, por agora, com poucas dezenas de produtos e alterações raras. Nesse caso, a importação do próprio BigCommerce com um ficheiro bem validado custa menos a manter do que uma ligação por API.
Como se liga o Salsify ao BigCommerce por API?
A ligação usa o Salsify como origem e a API de catálogo do BigCommerce como destino. Segundo a documentação do BigCommerce, a API de produtos permite criar produtos, fazer operações em lote sobre produtos existentes e gerir imagens e vídeos. As variantes de um produto gerem-se depois de o produto existir, através dos pontos de acesso de modificadores, variantes e opções de variante. Os campos personalizados e os metacampos têm pontos de acesso próprios.
Do lado da Salsify, a empresa descreve uma arquitetura orientada a APIs, com REST e GraphQL, e webhooks para ligar fluxos entre sistemas. O fluxo típico segue estes passos:
- Selecionar no Salsify os produtos e atributos a publicar.
- Exportar os dados ou receber um aviso por webhook quando algo muda.
- Transformar os campos do Salsify nos campos do BigCommerce.
- Criar ou atualizar o produto, e só depois as variantes, as imagens e os campos personalizados.
- Registar o resultado de cada produto e repetir apenas os que falharam.
A ordem do passo quatro não é opcional: como as variantes dependem de o produto existir, um fluxo que as envie antes do produto gera erros em cadeia.
Outra decisão de desenho é enviar apenas os produtos que mudaram, em vez de reenviar o catálogo inteiro. Reduz o número de pedidos, deixa menos hipóteses de atingir o limite e facilita saber o que foi alterado em cada carga. Reserve a carga completa para a primeira sincronização e para reparar dados.
Que dados vão em cada sentido?
Decida cedo qual é o sistema mestre de cada dado. Esta é a matriz de partida que usamos:
| Dado | Sistema mestre | Sentido |
|---|---|---|
| Nome, descrição, atributos | Salsify | Salsify para loja |
| Imagens e vídeos | Salsify | Salsify para loja |
| Variantes e opções | Salsify | Salsify para loja |
| Campos personalizados | Salsify | Salsify para loja |
| Categorias e canais | Salsify ou loja | Decidir caso a caso |
| Preço e stock | ERP | ERP para loja |
| Encomendas | BigCommerce | Loja para ERP |
Se a loja tiver vários canais (multi-storefront), a documentação do BigCommerce indica que o produto inclui atribuições a canais e a categorias. Convém decidir se essas atribuições vêm do Salsify ou se são geridas na loja, para uma atualização não desfazer o trabalho da outra.
Que limites e erros esperar do BigCommerce?
Os erros mais comuns vêm de lotes e de limites de pedidos, não do conteúdo. A documentação de tratamento de erros do BigCommerce avisa que um único item inválido pode fazer falhar um pedido em lote inteiro, e que não se deve assumir que o lote inteiro teve sucesso ou falhou. Alguns pontos de acesso em lote não indicam qual o item com erro, e nesse caso é preciso reenviar os itens em pedidos separados.
| Situação | O que significa | O que fazer |
|---|---|---|
| Resposta 429 | Limite de pedidos excedido | Esperar pelo tempo indicado |
| Resposta 422 | Dados inválidos | Corrigir o mapeamento |
| Erros 5xx | Falha temporária | Repetir com espera crescente |
| Item com erro em lote | Lote pode falhar todo | Separar e reenviar |
| Erros ignorados | Perda silenciosa de dados | Rever o registo no fim |
Perante um 429, o BigCommerce recomenda esperar com base nos cabeçalhos X-Rate-Limit-Time-Reset-Ms ou X-Retry-After, usando o tempo mais longo se ambos existirem. Para falhas 5xx temporárias, recomenda repetir com espera crescente. A mesma documentação lembra que registar e ignorar erros pode levar a perda silenciosa de dados, por isso o resumo dos registos ignorados deve ser revisto no fim de cada carga.
Ligação por API, conector ou importação por ficheiro?
A escolha depende do volume, da frequência de alterações e de quem mantém a ligação. A tabela compara as opções:
| Opção | Quando serve | Limitação |
|---|---|---|
| Importação por ficheiro | Catálogo estável, poucas alterações | Manual e sujeita a erro |
| Conector da Salsify | Se existir para o seu caso | Confirmar com a Salsify |
| API à medida | Variantes e regras próprias | Exige desenvolvimento |
| Camada intermédia | Vários sistemas ligados | Custo de manutenção maior |
Em catálogos com muitas variantes, a ligação à medida costuma compensar, desde que inclua registo de erros e alertas. Sem isso, os problemas só aparecem quando um cliente os vê.
Lista de verificação antes de arrancar o projeto
- Confirmar com a Salsify se existe conector para o BigCommerce.
- Decidir o sistema mestre de cada dado e registá-lo numa matriz.
- Fixar o SKU como identificador comum entre Salsify, ERP e loja.
- Definir como se criam e atualizam variantes e opções.
- Decidir quem gere categorias e atribuições a canais.
- Testar com um lote pequeno e conferir produto a produto.
- Implementar espera e repetição para respostas 429 e 5xx.
- Definir quem recebe o alerta e rever os erros ignorados no fim.
Como trabalhamos na Avafa
Começamos por mapear dados e responsáveis, só depois escolhemos a forma de ligação. Revemos o desenho do fluxo, o tratamento de erros e a ordem de criação das variantes antes de qualquer desenvolvimento, para que o projeto não arranque com um conflito de fontes. Se quiser ver como abordamos este tipo de projetos, comece pela página de agência de SEO para BigCommerce e pela de integração de PIM com ecommerce.
Guias relacionados do mesmo cluster
Se o PIM ou a plataforma ainda não estão decididos, estes guias comparam alternativas:
- Akeneo com BigCommerce
- Plytix com BigCommerce
- Bluestone PIM com BigCommerce
- Brandfolder com BigCommerce para alimentar catálogos
- Salsify com Salesforce Commerce Cloud
- Salsify com WooCommerce
Perguntas frequentes
O BigCommerce tem ligação nativa ao Salsify?
A documentação da Salsify que consultámos destaca ligações pré-construídas para Shopify e Salesforce Commerce Cloud. Para o BigCommerce, confirme com a Salsify se existe conector; se não existir, a ligação faz-se por API.
Posso enviar produtos e variantes no mesmo pedido?
Segundo a documentação do BigCommerce, as variantes gerem-se depois de o produto ser criado, através de pontos de acesso próprios. Planeie o fluxo em duas fases.
O que acontece se um item de um lote tiver erro?
Um único item inválido pode fazer falhar o lote inteiro. Processe os itens com sucesso e volte a tentar ou registe os que falharam, sem assumir que o lote todo correu bem.
Como devo reagir a um erro 429?
Espere o tempo indicado nos cabeçalhos de resposta e só depois repita o pedido. Se existirem dois cabeçalhos, use o tempo mais longo.
O Salsify deve gerir o preço e o stock?
Normalmente não. Preço, stock e encomendas pertencem ao ERP e à loja, e o Salsify fica com o conteúdo de produto: textos, atributos, imagens e variantes.