Sincronizar o catálogo com lojas e marketplaces (Sync Studio)

Visão geral

O Sync Studio conecta plataformas externas de e-commerce e marketplaces ao seu catálogo nativo da ConversaLabs. Com ele você define fontes de sincronização que podem:

• Importar (entrada) — trazer os produtos da plataforma externa para o catálogo nativo;
• Publicar (saída) — enviar produtos do catálogo nativo para a plataforma externa;
• Manter as duas vias — combinar importação e publicação na mesma fonte.

O Sync Studio é diferente de outros dois recursos próximos:

• A Sincronização com o WhatsApp Business Catalog (Meta) liga o catálogo nativo ao catálogo da Meta para enviar produtos no WhatsApp — tem artigo próprio.
• O Ciclo de vida de e-commerce trata de eventos de venda (carrinho abandonado, PIX pendente, compra aprovada, reembolso) que viram cards na conversa — também tem artigo próprio.

O Sync Studio cuida do catálogo de produtos: o que está à venda, com nome, preço e imagens.

Pré-requisitos

• Módulo de Catálogo & Comércio habilitado para a sua conta.
• Permissão de administrador para gerenciar fontes de sincronização.
• Uma conta e as credenciais de acesso na plataforma externa (token, chaves de aplicativo ou autorização, conforme o conector).
• Recomendado: catálogo nativo já organizado em categorias antes de publicar produtos para fora.

Passo a passo

1. Na área de Catálogo, abra o Sync Studio (fontes de sincronização) e clique em criar uma nova fonte.
2. Escolha o conector/preset: fonte Genérica, Shopify, WooCommerce, Magento, PrestaShop, Medusa, Mercado Livre, Nuvemshop, Hotmart, Kiwify ou OLX.
3. Defina a direção: Entrada (importar), Saída (publicar) ou Duas vias.
4. Autentique a fonte conforme o conector:
   • Mercado Livre — clique em Autorizar; você é levado à tela de login da plataforma e, ao aprovar, é devolvido ao endereço fixo /catalog_oauth/callback. Os tokens ficam guardados de forma criptografada.
   • Hotmart / Kiwify — informe client_id e client_secret (e account_id no Kiwify). O basic_token da Hotmart é aceito para fontes antigas, mas é derivado automaticamente quando não foi informado. A Kiwify recebe as credenciais em formulário e a plataforma gera o token.
   • Fonte Genérica, Shopify, WooCommerce, Magento, PrestaShop, Medusa — escolha autenticação Bearer, cabeçalho, Basic (usuário e senha) ou parâmetro da URL, e informe o mapeamento.
   • Nuvemshop — cole o token da loja e o store_id.
5. Use Testar conexão para validar Hotmart ou Kiwify já salvos. Para uma fonte Genérica, use a prévia ao vivo antes de salvar: ela faz a mesma chamada da sincronização, mostra a resposta, o formato realmente lido, os campos detectados, sugestões de mapeamento e o primeiro registro mapeado.
6. Salve e clique em Sincronizar agora para rodar a primeira importação (ou Publicar agora para uma fonte de saída).
7. Acompanhe o histórico de execuções paginado e filtrável para ver cada sincronização, com horários no fuso da conta, direção e resultado (itens lidos, criados, atualizados, ignorados ou com falha). A lista de fontes também mostra os contadores seguros e o último erro sem expor credenciais. Você pode exportar o histórico filtrado ou execuções selecionadas explicitamente como CSV; uma exportação parcial mantém visíveis os IDs que não puderam ser exportados.

Configurações & opções

