## 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.

| Plataforma | Importar (entrada) | Webhook de eventos | Vendas históricas | Autenticação |
|---|---|---|---|---|
| Fonte Genérica (JSON, NDJSON, XML, CSV ou TSV) | Sim | Sim (assinatura HMAC configurável) | Não | Bearer, cabeçalho, Basic ou parâmetro da URL |
| Shopify | Sim | — | Não | Token / cabeçalho |
| WooCommerce | Sim | — | Não | Token / cabeçalho |
| Magento, PrestaShop, Medusa | Sim | — | Não | Token / cabeçalho |
| Mercado Livre | Sim | — | Não | OAuth (Autorizar) |
| Nuvemshop | Sim | Sim (auto-registro) | Não | Token da loja (colar) |
| Hotmart | Sim (produtos) | Sim (no painel Hotmart) | Sim (prévia e seleção governadas) | Client-credentials |
| Kiwify | Sim (produtos) | Sim (auto-registro) | Sim (prévia e seleção governadas, até 90 dias) | Client-credentials |
| OLX | Não (sem API de leitura) | — | Não | Apenas parceiro |

- 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](/hc/ajuda/articles/catalog-commerce-catalogo-nativo-pt-br)
- [Sincronização e WhatsApp Business Catalog](/hc/ajuda/articles/catalog-commerce-sync-whatsapp-business-catalog-pt-br)
- [Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify](/hc/ajuda/articles/catalog-commerce-commerce-lifecycle-pt-br)