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 Conversa Labs. 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 Conversa Labs 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 Conversa Labs 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.
• 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.

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