• Conector / preset (source_type) — a plataforma de origem/destino.
• Direção — entrada, saída ou duas vias.
• Credenciais — guardadas criptografadas, nunca exibidas de volta e nunca registradas em log.
• Intervalo de sincronização — de quanto em quanto tempo a fonte é sincronizada automaticamente (além da sincronização manual sob demanda).
• Estado da fonte — uma fonte desabilitada continua editável, mas não aceita webhooks nem executa Sincronizar agora, Publicar agora ou trabalhos de pull, publicação e validação Meta que já estavam na fila. Reabilite-a somente depois de revisar direção, capacidades e credenciais.
• Paginação — catálogos grandes são percorridos por páginas automaticamente (Shopify segue o cabeçalho Link, WooCommerce avança por página); fontes JSON genéricas podem configurar o estilo de paginação. Se uma execução alcançar o limite de segurança de 200 páginas e ainda houver uma próxima página, ela termina como parcial/truncada e preserva o cursor; a execução seguinte retoma desse ponto. O cursor só é limpo quando a leitura chega realmente ao fim.
• Formato e raiz de produtos — a fonte Genérica detecta JSON, NDJSON, XML, CSV ou TSV pela resposta; você pode escolher o formato manualmente. Para XML, a raiz é um XPath (por exemplo, //products/product); nos outros formatos ela usa caminho com pontos.
• Mapeamento sugerido — a prévia sugere, sem salvar sozinha, campos em português, inglês e espanhol, com confiança. Revise antes de aplicar. Além de nome e ID, você pode mapear preço, preço comparativo, moeda, SKU, estoque, marca e URL externa; itens.0.preco seleciona a primeira posição de uma lista.
• Webhook da fonte — cada fonte tem um endereço de webhook próprio (/webhooks/catalog/:account_id/:source_id). Onde a plataforma permite, a ConversaLabs o registra com um clique em Registrar webhook (Nuvemshop, Kiwify); em outras, você cola o endereço no painel da própria plataforma (Hotmart).
• Segredo de sincronização de entrada — usado por clientes da API de sincronização em lote. Ele aparece mascarado na lista. Rotacionar segredo de entrada invalida o anterior imediatamente, registra a operação quando a trilha de auditoria nativa está habilitada e revela o novo valor uma única vez; atualize todos os remetentes.
• Segredo do webhook da plataforma — valor fornecido pela própria plataforma para validar eventos de comércio. Ele é write-only e nunca volta na resposta. Para substituí-lo, cole o novo valor ao editar a fonte e atualize também o painel externo; a ConversaLabs não inventa nem rotaciona esse valor na plataforma.
• Fonte Genérica bidirecional — configure o mapa de evento e os caminhos dos campos na própria tela. A entrada exige X-Webhook-Signature: t=…,v1=…, recusa fonte sem segredo, limita a janela de replay e deduplica o ID de entrega. Uma fonte somente de saída recusa entregas de entrada. Para saída, informe um destino HTTP(S) sem credenciais, parâmetros de consulta ou fragmentos; a autenticação usa o segredo HMAC compartilhado. Os eventos ficam em um histórico pesquisável, com retentativa automática e reenvio manual individual ou em lote. Uma entrega que encontrar a fonte desabilitada, removida, alterada ou sem segredo falha antes de fazer qualquer requisição externa e deixa o motivo no histórico.
• Produto, variação e itens do webhook genérico — os caminhos de produto e variação partem da raiz do evento. Informe primeiro o caminho da lista de itens e depois mapeie os campos relativos a cada item. Campos em branco nunca são deduzidos. Quando mapeados, os valores ficam preservados no pedido do CRM e só são enviados a webhooks de conta que ativaram detalhes de comércio.
• Proteção contra duplicidade e laço — cada item importado guarda o identificador de origem (external_id / retailer_id) e a fonte. Em novas sincronizações isso atualiza o mesmo produto em vez de recriá-lo e impede devolver à origem uma mudança que veio dela.

Importar vendas históricas da Hotmart ou Kiwify

Em uma fonte Hotmart ou Kiwify salva, abra Gerenciamento → Importar vendas. Escolha as duas datas dentro da janela do provedor: até 31 dias corridos na Hotmart ou 90 dias na Kiwify. Você pode filtrar por produto e pelos valores documentados de status/pagamento do provedor; na Kiwify também pode usar o filtro de afiliado. Sem filtro de status na Hotmart, a API retorna apenas APPROVED e COMPLETE; selecione explicitamente outro status documentado quando precisar. Clique em Visualizar vendas: essa chamada é somente leitura, usa a paginação oficial de cada provedor e não grava contato, organização, evento nem pedido. Revise a ação local de cada linha e selecione explicitamente de 1 a 500 IDs antes de colocar a importação na fila. Omitir a seleção nunca significa “importar tudo”.

A importação associa somente contatos existentes da conta pelos campos exatos desse endpoint de vendas. O histórico da Hotmart fornece o e-mail do comprador (nome/ucode não são usados como identidade); o GET /sales da Kiwify fornece e-mail, celular e CPF. Uma organização só é vinculada pela organização principal atual do contato que coincidiu exatamente. A importação nunca escolhe entre correspondências conflitantes nem inventa um campo de CNPJ que a listagem da Kiwify não documenta. Um comprador sem contato existente, ou um status sem equivalência local fiel, aparece como não importável; a importação histórica nunca cria pessoas nem empresas. Os eventos de ciclo de vida e Pedidos do CRM importados preservam as datas de pedido/aprovação do provedor e recebem a marca histórica. Isso suprime mensagens ao cliente, fan-out de automações, crédito de comissão e ranking, engajamento, CAPI, efeitos de estoque e webhooks de saída da conta, mas ainda preenche o registro nativo de pedidos.

Use o Histórico de execuções para revisar quantidades selecionadas, criadas, atualizadas, reparadas, ignoradas e com falha, os IDs exatos ignorados/com falha e se a leitura global do provedor foi truncada. Uma solicitação idêntica reutiliza a execução ativa e o processamento é travado por conta/fonte. Uma execução concluída ou parcial oferece Desfazer importação somente enquanto cada pedido e evento criado localmente continuar intocado e sem vínculos; a reversão é atômica, nunca chama Hotmart/Kiwify e nunca exclui contatos ou organizações.

Casos de uso

• Importar uma loja Shopify ou WooCommerce para o catálogo nativo e atender por ali.
• Publicar produtos nativos em um marketplace (quando o conector suporta saída).
• Manter Mercado Livre ou Nuvemshop conectados para alimentar o catálogo nativo.
• Importar infoprodutos do Hotmart ou Kiwify e ainda receber os eventos de venda na conversa.

Capacidades por plataforma

Cada conector declara o que suporta; a interface libera a direção e os botões conforme essa capacidade.

• A publicação (saída) para o WhatsApp Business Catalog tem artigo próprio; os conectores de loja/marketplace acima focam em importação nesta versão. Nem toda plataforma é bidirecional.
• Os webhooks de eventos acima entregam eventos de venda (não produtos) e alimentam o Ciclo de vida de e-commerce — veja o artigo correspondente.
• A OLX não oferece API pública de leitura: a integração existe apenas para parceiros aprovados, que publicam um feed de anúncios (autoupload). Por isso o conector OLX vem desabilitado no Sync Studio até a liberação de acesso de parceiro.

Dicas, limites e boas práticas

• As credenciais ficam no servidor: são criptografadas, nunca retornam na tela e não aparecem em logs. Conectores OAuth (Mercado Livre) renovam o token sozinhos pela autorização concedida.
• Respeite a paginação e os limites da plataforma de origem; catálogos muito grandes são lidos em várias páginas e podem levar mais tempo na primeira importação.
• A descrição chega como texto puro: lojas como Nuvemshop/Tiendanube e Shopify guardam a descrição do produto em HTML. Na importação a plataforma converte para texto, preservando parágrafos, quebras de linha e listas — as tags nunca aparecem para você nem para o cliente, já que a descrição viaja como texto na mensagem enviada na conversa e no catálogo da Meta. Uma descrição que você mesmo digitar é gravada exatamente como escreveu.
• O link público vem junto na Nuvemshop/Tiendanube: a importação preenche o campo Link público do produto com a URL canônica informada pela loja. Em respostas que trazem apenas o identificador amigável da página, a plataforma combina esse valor com o domínio da loja. A próxima sincronização — a agendada ou a que você disparar em Rodar agora — também completa o link dos itens importados anteriormente; não é preciso reimportar nada.
• Sem domínio, os produtos sincronizam mesmo assim: se a loja não informar um domínio público, ou se a consulta aos dados da loja falhar, os produtos são importados normalmente, sem o link. A execução termina como Concluída parcialmente, com o aviso de que não foi possível obter o domínio público da loja, em vez de falhar inteira.
• Preencher o link à mão é para produtos sem link na origem: em um produto sincronizado da Nuvemshop/Tiendanube o link é montado a partir da loja — o endereço da página do produto somado ao domínio da loja. Por isso, um link digitado à mão é substituído na próxima sincronização sempre que a loja tiver um domínio público. O que a sincronização nunca faz é apagar o campo: enquanto a origem não tiver link para aquele produto, o que você digitou em Link público do produto fica.
• Atributos personalizados são preservados: a sincronização atualiza apenas os atributos que a origem envia e mantém os que você preencheu no produto.
• Um item com problema não trava os outros: quando um produto não pode ser gravado, a execução segue com os demais e termina como Concluída parcialmente. O Histórico de execuções mostra até 50 desses produtos, com o identificador na origem, o nome e o motivo.
• Na Nuvemshop/Tiendanube, dois produtos com o mesmo endereço continuam sendo dois: o endereço da página do produto (o identificador amigável) é de um único produto na loja. Quando dois produtos ativos usam o mesmo, cada um mantém o próprio cadastro no catálogo; o segundo recebe o endereço seguido do identificador dele na origem. Se um produto foi apagado e recriado na loja com o mesmo endereço, o cadastro existente é reaproveitado e a execução avisa em Produtos para revisar.
• Essa regra vale só para o conector Nuvemshop/Tiendanube: as demais origens e a API de entrada continuam agrupando em um único produto as linhas que repetem o mesmo endereço (slug) ou o mesmo nome — é assim que uma fonte com uma linha por variação vira um produto com várias variações, e que o catálogo do WhatsApp Business agrupa itens de mesmo nome, como sempre foi.
• Catálogos com mais de 40.000 produtos na Nuvemshop/Tiendanube: a leitura é feita em partes, e só uma leitura completa da loja consegue confirmar que o produto antigo deixou de existir. Nesses catálogos, um produto recriado com o mesmo endereço não assume o cadastro antigo: ele aparece entre os produtos que não foram sincronizados, com o motivo de que outro produto usa o mesmo endereço. Dê ao produto novo um endereço próprio na loja para que ele seja importado como um cadastro novo.
• Valores em unidades maiores: preços continuam em unidades maiores (4,97 = R$4,97). A plataforma não divide por 100.
• Rode a primeira importação fora do horário de pico para revisar o resultado com calma.

Solução de problemas

• A autorização do Mercado Livre falhou: confirme que o aplicativo da plataforma usa o endereço de retorno fixo /catalog_oauth/callback e refaça o fluxo de Autorizar (o state da autorização expira em poucos minutos).
• Produtos não foram importados: use Testar conexão para ver a resposta real; cheque o token/as chaves, o store_id/account_id quando aplicável e se o conector escolhido é o correto. A prévia genérica mostra o motivo devolvido pela plataforma, com segredos ocultados.
• O webhook não dispara: confirme que a fonte foi registrada (Nuvemshop/Kiwify) ou que o endereço foi colado no painel da plataforma (Hotmart), e que o segredo do webhook está preenchido.
• Itens duplicados: a duplicidade é evitada pelo identificador de origem (retailer_id / external_id); se aparecerem duplicatas, verifique se os itens chegaram com identificadores diferentes do que já existia.
• O link público do produto está vazio: veja, no card da fonte, o status e o aviso da última execução. O aviso de que não foi possível obter o domínio público da loja significa que os produtos entraram sem link: confira o domínio na Nuvemshop/Tiendanube e clique em Rodar agora, ou digite o link no próprio produto — ele vale até a sincronização conseguir montar o link pela loja. Se a execução aparece como Falhou, o texto do erro diz o motivo (por exemplo, token inválido) e a leitura parou naquele ponto: os produtos das páginas já lidas ficaram gravados e os demais não foram atualizados — se a falha foi logo na primeira leitura, nenhum foi. Corrija a causa e clique em Rodar agora: a próxima execução retoma de onde a anterior parou.
• Alguns produtos não atualizam: abra a execução Concluída parcialmente no Histórico de execuções e veja a lista de produtos que não foram sincronizados e o motivo de cada um. Corrija o item na origem, ou o produto em conflito no catálogo, e rode a sincronização de novo.
• A execução mostra "Produtos para revisar": a lista aponta produtos que foram sincronizados, mas cuja identificação na origem pede atenção — um produto que assumiu o cadastro de outro que não existe mais, ou dois produtos ativos que já dividiam o mesmo cadastro. Um cadastro dividido não é separado nem ampliado pela sincronização: o primeiro produto continua sendo o dono dele e, do segundo, só são atualizadas as variações que já estão ali (preço e estoque), para que um não sobrescreva o outro. Uma variação nova do segundo produto não é importada, e mudar o endereço dele na loja não o separa: ele só ganha um cadastro próprio se chegar como um produto novo, com variações que não estejam no cadastro dividido. A execução só fica Concluída parcialmente quando aparece um caso novo: na primeira vez em que um par é detectado, ou quando um par que tinha sido corrigido volta. Fora isso o aviso continua listado e a execução termina Concluída — inclusive quando um dos casos deixa de existir e ainda restam outros. Quando a mesma execução tem mais de um aviso — por exemplo, este e o do domínio público da loja —, os dois aparecem juntos.

Veja também

• Catálogo nativo: produtos, categorias, imagens e preços
• Sincronização e WhatsApp Business Catalog
• Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify

Nomes de variantes da Nuvemshop

A sincronização preserva as opções de tamanho e cor da plataforma e compõe o nome da variante com esses valores. Execute a sincronização novamente para preencher opções de produtos importados anteriormente. Repetir a mesma sincronização atualiza as variantes existentes sem duplicá-las; uma resposta incompleta não apaga nomes e opções já importados com sucesso.