Catálogo & Comércio
Por Conversa Labs
Por Conversa Labs
Catálogo nativo, sincronização e WhatsApp Business Catalog, envio de produtos/pedidos na conversa e ciclo de vida de e-commerce.
Visão geral de Catálogo & Comércio
Visão geral O módulo Catálogo & Comércio reúne tudo o que envolve produtos e vendas dentro das suas conversas. Com ele você mantém um catálogo nativo (produtos, categorias, imagens e preços), sincroniza esse catálogo com o WhatsApp Business Catalog da Meta, envia produtos e listas de produtos diretamente no atendimento, recebe pedidos do cliente como um card pronto para cobrar e acompanha o ciclo de vida de e-commerce de plataformas externas (Kiwify, Hotmart, Nuvemshop, Shopify) sem sair da plataforma. A ideia é transformar a conversa em um balcão de vendas: o cliente vê o produto, monta o pedido e você cobra — tudo no mesmo lugar, integrado ao CRM, aos Pagamentos e aos Follow-ups. Pré-requisitos - Uma conta Conversa Labs ativa com o módulo de Catálogo & Comércio habilitado para o seu plano e perfil de acesso. Se não enxergar o módulo, fale com um administrador. - Para o WhatsApp Business Catalog: uma Caixa de Entrada de WhatsApp (Cloud API) conectada e vinculável ao catálogo da Meta. - Para o ciclo de vida de e-commerce: acesso à plataforma externa (Kiwify, Hotmart, Nuvemshop ou Shopify) para configurar o webhook. - Para cobrar pedidos: o módulo de Pagamentos configurado (gateways como Asaas ou Mercado Pago). Passo a passo 1. Crie ou importe seu catálogo nativo de produtos (com categorias, imagens e preços). 2. Se você atende por WhatsApp, vincule e sincronize o catálogo com o WhatsApp Business Catalog. 3. Durante o atendimento, envie produtos (um produto ou uma lista) para o cliente na conversa. 4. Quando o cliente monta um carrinho, receba o pedido como card e gere a cobrança ou a assinatura. 5. Conecte plataformas de e-commerce para acompanhar o ciclo de vida (carrinho abandonado, PIX pendente, compra aprovada, reembolso) e recuperar vendas com Follow-ups. Configurações & opções - Catálogo nativo: cadastro de produtos, categorias, imagens, preço e disponibilidade. - Fontes de sincronização: vinculação ao WhatsApp Business Catalog (Meta) e a conectores externos, com intervalo de sincronização configurável. - Envio na conversa: enviar produto único, lista de produtos ou abrir o catálogo no WhatsApp. - Pedidos: card de pedido com itens, total e atalhos para Criar cobrança / Criar assinatura. - Comércio (lifecycle): webhooks de plataformas externas com URL e segredo de verificação por fonte. Casos de uso - Loja que atende por WhatsApp e quer mostrar produtos nativos sem mandar o cliente para um site. - Operação que recebe pedidos pelo carrinho do WhatsApp e fatura na hora com PIX ou boleto. - Infoprodutor que vende por Kiwify/Hotmart e quer recuperar carrinho abandonado e PIX pendente. - E-commerce em Nuvemshop/Shopify que centraliza a recuperação de vendas no atendimento. Dicas, limites e boas práticas - Valores em unidades maiores: o preço 4,97 significa R$4,97 — nunca divida por 100. O total de um pedido é a soma de preço × quantidade de cada item. - Produtos e pedidos nativos no WhatsApp (catálogo, lista, card de pedido) funcionam na API Cloud; no WhatsApp Web a venda usa o card de produto enriquecido como alternativa. - Mantenha as imagens dos produtos acessíveis publicamente para que a sincronização consiga baixá-las. - Comece pelo catálogo nativo bem organizado antes de ativar sincronização e conectores externos. Solução de problemas - Não vejo o módulo: pode não estar habilitado para sua conta ou perfil — fale com um administrador. - Produtos sem imagem após sincronizar: confira se as imagens originais estão acessíveis e refaça a sincronização (cada execução tenta baixar as imagens novamente). - O cliente não recebe o produto/pedido nativo: confirme que a caixa de entrada é WhatsApp Cloud API. Veja também - Catálogo nativo: produtos, categorias, imagens e preços - Sincronização e WhatsApp Business Catalog - Enviar produto e receber pedidos na conversa - Ciclo de vida de e-commerce
Catálogo nativo: produtos, categorias, imagens e preços
Visão geral O catálogo nativo é a sua base de produtos dentro da Conversa Labs. É onde você cadastra cada item com nome, descrição, imagens, preço e disponibilidade, organiza tudo em categorias e mantém os dados que serão usados para sincronizar com o WhatsApp e para enviar produtos durante o atendimento. Tê-lo bem organizado é o primeiro passo: a partir dele você sincroniza com a Meta, envia produtos na conversa e cobra pedidos. Mesmo que você também use plataformas externas, o catálogo nativo é a fonte da verdade dentro da plataforma. Pré-requisitos - Módulo de Catálogo & Comércio habilitado para sua conta e perfil de acesso. - Permissão para gerenciar o catálogo (cadastrar/editar produtos e categorias). - Imagens dos produtos em um formato comum (por exemplo, JPG ou PNG) e acessíveis. Passo a passo 1. Abra a área de Catálogo da plataforma. 2. Crie suas categorias para agrupar produtos (por exemplo, "Bebidas", "Serviços", "Cursos"). 3. Cadastre um produto: informe nome, descrição, categoria e a primeira variação. 4. Em cada variação, defina nome, SKU, preço e opções como Cor: Azul e Tamanho: M. 5. Use as setas para ordenar as variações e escolha exatamente uma como padrão. 6. Adicione uma ou mais imagens ao produto. Depois, você pode vincular uma imagem do produto a cada variação; variações sem imagem usam a imagem principal. 7. Defina disponibilidade e estoque quando necessário, salve e repita para os demais produtos. Configurações & opções - Produto: nome, descrição, preço, categoria, disponibilidade, imagens e identificadores (como SKU e link externo). - Categorias: agrupamento dos produtos para facilitar a busca e a montagem de listas. - Imagens: uma ou mais por produto; a primeira costuma ser usada como destaque. - Variações: cada combinação vendável tem nome, opções, posição, preço, estoque e imagem opcional. A variação padrão é a escolha inicial nas listas e nos envios. - Arquivar uma variação: o formulário de edição só descarta variações que ainda não foram salvas. Arquive uma variação salva no detalhe do produto, após a confirmação, e escolha antes outra variação padrão. O registro arquivado e seu histórico de pedidos e pagamentos são preservados. - Imagem da variação: só pode ser escolhida na galeria do mesmo produto. Ao excluí-la, a variação volta com segurança para a imagem principal do produto. - Preço: sempre em unidades maiores da moeda (veja a seção de dicas). - Baixa automática de estoque: quando uma venda ao vivo fica paga, a quantidade de cada variação com controle de estoque é baixada uma única vez. A cobrança e o pedido da mesma venda compartilham a mesma identidade, portanto webhooks repetidos ou os dois eventos não baixam em dobro. O saldo para em zero; variações sem controle de estoque não são alteradas. Importações e adoções históricas também não alteram o saldo atual. O estoque rastreado usa unidades inteiras: uma linha fracionária falha de modo seguro, sem arredondar nem baixar parcialmente a venda, e fica visível no Histórico. Quantidades fracionárias de variações sem controle de estoque não alteram o saldo. - Relatórios: a visão de relatórios distingue o orçamento dos itens de negócios do valor realizado nos itens de pedidos pagos. As duas métricas não são somadas e podem divergir quando há descontos, frete ou pedidos ainda não liquidados. Casos de uso - Cardápio de um restaurante ou lanchonete com categorias e fotos. - Catálogo de serviços (consultas, planos, pacotes) com preço por item. - Lista de produtos físicos de uma loja que vende por WhatsApp. - Catálogo de infoprodutos ou cursos para enviar diretamente ao cliente. Dicas, limites e boas práticas - Preço em unidades maiores: digite 4,97 para indicar R$4,97. A plataforma não divide por 100 — o valor que você cadastra é o valor exibido e cobrado. - O total de um pedido é a soma de preço × quantidade de cada item — também sem divisão por 100. - Use imagens nítidas e acessíveis publicamente: a sincronização com o WhatsApp precisa conseguir baixá-las. Imagens hospedadas em endereços que ficam fora do ar não serão importadas. - Mantenha nomes e descrições claros — eles aparecem para o cliente quando você envia o produto. - No relatório, trate Orçado como a proposta registrada no negócio e Realizado como itens de pedidos pagos. Um item sem pedido pago não entra no realizado. Solução de problemas - Preço aparecendo errado (ex.: R$0,05 em vez de R$4,97): confirme que digitou o valor em unidades maiores; não multiplique nem divida por 100. - Imagem não aparece: verifique se o arquivo é válido e se o endereço da imagem está acessível. - Uma variação não pode ser arquivada ou excluída: escolha primeiro outra variação ativa como padrão. - A imagem errada aparece na variação: edite o produto e escolha uma imagem da galeria para essa variação, ou selecione o uso da imagem principal. - Produto não some das listas: marque-o como indisponível em vez de manter visível quando não estiver à venda. - Uma venda paga não baixou o estoque: confirme que a linha da venda aponta para uma variação com controle de estoque ativo. Registros apenas importados ou adotados como histórico são mantidos para consulta e, de propósito, não reescrevem o saldo atual. - A baixa aparece como falha depois dos retries automáticos: um administrador deve abrir Catálogo → Importar & Sincronizar → Histórico, localizar a execução Baixa automática de estoque, abrir o detalhe e clicar em Tentar baixa novamente. A execução identifica a cobrança ou o pedido e mostra apenas uma referência técnica sanitizada, sem credenciais ou payload do gateway. O retry é seguro: o recibo único da venda impede uma segunda baixa se a tentativa anterior tiver concluído de forma ambígua. Se a execução estiver Pendente ou Processando, aguarde o worker em vez de clicar novamente. Se o motivo indicar quantidade fracionária, corrija a linha de origem para unidades inteiras — ou desative o controle somente quando a variação for legitimamente fracionável — antes de tentar novamente; a plataforma nunca arredonda essa quantidade. Veja também - Visão geral de Catálogo & Comércio - Sincronização e WhatsApp Business Catalog - Enviar produto e receber pedidos na conversa
Sincronização e WhatsApp Business Catalog
Visão geral A sincronização conecta o seu catálogo nativo ao WhatsApp Business Catalog da Meta. Depois de vincular, os produtos passam a existir nos dois lugares e podem ser mantidos em duas vias: o que você cadastra na plataforma é enviado para a Meta, e o que existe no catálogo da Meta pode ser importado para a plataforma. Isso é o que torna possível enviar produtos nativos no WhatsApp, abrir o catálogo dentro da conversa e receber pedidos do carrinho do cliente — tudo a partir de um catálogo único e atualizado. Pré-requisitos - Uma Caixa de Entrada de WhatsApp (Cloud API) conectada e funcionando. - Um catálogo configurado na sua conta comercial da Meta (Business / Commerce Manager). - Módulo de Catálogo & Comércio habilitado e permissão para gerenciar fontes de sincronização. - Catálogo nativo com produtos cadastrados (recomendado antes da primeira sincronização). Passo a passo 1. Na área de Catálogo, abra a configuração de fontes de sincronização. 2. Crie uma fonte do tipo WhatsApp Business Catalog (Meta) e selecione o catálogo da Meta a vincular. 3. Vincule a fonte à caixa de entrada de WhatsApp Cloud correspondente — a credencial de acesso é reaproveitada automaticamente dessa caixa, sem precisar informar um token à parte. 4. Defina o intervalo de sincronização (de quanto em quanto tempo a plataforma confere o catálogo da Meta). 5. Execute a primeira sincronização e confira os produtos importados/atualizados. 6. A partir daí, alterações fluem nas duas vias conforme o intervalo configurado, e você pode forçar uma sincronização manual quando quiser. Configurações & opções - Catálogo da Meta vinculado: qual catálogo da conta comercial está conectado à fonte. - Caixa de entrada: a inbox de WhatsApp Cloud usada para a credencial e para enviar produtos. - Intervalo de sincronização: frequência das sincronizações automáticas. - Sincronização manual: botão para rodar a sincronização na hora. - Duas vias: produtos cadastrados na plataforma são publicados na Meta; produtos da Meta são importados para a plataforma, casando os identificadores de cada lado. Publicar com segurança e revisar a validação Cada variação vendável é publicada como um item próprio no catálogo da Meta. As variações do mesmo produto ficam agrupadas, mas têm identificadores independentes; assim, preço e disponibilidade não se misturam entre tamanhos, cores ou opções. Antes de enviar, a plataforma bloqueia a variação e mostra o motivo quando faltar algum requisito da Meta: nome, descrição, marca, link público HTTPS, preço, moeda ou imagem pública HTTPS de ao menos 500 × 500 pixels. Complete os campos no produto e tente novamente — um bloqueio local não é tratado como produto sincronizado. Depois que a Meta aceita o lote, ela ainda valida o conteúdo de forma assíncrona. Abra o produto e veja o status em cada variação: Aguardando validação, Validado, Rejeitado, Envio bloqueado ou Validação inconclusiva. Um item só deve ser considerado disponível na Meta depois de Validado; a mensagem de rejeição aponta o campo que precisa ser corrigido. Validação inconclusiva significa que a Meta respondeu sem um resultado reconhecido. Estados transitórios, como “iniciado”, são consultados novamente por até quatro minutos; se aparecer tempo de validação esgotado, reenvie o produto e acompanhe o histórico de execuções. Ao importar de volta, os itens do mesmo grupo voltam para o mesmo produto, cada um como a sua variação. A plataforma reconhece o produto pelo grupo e pelo identificador de cada variação, então uma reimportação atualiza o produto existente em vez de criar uma cópia. Reconciliação assistida de itens remotos Ao editar uma fonte Meta de saída ou de duas vias, a seção Reconciliação assistida do catálogo Meta lista itens remotos que não têm uma variação local com o mesmo retailer_id. Ela é apenas uma revisão: 1. Atualize a lista e confira nome e identificador de cada possível órfão. 2. Marque somente os itens que realmente devem sair do catálogo Meta. 3. Clique em Solicitar remoção selecionada e confirme no diálogo. Nada é removido ao abrir ou atualizar a lista. A plataforma relê o catálogo no momento da solicitação, recusa uma seleção que mudou e também recusa um lote acima do limite de segurança de 10% do catálogo remoto. Mesmo após aceitar a solicitação, a Meta valida o lote: o resultado exibido é “enviado para validação”, não “removido”, até a confirmação remota. Casos de uso - Loja que já tem catálogo na Meta e quer trazê-lo para a plataforma para atender e cobrar. - Operação que prefere cadastrar produtos na plataforma e publicá-los automaticamente no WhatsApp. - Equipe que mantém um catálogo único e quer evitar atualizar preços em dois lugares. Dicas, limites e boas práticas - Credencial automática: ao vincular a fonte à caixa de WhatsApp Cloud, a plataforma usa a credencial dessa inbox — você não precisa cadastrar um token só para o catálogo. - Imagens precisam estar acessíveis: a sincronização baixa as imagens dos produtos. Se a imagem original estiver hospedada em um endereço que saiu do ar, ela não será importada. Mantenha as imagens em um local público, estável, HTTPS e com pelo menos 500 × 500 pixels para publicação. - Valores em unidades maiores: preços continuam em unidades maiores (4,97 = R$4,97) dos dois lados. - Faça a primeira sincronização fora do horário de pico para revisar com calma o resultado. Solução de problemas - Produtos importados sem imagem: a imagem original pode estar inacessível; garanta um endereço público e refaça a sincronização (cada execução tenta baixar as imagens novamente). - Nada sincroniza: confirme que a fonte está vinculada a uma caixa de WhatsApp Cloud válida e que o catálogo da Meta selecionado é o correto. - Mudança não apareceu do outro lado: aguarde o intervalo de sincronização ou rode uma sincronização manual. Para publicação, abra a variação e confira se a validação da Meta está aguardando, bloqueada ou rejeitada; uma resposta de lote aceita ainda não é confirmação de catálogo. - Tempo de validação esgotado: a Meta não entregou um resultado final durante as tentativas automáticas. Reenvie o produto; se o aviso persistir, confira o item no Commerce Manager da Meta. - O item não aparece na reconciliação: itens remotos sem retailer_id não são oferecidos para remoção automática por segurança. Localize-os diretamente no Commerce Manager da Meta. Veja também - Catálogo nativo: produtos, categorias, imagens e preços - Enviar produto e receber pedidos na conversa - Visão geral de Catálogo & Comércio
Catálogo & Vitrine na caixa de entrada do WhatsApp
Visão geral Ter um catálogo criado e sincronizado na Meta não é o mesmo que ter a vitrine ligada no seu número de WhatsApp. São três coisas diferentes, e todas precisam estar em ordem para que um produto possa ser enviado na conversa: 1. O catálogo existe na sua conta comercial da Meta e tem itens publicados. 2. O catálogo está vinculado à sua Conta do WhatsApp Business (a WABA). 3. A vitrine está visível no número — esta é a etapa que costuma passar despercebida, porque a Meta cria o número com a vitrine desligada por padrão. Quando a etapa 2 ou a 3 está faltando, o catálogo aparece perfeito no gerenciador da Meta, mas o envio de produto na conversa falha — normalmente com o erro #131008. A aba Catálogo & Vitrine existe para tornar isso visível. Ela fica dentro das configurações da caixa de entrada, lê o estado ao vivo na Meta e mostra, em linhas simples, o que está pronto e o que falta. Um único botão — Ativar vitrine neste número — resolve a etapa 3. A aba cuida do comércio do número. A sincronização dos produtos (mapeamento, agendamento, histórico) continua no Sync Studio, no módulo de Catálogo. Pré-requisitos - Uma Caixa de Entrada de WhatsApp (Cloud API). A aba não aparece em caixas de WhatsApp Web nem em outros canais — a vitrine é um recurso da API Cloud. - Um catálogo na Meta com itens publicados. Se você ainda não tem, crie e sincronize primeiro pelo Sync Studio. - Permissão de administrador na caixa de entrada, dentro da plataforma. - A conexão com a Meta precisa ter permissão sobre o catálogo e sobre a Conta do WhatsApp Business. Sem isso, a leitura funciona parcialmente e a ativação é recusada pela Meta. Passo a passo 1. Abra Configurações → Caixas de Entrada e selecione a caixa de entrada do WhatsApp Cloud API. 2. Abra a aba Catálogo & Vitrine. 3. Leia o diagnóstico. Cada linha responde uma pergunta objetiva: qual catálogo está selecionado, se ele está vinculado à Conta do WhatsApp Business, se a vitrine está visível no número, se o carrinho está habilitado, quantos itens o catálogo tem e quando foi a última sincronização. 4. Se ainda não houver um catálogo selecionado, escolha o catálogo que este número deve usar. 5. Se a vitrine estiver desligada, clique em Ativar vitrine neste número e confirme. 6. Recarregue o diagnóstico e confirme que o vínculo e a vitrine aparecem como ativos. 7. Abra uma conversa e envie um produto para validar de ponta a ponta. Configurações & opções - Catálogo selecionado — qual catálogo da Meta este número usa. É a origem dos produtos que você envia na conversa. - Vínculo com a Conta do WhatsApp Business — indica se o catálogo está associado à WABA. Sem o vínculo, o número não enxerga os produtos, mesmo que eles existam. - Vitrine visível no número — indica se a vitrine está ligada neste número específico. É o que o botão de ativação altera. - Carrinho habilitado — indica se o cliente pode montar um carrinho e enviar um pedido. Quando o carrinho está desligado, o cliente ainda vê os produtos, mas não fecha um pedido pelo WhatsApp. - Itens no catálogo — quantos produtos a Meta enxerga hoje. Um número zerado quase sempre significa que a sincronização não concluiu. - Última sincronização — quando os produtos foram enviados ao catálogo pela última vez. - Ativar vitrine neste número — o único botão que escreve na sua conta da Meta. Nada é alterado lá sem esse clique: abrir a aba apenas lê o estado atual. Casos de uso - Caixa nova: você acabou de conectar o número, o catálogo já está sincronizado e quer deixar o envio de produtos pronto antes do primeiro atendimento. - Envio falhando: um agente relata que "não consegue enviar produto". A aba mostra em segundos se o problema é vínculo, vitrine ou catálogo vazio. - Vários números: cada número tem a própria vitrine. Ao abrir um novo número na mesma conta comercial, você repete apenas a ativação — o catálogo continua o mesmo. - Auditoria periódica: antes de uma campanha, conferir itens no catálogo e a última sincronização evita anunciar produto que a Meta não enxerga. Dicas, limites e boas práticas - A vitrine nasce desligada. É um comportamento da Meta, não uma falha da plataforma. Todo número novo precisa da ativação uma vez. - A ativação é explícita. A plataforma nunca liga a vitrine sozinha, nem durante a sincronização. A escrita acontece somente quando você clica no botão. - A leitura é ao vivo. Os valores vêm da Meta no momento em que a aba abre, não de um cache. Se alguém alterar algo no gerenciador da Meta, recarregar a aba já mostra o novo estado. - Vitrine é por número; catálogo é por conta comercial. O mesmo catálogo pode servir vários números, mas cada número precisa da própria ativação. - Sincronizar não ativa. Uma sincronização bem-sucedida no Sync Studio publica produtos, mas não liga a vitrine. São etapas independentes. - Carrinho e pedidos: para receber pedidos estruturados na conversa, o carrinho precisa estar habilitado além da vitrine. Solução de problemas - Erro #131008 ao enviar um produto — a Meta indica que falta um parâmetro obrigatório para a mensagem de produto. Na prática, o número não tem uma vitrine utilizável: o catálogo não está vinculado à Conta do WhatsApp Business, ou a vitrine está desligada no número. Correção: abra a aba Catálogo & Vitrine, selecione o catálogo e clique em Ativar vitrine neste número. - Erro #131009 ao enviar um produto — a Meta indica que um valor enviado é inválido. Em geral o produto informado não está no catálogo vinculado: o item não foi sincronizado, foi arquivado, ou pertence a outro catálogo. Correção: confira no diagnóstico se o catálogo selecionado é o mesmo onde o produto foi publicado, verifique a contagem de itens e rode a sincronização no Sync Studio. - A aba não aparece — a caixa de entrada não é do WhatsApp Cloud API. Vitrine e catálogo nativo são recursos da API Cloud. - A ativação é recusada — a conexão com a Meta não tem permissão suficiente sobre o catálogo ou sobre a Conta do WhatsApp Business. Revise as permissões no gerenciador da Meta e tente novamente. - Itens no catálogo = 0 — a sincronização não concluiu ou os produtos foram rejeitados pela Meta. Confira o histórico de sincronização no Sync Studio. - Vitrine ativa, mas o cliente não fecha o pedido — provavelmente o carrinho está desabilitado. Veja também - Sincronização e WhatsApp Business Catalog - Enviar produto/lista e receber pedidos na conversa - Catálogo nativo: produtos, categorias, imagens e preços
Enviar produto/lista e receber pedidos na conversa
Visão geral Com o catálogo pronto e sincronizado, você pode enviar produtos ao cliente dentro da conversa e receber o pedido dele de volta como um card estruturado. Em vez de descrever preços em texto, você envia o item certo; quando o cliente monta um carrinho no WhatsApp, o pedido chega organizado, com itens, quantidades e total — e com atalhos para gerar a cobrança. São três formas de mostrar produtos: produto único, lista de produtos e abrir o catálogo. E uma forma de receber: o pedido (order) que vira card na conversa. Pré-requisitos - Catálogo nativo com produtos e, para recursos nativos do WhatsApp, a sincronização com o WhatsApp Business Catalog ativa. - Uma Caixa de Entrada de WhatsApp (Cloud API) — os formatos nativos de produto, lista e pedido funcionam na API Cloud. - A vitrine ativa no número, na aba Catálogo & Vitrine da caixa de entrada. A Meta cria todo número com a vitrine desligada: sem ativá-la, o envio de produto falha com o erro #131008. Veja Catálogo & Vitrine na caixa de entrada do WhatsApp. - Para o envio interativo de um produto pelo WhatsApp Web, basta a caixa Web ativa; o carrinho e o pedido nativos continuam exclusivos da Cloud API. - Para cobrar o pedido: o módulo de Pagamentos configurado. Passo a passo 1. Abra a conversa com o cliente. 2. No campo de envio, escolha enviar produto e selecione um item (produto único) ou monte uma lista de produtos. Quando houver mais de uma variação, escolha a correta; quando a variação tiver preços em mais de uma moeda, escolha também a moeda. Você pode ainda abrir o catálogo para o cliente navegar. 3. Na Cloud API, o cliente pode adicionar os itens ao carrinho. No WhatsApp Web, ele usa Tenho interesse ou Ver produto no card interativo. 4. Quando o cliente finaliza o carrinho, o pedido chega na conversa como um card de pedido com os itens, as quantidades e o total. 5. No card do pedido, use Criar cobrança ou Criar assinatura para faturar exatamente o que foi pedido — o valor já vem preenchido com o total do pedido. 6. Acompanhe o pagamento pelo módulo de Pagamentos; quando confirmado, o cliente recebe a confirmação. Configurações & opções - Produto único: envia um item específico do catálogo. - Variação e moeda: o card usa a variação escolhida e o preço cadastrado para a moeda escolhida; a seleção não volta silenciosamente para a primeira variação. - Lista de produtos: envia vários itens agrupados em uma mensagem, preservando a variação e a moeda escolhidas em cada produto. - Abrir catálogo: convida o cliente a navegar pelo catálogo no WhatsApp. - Card de pedido: mostra itens, quantidades, total e observações do cliente. - Atalhos do pedido: Criar cobrança (pagamento único) e Criar assinatura (recorrente), já com o valor do pedido preenchido. - Produto referenciado: quando o cliente responde citando um produto, um indicador do item citado aparece junto da mensagem. Casos de uso - Cliente pergunta por um item específico — você envia o produto único com foto e preço. - Atendimento consultivo — você envia uma lista com as melhores opções para o cliente escolher. - Cliente monta o carrinho sozinho — o pedido chega pronto e você fatura em segundos. - Venda recorrente (assinatura/plano) — o pedido vira uma assinatura com o valor combinado. Dicas, limites e boas práticas - Cobre o que foi pedido: o card usa o total do pedido combinado com o cliente; o valor não é recalculado a partir dos preços atuais do catálogo. Faturar o pedido respeita exatamente o que o cliente montou. - Valores em unidades maiores: o total é a soma de preço × quantidade (4,97 = R$4,97), sem divisão por 100. - API Cloud: o formato nativo é usado somente quando a variação escolhida está publicada com retailer_id próprio e usa a moeda publicada. Caso contrário, a plataforma envia o card enriquecido com a variação e o preço exatos, sem trocar o item. - WhatsApp Web: um produto único segue como card interativo, com o botão Tenho interesse e, quando o cadastro tem link público, Ver produto. Esse envio não depende de licença adicional. - Confira o pedido antes de cobrar: itens, quantidades e total. Solução de problemas - O envio falhou com o erro #131008: a vitrine não está utilizável no número — o catálogo não está vinculado à Conta do WhatsApp Business ou a vitrine está desligada. Abra a aba Catálogo & Vitrine da caixa de entrada, selecione o catálogo e clique em Ativar vitrine neste número. Detalhes em Catálogo & Vitrine na caixa de entrada do WhatsApp. - O cliente não recebeu o produto/lista nativos: confirme que a caixa é WhatsApp Cloud API e que o catálogo está sincronizado. Confira também se a variação escolhida tem retailer_id próprio; sem ele, receber o card enriquecido é o fallback esperado. - O pedido não virou card: verifique se o pedido veio do carrinho do WhatsApp; pedidos de fora do WhatsApp seguem pelo ciclo de vida de e-commerce. - Valor errado ao cobrar: o card preenche o total do pedido; se editar manualmente, lembre-se das unidades maiores (não divida por 100). Veja também - Catálogo & Vitrine na caixa de entrada do WhatsApp - Catálogo nativo: produtos, categorias, imagens e preços - Sincronização e WhatsApp Business Catalog - Ciclo de vida de e-commerce
Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify
Visão geral O ciclo de vida de e-commerce conecta plataformas externas — Kiwify, Hotmart, Nuvemshop e Shopify — para que os eventos de venda cheguem dentro do atendimento. Quando algo acontece na plataforma externa (carrinho abandonado, PIX/boleto gerado, compra aprovada, recusada ou reembolsada), a Conversa Labs recebe o webhook, normaliza o evento e mostra um card na conversa do cliente, com os dados de pagamento quando disponíveis. Com isso, você recupera vendas sem trocar de ferramenta: o time vê o estágio da compra na própria conversa e pode acionar Follow-ups automáticos para reconquistar quem não finalizou. Pré-requisitos - Módulo de Catálogo & Comércio habilitado e permissão para configurar fontes de comércio. - Acesso à plataforma externa (Kiwify, Hotmart, Nuvemshop ou Shopify) para configurar o webhook. - Para recuperação automática: o módulo de Follow-ups configurado com sequências por evento. Passo a passo 1. Na área de Catálogo & Comércio, crie uma fonte de comércio para a plataforma desejada. 2. Copie a URL de webhook completa gerada para essa fonte. Ela inclui a conta e a fonte; não remova nenhum trecho. Configure também o segredo de verificação. Na Kiwify, o registro automático pode gerar e salvar o token; na Hotmart, informe o Hottok da aplicação. 3. Cole a URL no painel da plataforma externa (ou use o registro automático quando disponível, por exemplo em Kiwify e Nuvemshop). 4. Faça uma venda de teste (ou um carrinho de teste) para confirmar que o evento chega. 5. Veja o card do evento aparecer na conversa do cliente, com itens, valores e link/dados de pagamento conforme o estágio. 6. Configure Follow-ups acionados por evento (por exemplo, "carrinho abandonado") para recuperar a venda automaticamente. Configurações & opções - Fonte de comércio: uma por plataforma, com URL de webhook e segredo de verificação próprios. - Registro automático do webhook: disponível em parte das plataformas (ex.: Kiwify e Nuvemshop); nas demais, a configuração é manual no painel da própria plataforma. - Card do evento: mostra o estágio da compra e, quando a plataforma expõe, dados de PIX/boleto e o link de checkout. - Variáveis de comércio: dados do último evento ficam disponíveis para uso em mensagens de Follow-up (link de pagamento, valor, código PIX/boleto, etc.). Escolher quais eventos receber Ao editar a fonte em Catálogo → Fontes de sincronização → editar a fonte, a seção Eventos lista os eventos que aquela plataforma envia e permite mapear cada um para um estágio do ciclo de vida — ou marcá-lo como Desligado (ignorar) para descartá-lo por completo. Todo evento habilitado percorre o resto da plataforma: automações, flows, webhooks, Follow-up e o CRM. O mapeamento é o que decide em qual estágio ele entra. Um botão em destaque de Recuperação de carrinho abandonado liga e desliga o evento de carrinho da plataforma — é ele que alimenta a cadência de recuperação no Follow-up (gatilho commerce.cart_abandoned). Disponível para: | Fonte | Eventos que você mapeia | |---|---| | Hotmart | eventos de compra, carrinho, assinatura e área de membros | | Kiwify | os 10 gatilhos reais: compra_aprovada, pix_gerado, boleto_gerado, compra_recusada, compra_reembolsada, chargeback, carrinho_abandonado, subscription_renewed, subscription_late, subscription_canceled | | Nuvemshop | os valores de payment_status do pedido: paid, authorized, pending, refunded, partially_refunded, abandoned — o webhook da Nuvemshop traz apenas o ID, então o estágio vem do status de pagamento do pedido | | Fontes genéricas | os nomes de evento documentados pelo seu sistema. Você define explicitamente o campo do evento, o ID, os caminhos de comprador/produto/itens e o estágio canônico; nada é inferido pelo nome de uma plataforma | Fontes gerenciadas sem um contrato verificado de ciclo de venda, como Mercado Livre e OLX, não exibem um seletor de eventos. Fontes atendidas pelo conector genérico — inclusive uma configuração Shopify/API própria — exibem a configuração do webhook genérico assinado e recebem somente os eventos que você mapear explicitamente. Os padrões já são sensatos: só mexa no mapeamento se quiser um estágio diferente ou se quiser ignorar um evento. Casos de uso - Carrinho abandonado: dispara uma sequência de Follow-up lembrando o cliente de concluir. - PIX/boleto pendente: reenvia o código de pagamento e acompanha até confirmar. - Compra aprovada: confirma com o cliente e libera o próximo passo do atendimento. - Reembolso/recusa: alerta o time para tratar o caso na própria conversa. Dicas, limites e boas práticas - O que cada plataforma expõe varia: algumas enviam o código PIX e a linha do boleto no evento (recuperação completa dentro da conversa); outras só fornecem o link de checkout — nesses casos, o card mostra o link para o cliente concluir. - Valores e formatos diferem por plataforma: a Conversa Labs normaliza cada evento; você não precisa se preocupar com a conversão — o card já exibe o valor correto. - Segredo de verificação: mantenha-o configurado para que apenas eventos legítimos da plataforma sejam aceitos. Webhooks Hotmart, Kiwify, Nuvemshop e genéricos sem segredo configurado são recusados. Um emissor genérico também precisa enviar a assinatura com timestamp e um ID de entrega estável por evento. - Combine com Follow-ups para automatizar a recuperação em vez de depender de ação manual. Solução de problemas - O evento não aparece: confira se a URL completa de webhook foi colada corretamente na plataforma e se o segredo de verificação está configurado e confere. - Não vejo PIX/boleto no card: nem toda plataforma expõe esses dados; quando não há, o card traz o link de checkout. - Eventos duplicados: entregas genéricas com o mesmo ID são processadas uma única vez. Se notar algo estranho, confirme que o emissor reutiliza esse ID nas tentativas e que há apenas um webhook configurado para a mesma fonte. Veja também - Visão geral de Catálogo & Comércio - Enviar produto e receber pedidos na conversa - Catálogo nativo: produtos, categorias, imagens e preços
Configurar as mensagens da recuperação de vendas
Visão geral Cada estágio produzido da recuperação de vendas (carrinho abandonado, pagamento pendente, pagamento recusado e em atraso) envia um card ao cliente. Nesta tela você personaliza o texto desse card por estágio e por idioma, sem depender de nenhuma automação de IA. O que você não personalizar continua usando a mensagem embutida da Conversa Labs — ou seja, você mexe só no que quiser. Vence em breve continua reservado para compatibilidade com dados históricos, mas ainda não tem um produtor de eventos e não é oferecido para configuração nem automação. Além do corpo, você edita os rótulos auxiliares do card e configura, para cada estágio e cada idioma, o modelo aprovado do WhatsApp usado quando a janela de 24h está fechada. Pré-requisitos - A Recuperação de vendas precisa estar habilitada na conta. - Permissão de administrador para alterar as configurações. - Para configurar o envio fora da janela: uma caixa de entrada de WhatsApp Cloud com modelos aprovados na Meta. Passo a passo 1. Abra Recuperação de vendas → Mensagens. 2. Escolha o idioma no seletor do topo. Ele abre no idioma da conta e lista todos os idiomas habilitados na instalação (até 40), mostrando quantos já têm texto seu ("N de M idiomas com conteúdo"). 3. Em cada estágio, escreva o corpo da mensagem em Markdown. Deixe vazio para usar a mensagem padrão daquele idioma — o selo Padrão indica que o estágio está herdando o texto embutido. 4. Use o botão de variáveis ({x}) para inserir dados como {{contact.name}}, o valor e o link de pagamento do último evento do cliente. O seletor oferece apenas as variáveis que realmente resolvem naquela mensagem. 5. Abra o bloco Rótulos auxiliares para ajustar as 6 legendas e textos de botão do card. 6. O bloco Fora da janela de 24h (WhatsApp Cloud) aparece aberto, logo abaixo de cada estágio. Escolha o modelo aprovado daquele estágio naquele idioma, mapeie os parâmetros {{1}}, {{2}}… e, se o modelo tiver botão de link, informe o valor do botão. Se ainda não houver um modelo, use Criar a partir do meu texto para gerá-lo a partir do corpo que você escreveu. 7. Confira a prévia por canal e, se quiser, use Enviar teste para mandar a mensagem a uma conversa real. 8. Salvar mensagens — inclusive depois de criar um modelo, porque criar o modelo não grava a configuração. Para voltar um estágio ao padrão, use Restaurar padrão — a personalização é removida no servidor, não apenas na tela. Configurações & opções Idiomas e fallback O idioma não é mais um trio fixo de abas: é um seletor com todos os idiomas que a instalação habilita. Na hora do envio, a Conversa Labs procura o texto nesta ordem: 1. o idioma do contato; 2. o mesmo idioma-base (por exemplo, pt_BR ↔ pt); 3. o idioma da conta; 4. a mensagem padrão embutida. Rótulos auxiliares O card não é só o corpo da mensagem: ele tem legendas e textos de botão. Os 6 rótulos auxiliares ficam num bloco recolhível abaixo do corpo e seguem as mesmas regras de idioma e de restauração. Fora da janela de 24h (WhatsApp Cloud) O bloco aparece aberto e embutido logo abaixo de cada tipo de mensagem — não é uma seção que você precisa expandir. O modelo é por tipo de mensagem e por idioma — cada estágio tem o seu, em vez de um único modelo para o módulo inteiro. Nele você tem: - Escolher o modelo aprovado entre os do catálogo. - Sincronizar da Meta e Criar a partir do meu texto ficam sempre visíveis. Quando a ação não está disponível, o botão aparece desabilitado com o motivo escrito ao lado: a caixa não é WhatsApp Cloud, a conta não tem o WhatsApp Inbox Suite, ou o seu perfil não gerencia caixas de entrada. - Sincronizar da Meta atualiza a lista de modelos aprovados. - Criar a partir do meu texto gera o modelo a partir do texto daquele estágio naquele idioma, enviando-o à Meta como modelo UTILITY, convertendo cada {{ variável }} em {{1}}, {{2}}… e já deixando o mapeamento pronto. Sem texto para gerar, o botão fica desabilitado e a tela pede para escrever o texto primeiro. - Depois do envio, o modelo ainda não está aprovado: ele aparece no seletor marcado como aguardando aprovação e só passa a entregar quando a Meta aprovar e você sincronizar. Enviar de novo com o mesmo nome substitui o rascunho pendente, em vez de falhar. - Criar o modelo não salva a configuração — clique em Salvar mensagens para gravar o mapeamento. - Mapeamento dos parâmetros {{n}} e o campo do botão de link, quando o modelo tiver um. - Entrega: escolhe de qual caixa do WhatsApp o catálogo de modelos aprovados é consultado. O envio em si continua saindo pela caixa da própria conversa. Tudo que depende dessa caixa — por que sincronizar/criar está indisponível, quantos modelos ficaram de fora, o link para gerenciá-los e o botão Sincronizar da Meta — aparece uma vez aqui, e não repetido embaixo de cada mensagem. - Botões nativos: por padrão o link de pagamento sai como botão no WhatsApp, em vez de uma URL solta no texto. Você desliga por tipo de mensagem em Entrega → Botões nativos. No WhatsApp Cloud a Meta entrega um único botão, então o código PIX continua no corpo; no WhatsApp Web saem os dois. Modelos cujo cabeçalho exige mídia ou uma variável não entram nesta lista — este envio não tem como preencher esse cabeçalho — e a tela informa quantos ficaram de fora. Eles continuam utilizáveis pela aba Modelos da própria caixa de entrada, com link direto a partir desta tela. Observações importantes: - WhatsApp Web (WazMeow) não tem janela de 24h — para essas caixas o bloco de modelo nem aparece. - 360dialog pode selecionar um modelo, mas não criar — a criação é exclusiva do Cloud. - A Meta casa nome + idioma + aprovado. Um modelo no idioma errado é sinalizado na tela e seria recusado no envio. Prévia e envio de teste A prévia é renderizada no servidor, por canal, e mostra apenas os canais que a conta realmente tem. Ela também exibe o modelo resolvido para fora da janela, com os valores que cada parâmetro vai carregar. O Enviar teste manda a mensagem para uma conversa escolhida, respeitando a janela de 24h: se a janela estiver fechada e não houver modelo configurado, o teste é pulado com o motivo escrito na tela. Variáveis O seletor lista só o que resolve naquele contexto. Dados de contato, conta, conversa, caixa de entrada, agente, CRM e organização agora renderizam de verdade (antes saíam em branco), além dos dados do evento de comércio que originou o card. Dicas, limites e boas práticas - Os corpos são Markdown e cada canal mostra o que suporta: anexos são descartados em LINE, TikTok e X; HTML bruto some no e-mail e no widget; *negrito* no WhatsApp aparece como um par de asteriscos. A prévia deixa isso explícito para você não escrever algo que só funciona num canal. - Personalize primeiro o idioma principal do seu público e só depois os demais — o contador "N de M" ajuda a acompanhar a cobertura. - Configure o modelo fora da janela no mesmo idioma do corpo: são pares, não uma configuração única. - Depois de "Criar a partir do meu texto", o modelo fica aguardando aprovação na Meta — use Sincronizar da Meta para ver quando ele for aprovado e passar a entregar. Solução de problemas - A mensagem saiu no texto padrão: o estágio estava com o selo Padrão (vazio) naquele idioma, ou o contato está num idioma sem texto e o fallback caiu no padrão embutido. - Fora da janela não enviou: confirme que há um modelo aprovado configurado para aquele estágio e aquele idioma. - O modelo aparece sinalizado: ele está num idioma diferente do card — troque por um modelo aprovado no idioma certo. - "Criar a partir do meu texto" está desabilitado: o motivo aparece escrito ao lado do botão — a caixa não é WhatsApp Cloud (em 360dialog você escolhe um modelo já aprovado), a conta não tem o WhatsApp Inbox Suite, seu perfil não gerencia caixas de entrada, ou não há texto naquele estágio e idioma para gerar o modelo. - Criei o modelo, mas ele não aparece / não é usado: logo após o envio ele fica aguardando aprovação — só entrega depois que a Meta aprovar e você usar Sincronizar da Meta. E confirme que clicou em Salvar mensagens: criar o modelo não grava a configuração. - Não encontro um modelo na lista: modelos com cabeçalho de mídia ou com variável no cabeçalho não são listados aqui; use-os pela aba Modelos da própria caixa de entrada. - O envio de teste foi pulado: a conversa estava fora da janela de 24h e o card não tinha modelo configurado — a tela informa o motivo. Veja também - Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify - WhatsApp Inbox Suite: Templates, Flows e Chamadas
Recuperação de vendas: entrega do card, política de conversa e métricas
Visão geral A Recuperação de vendas é a camada que garante que um evento de comércio sempre vire uma ação visível. Antes, o card de recuperação podia morrer em silêncio: se o cliente não tinha conversa aberta, ou se a mensagem caía fora da janela do WhatsApp, nada acontecia e ninguém ficava sabendo. Agora, todo evento de ciclo de vida — vindo de Kiwify, Hotmart, Nuvemshop ou do gateway nativo (Asaas / Mercado Pago) — passa por três garantias: 1. Um resolvedor de conversa decide para onde o card vai, com uma política que você escolhe. 2. Uma guarda de janela de envio verifica se o canal aceita a mensagem naquele momento. 3. Um resultado de entrega é registrado em todos os caminhos de saída: enviado, ignorado ou falhou, sempre com um motivo legível. O resultado prático: você abre a página Recuperação de vendas e vê quantas oportunidades foram alcançadas, quantas não foram e exatamente por quê — em vez de descobrir semanas depois que uma cadência inteira nunca saiu. Quando cada estágio dispara | Estágio | Dispara quando | Acionável? | |---|---|---| | Carrinho abandonado | o cliente montou o carrinho/checkout e não concluiu | Sim | | Pagamento pendente | PIX ou boleto foi gerado e ainda não foi pago | Sim | | Pagamento recusado | o cartão foi negado pelo emissor ou pelo antifraude | Sim | | Vencido | a data de vencimento passou sem pagamento | Sim | | Pedido criado | o pedido foi registrado na plataforma, ainda pendente | Não (não liquida) | | Pagamento confirmado | o pagamento foi aprovado | Não (liquidação) | | Reembolsado | o valor foi devolvido ao cliente | Não | | Chargeback | o cliente contestou a cobrança no emissor | Não | | Assinatura atrasada | a renovação da assinatura falhou ou está em atraso | Não | | Assinatura cancelada | a assinatura foi encerrada | Não | Os quatro estágios acionáveis são os que entram na conta da taxa de recuperação. Reembolso e chargeback nunca contam como recuperação — são o oposto disso. due_soon continua sendo um valor armazenado válido por compatibilidade, mas nenhum conector ou gateway nativo atual o produz. Por isso ele não é oferecido na recuperação automática nem no seletor de Follow-up. Pré-requisitos - A funcionalidade Recuperação de vendas (commerce_recovery) habilitada na conta. Ela vem desligada por padrão; peça a ativação a quem administra a instalação. - Perfil de administrador ou de agente na conta. Ambos podem abrir a página de recuperação, alterar políticas e reenviar cards — não existe permissão separada por módulo aqui. - Pelo menos uma fonte de comércio conectada (Kiwify, Hotmart, Nuvemshop) ou um gateway nativo configurado (Asaas / Mercado Pago), para que os eventos cheguem. - Para envio fora da janela do WhatsApp: um template aprovado na caixa de entrada correspondente. Sem a funcionalidade ligada, a nova página, o painel lateral e as métricas ficam ocultos. A entrega em si (política de conversa, resultado registrado) continua funcionando nos bastidores — é infraestrutura de comportamento preservado. Passo a passo 1. Abra Recuperação de vendas no menu do módulo de comércio. 2. Confira o funil acionável por estágio: ele usa os mesmos quatro estágios das métricas de tentativas e recuperações; liquidações, reembolsos e cancelamentos não entram nesse funil. 3. Olhe o bloco de entrega: enviado, ignorado, falhou e não tentado. 4. Abra a lista de motivos — ela vem ordenada do mais frequente para o menos frequente. É a sua lista de correção, em ordem de impacto. 5. Clique em um evento para ver o card, a conversa de destino e o histórico de entrega. 6. Se o card não saiu por um motivo já corrigido (canal reconectado, template aprovado), use Reenviar. Se precisar passar por cima da guarda de duplicidade, marque forçar. 7. Ajuste a política de conversa na ação de automação/macro para que o próximo evento do mesmo tipo não caia no mesmo motivo. Configurações & opções A política de conversa (a escolha mais importante) Quando o card precisa ser entregue, a plataforma precisa saber em qual conversa escrever. Você tem três opções: | Política | O que faz | Quando usar | |---|---|---| | Usar uma conversa existente (padrão) | Entrega na conversa mais recente do contato. Nunca cria uma conversa. Se não houver nenhuma, o card é ignorado com o motivo no_conversation. | Padrão seguro — é exatamente o comportamento de hoje. Nada muda para quem já usa. | | Criar uma se necessário | Usa a conversa existente quando há uma; cria uma nova quando não há. | Quando você quer alcance máximo e aceita que uma conversa nova apareça para o cliente. | | Somente esta conversa | Entrega estritamente na conversa em que a regra foi disparada. Nunca procura outra, nunca cria. | Quando o card só faz sentido no contexto daquele atendimento específico. | Por que "criar uma se necessário" é opt-in: criar uma conversa é uma ação visível para o cliente e para a fila do time. Ela aparece no inbox, conta nos relatórios e pode gerar notificação. Por isso Conversa Labs nunca faz isso por conta própria — você precisa escolher. A janela de 24 horas do WhatsApp (sem meias-verdades) O WhatsApp só permite mensagem livre dentro de 24 horas desde a última mensagem do cliente. Fora dessa janela: - Sem template aprovado → o card é ignorado, com o motivo whatsapp_window_closed. Ele não é entregue. Conversa Labs prefere registrar a razão a enfileirar uma mensagem que o WhatsApp vai rejeitar. - Com template aprovado → a entrega degrada para a mensagem única do template. Você recebe o contato, mas não o card rico completo: apenas o que o template aprovado permite. WhatsApp Web não tem janela. Caixas de entrada WhatsApp Web entregam normalmente a qualquer momento — a restrição de 24h é da API oficial do WhatsApp Business, não da plataforma. Exceção: par híbrido. Se você tem um par híbrido com Cloud como principal e roteamento de fora da janela para o WhatsApp Web, o envio sai completo por sessão do Web — não vira template nem é pulado. Nesse caso não espere ver whatsapp_window_closed. Outros canais O card sempre inclui o link de pagamento no corpo da mensagem, nunca só em anexo. Isso é deliberado: LINE, TikTok e X (Twitter) descartam ou rejeitam anexos. Se o link viajasse apenas no anexo, o cliente receberia uma mensagem sem a única coisa que importa. Entrega dos cards e a fila de "não tentado" O painel mostra a repartição da entrega — enviados, ignorados, com falha e não tentados. O balde "não tentado" é o que nunca teve card algum: nenhuma regra agiu sobre aquele evento. Ele deixou de ser um número solto: agora dá para filtrar por ele na linha do tempo e enfileirar os pendentes em lotes limitados, do mais antigo para o mais novo, até 50 por vez. A ação responde aceito/enfileirado, não uma contagem de entregas. O processamento acontece em segundo plano e os resultados reais (enviado, ignorado ou falhou) aparecem depois na linha do tempo. Ela nunca abre uma conversa nova: um evento sem destino fica registrado como ignorado com o motivo correspondente. Histórico importado ou adotado de gateway fica sempre fora dessa fila. Por que "Recuperações tentadas" pode aparecer como 0 com a lista cheia. A conta considera só os eventos acionáveis cujo card foi registrado como enviado. Se nenhum card foi enviado, o denominador é zero — não é a página quebrada, é a informação de que ninguém foi abordado ainda. Recuperação automática por estágio (desligada por padrão) Em Mensagens → Recuperação automática por estágio, ligue apenas os estágios ao vivo que você quer que o Conversa Labs enfileire automaticamente. Todos os controles começam desligados. O evento imediato enfileira o card, e um backstop a cada cinco minutos repara uma passagem perdida para a fila. Os dois caminhos conferem o controle novamente antes da entrega, reutilizam uma conversa existente, respeitam a janela de 24h do WhatsApp e adiam quando o limite seguro de envio da conexão está cheio. Cobranças importadas ou adotadas são histórico: continuam visíveis para auditoria e relatórios, com o selo Histórico — envio bloqueado, mas são excluídas de qualquer envio ao cliente. Recuperação automática, dreno manual, backstop, Follow-up, reenvio forçado, automações e Maestro não atravessam essa proteção. Ordem das mensagens do card O card é uma sequência: resumo → botão de pagar → PIX copia-e-cola → QR Code → boleto → linha digitável. Essa ordem agora é garantida na entrega — antes cada mensagem saía por conta própria e podiam chegar embaralhadas (o código PIX cru chegando antes da mensagem que manda copiá-lo). Em Mensagens → Entrega você define o intervalo entre as mensagens do card. Deixe em branco para usar o padrão do canal: no WhatsApp conectado por celular (WazMeow) é 1 segundo, para espaçar a rajada e não parecer disparo automático; nos demais canais não há pausa. Abrir a conversa e reenviar Cada linha ao vivo da lista tem Abrir conversa (vai direto para o atendimento daquele cliente) e Reenviar card. O reenvio mira a conversa pelo identificador público — nunca corre o risco de cair no cliente errado. Se o evento ainda não tem conversa, o diálogo avisa antes de confirmar que uma conversa será aberta com o cliente. Linhas históricas não exibem reenvio e a API também recusa a ação, mesmo com forçar. Casos de uso - PIX pendente que esfriou: o cliente gerou o PIX ontem e sumiu. O card reenvia o código na conversa existente, sem criar ruído novo. - Recusa de cartão em massa: uma emissora derrubou várias transações. Você filtra por payment_declined, vê que todas foram ignoradas por channel_unavailable, reconecta o canal e reenvia em lote. - Carrinho abandonado de quem nunca falou com você: contato novo, sem conversa. Com a política "criar uma se necessário", o card abre a conversa e inicia o atendimento. - Auditoria de cadência: a lista de motivos mostra que 60% dos envios morreram em whatsapp_window_closed — o sinal claro de que aquela cadência precisa de template aprovado. Dicas, limites e boas práticas Os resultados de entrega e o que fazer com cada um Todo evento termina em um destes estados: enviado, ignorado, falhou — ou não tentado, quando nenhuma regra agiu sobre ele. | Motivo | O que significa | O que fazer | |---|---|---| | no_contact | O evento chegou sem um contato identificável (a plataforma de origem não enviou telefone/e-mail utilizável). | Verifique o mapeamento de identificação na fonte de comércio. Sem contato não há para quem enviar. | | no_conversation | O contato existe, mas não há conversa para receber o card e a política é "usar uma conversa existente". | Se quer alcançar esses casos, mude a política para criar uma se necessário. | | no_channel_inbox | Não existe caixa de entrada do canal pedido pela ação. | Conecte a caixa de entrada daquele canal, ou aponte a ação para uma caixa que exista. | | whatsapp_window_closed | Fora da janela de 24h e sem template aprovado. | Anexe um template aprovado à ação. Ou desloque a cadência para dentro da janela. | | throttled | O limite de envio do canal foi atingido naquele momento. | Espace a cadência. Rajadas grandes em WhatsApp também aumentam risco de bloqueio. | | channel_unavailable | O canal está desconectado, expirado ou indisponível. | Reconecte a caixa de entrada e reenvie os eventos afetados. | | sequence_not_published | A sequência de Follow-up ainda está em rascunho. | Publique a sequência. Rascunho nunca envia — é proposital. | | already_sent | A guarda de duplicidade barrou: esse evento já teve card registrado como enviado. | Nada, na maioria dos casos. Se precisa mesmo reenviar, use Reenviar com forçar. | Integrando com sistemas externos Cada resultado de entrega — enviado, pulado ou falhou — também sai como o evento de webhook de conta commerce_card_delivery, com o motivo canônico junto. É por ele que um sistema externo (n8n, CRM) reage sem ficar consultando: por exemplo, abrir uma tarefa quando o motivo for no_conversation, ou tentar outro canal quando for whatsapp_window_closed. Ative-o em Configurações → Integrações → Webhooks. A guarda de duplicidade e o reenvio explícito Um mesmo evento cria e despacha localmente o card uma vez. Se uma automação e uma macro tentarem enviar o mesmo card, a segunda é ignorada com already_sent — essa é a guarda local de duplicidade. A entrega final do provedor ainda precisa ser conferida no estado da mensagem/conversa do canal. O reenvio é sempre explícito e humano: você abre o evento e clica em Reenviar. Ele preserva o registro do primeiro envio (data e mensagem originais) e apenas incrementa o contador de reenvios — o histórico nunca é apagado. Para atravessar a guarda de propósito, marque forçar. Como ler a taxa de recuperação (com honestidade) A taxa de recuperação é a proporção de tentativas acionáveis registradas como enviadas que receberam uma liquidação posterior atribuível ao mesmo contato e ao mesmo pedido. Com precisão: - Denominador: eventos acionáveis (carrinho abandonado, pendente, recusado, vencido) cujo card foi registrado como enviado. - Numerador: liquidações posteriores com o mesmo contato, a mesma origem e o mesmo identificador externo do pedido/cobrança. Pagar outro pedido não recupera o primeiro. - Uma liquidação conta uma única vez. Se o mesmo pedido recebeu vários cards acionáveis, ela é atribuída deterministicamente à tentativa registrada como enviada mais recente anterior à liquidação. Pedido criado nunca liquida receita: somente payment_confirmed entra no numerador. - Eventos cujo card nunca foi registrado como enviado ficam fora dos dois lados. O estado enviado confirma a criação e o despacho local do card; ele ainda não é um recibo final do provedor. - Quando nada foi tentado no período, a taxa aparece como —, não como 0%. Zero por cento significaria "tentamos e falhamos"; travessão significa "não houve tentativa". Isto é correlação, não causalidade. A métrica diz "o cliente pagou depois de a gente falar com ele", e não "o cliente pagou porque a gente falou com ele". Parte dessas pessoas pagaria de qualquer forma. Use o número para comparar cadências entre si e acompanhar tendência — não o apresente como receita atribuída a uma campanha. A receita recuperada usa o valor e a moeda da liquidação, não o valor que aparecia no card. Os totais são exibidos separadamente por moeda — por exemplo, BRL e USD nunca são somados nem rotulados como se tudo fosse BRL. Valores monetários permanecem na unidade principal da moeda e não há conversão escondida. Quando a origem não informa a moeda, a interface deixa essa ausência explícita. Solução de problemas - "Não tentado" em muitos eventos: nenhuma regra está agindo sobre aquele estágio. Crie uma automação ou uma sequência de Follow-up para o estágio em questão. - Tudo ignorado com no_conversation: sua base é de contatos sem conversa aberta e a política é a padrão. Mude para criar uma se necessário — lembrando que a conversa nova é visível ao cliente. - Tudo ignorado com whatsapp_window_closed: a cadência está rodando fora da janela de 24h. Aprove um template e anexe-o à ação, ou antecipe o disparo. - Card entregue, mas “pobre”: você está fora da janela com template. É o comportamento correto — o WhatsApp só aceita o template aprovado nessa situação. - channel_unavailable intermitente: a caixa de entrada está caindo. Verifique a conexão do canal antes de reenviar em lote, senão os reenvios falham pelo mesmo motivo. - O cliente recebeu duas vezes: verifique se há uma automação e uma sequência de Follow-up cobrindo o mesmo estágio, ou se alguém usou forçar no reenvio. - A taxa aparece como “—”: nenhum card de recuperação foi registrado como enviado no período filtrado. Amplie o período ou verifique a lista de motivos. - A página não aparece: a funcionalidade commerce_recovery está desligada na conta, ou seu usuário não é administrador nem agente nela. Veja também - Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify - Visão geral de Catálogo & Comércio - Enviar produto e receber pedidos na conversa
Operar a fila de recuperação: responsável, desfecho, notas e ignorados
Visão geral A linha do tempo de Recuperação de vendas separa dois conceitos: - Entrega do card informa se a mensagem foi enviada, pulada ou falhou. - Desfecho operacional informa se a oportunidade terminou como recuperada ou perdida. Você também pode definir um responsável, registrar uma nota interna e ignorar uma oportunidade que não deve receber novas ações. Esses dados são operacionais: eles não alteram o estágio vindo do gateway, o valor, a liquidação nem o histórico de entrega. Pré-requisitos - A funcionalidade Recuperação de vendas habilitada na conta. - Permissão para gerenciar Comércio na conta. - Um evento de comércio já registrado na linha do tempo. Passo a passo 1. Abra Comércio → Recuperação de vendas. 2. Encontre o evento pelos dados exibidos do cliente, e-mail/telefone, identificador externo, origem, estágio e valor. Esses dados dão contexto mesmo quando ainda não existe uma conversa. 3. Se o cliente estiver ausente ou errado, use Corrigir cliente e vínculos da venda. Selecione um contato existente ou proponha um novo, revise cobrança e pedido relacionados e aplique somente após a prévia. 4. Selecione Gerenciar. 5. Em Responsável, escolha um agente da própria conta ou deixe sem responsável. 6. Em Desfecho, escolha Recuperada, Perdida ou deixe sem desfecho enquanto o trabalho continua. 7. Escreva uma nota operacional, se necessário, e salve. 8. Para retirar o evento das ações automáticas, selecione Ignorar e confirme. 9. Para voltar a trabalhar nele, abra-o novamente e selecione Reabrir oportunidade. 10. Para agir sobre várias oportunidades de uma vez, marque as caixas das linhas — ou use Selecionar esta página e Selecionar todas destes filtros — e escolha Tirar da recuperação, Devolver à recuperação ou Enviar card na barra de ações. Cada ação confirma antes, e o que for recusado aparece com o motivo e continua selecionado para você tentar de novo. Configurações & opções Desfecho O desfecho é terminal e manual: | Valor | Uso | |---|---| | Sem desfecho | a oportunidade ainda está aberta ou não foi avaliada | | Recuperada | a equipe confirmou a recuperação operacional | | Perdida | a equipe encerrou a tentativa sem recuperação | O desfecho não substitui a métrica financeira, que continua baseada na liquidação correlacionada. Responsável Somente usuários que pertencem à mesma conta podem ser escolhidos. Remover o responsável devolve o evento à fila sem atribuição. Nota operacional A nota aceita até 2.000 caracteres, remove espaços vazios nas pontas e é interna. Não coloque senhas, tokens, dados de cartão ou outros segredos. A auditoria registra que a nota mudou, nunca copia seu texto. Cliente e vínculos da venda A correção alinha contato, cobrança, pedido e recuperação em uma transação única. Ela pode atualizar organização, negócio e conversa, mas nunca altera estágio, valor, liquidação ou identificador externo. Se houver impacto em vendedor ou afiliado, a prévia exige confirmação auditada. Em eventos históricos, a correção cria apenas projeções internas e não envia card, mensagem, automação ou conversão externa. Ignorar e reabrir Ignorar é reversível. Enquanto ignorado, o evento: - continua visível, com o histórico preservado; - não entra na fila de cards pendentes nem na cadência automática; - não é usado como a oportunidade acionável mais recente do contato; - recusa novos envios e registra o motivo operacional quando houver tentativa por integração. Reabrir remove apenas o bloqueio. Responsável, desfecho, nota, estágio e entregas anteriores permanecem. Casos de uso - Distribuir carrinhos abandonados entre agentes sem criar negócios artificiais no CRM. - Marcar como perdida uma cobrança cuja negociação terminou fora da plataforma. - Ignorar um evento de teste ou uma oportunidade que o cliente pediu para não receber novamente. - Reabrir um evento ignorado por engano sem perder a anotação anterior. Dicas, limites e boas práticas - Use o desfecho para decisão humana e a métrica de receita para liquidação observada; não misture os dois. - Escreva notas curtas e factuais. Dados pessoais na nota seguem as regras de exportação e anonimização da conta. - Ignorar não apaga o evento e não estorna nada. Para corrigir cliente ou associações, use Corrigir cliente e vínculos da venda; para fatos financeiros, use a operação correspondente em Pagamentos. - Antes de ignorar, confira se a origem não é apenas uma falha de canal que pode ser corrigida e reenviada. Solução de problemas - O responsável não aparece: confirme que o usuário ainda pertence à conta. - Não consigo salvar a nota: reduza o texto para no máximo 2.000 caracteres. - O card não é enviado: verifique se o evento está ignorado; reabra-o antes de tentar novamente. - O evento não mostra cliente ou aponta para o contato errado: abra Corrigir cliente e vínculos da venda, resolva o contato e revise a prévia completa. Nada é enviado ao cliente durante esse reparo. - O desfecho não mudou a receita recuperada: isso é esperado; a receita usa liquidação correlacionada, não o desfecho manual. - Recebi erro de permissão: o perfil precisa da permissão de gerenciamento de Comércio. Veja também - Recuperação de vendas: entrega do card, política de conversa e métricas - Reconciliação de vendas
Central de reconciliação de vendas
Visão geral A Central de reconciliação reúne registros históricos com vínculos ausentes ou divergentes entre cobranças, pedidos do CRM e eventos de comércio. A verificação automática só sugere relações com identidade exata; nomes, valores ou datas parecidos nunca unem vendas. Além de confirmar a contraparte da venda, a ação Corrigir cliente e vínculos da venda alinha o contato, a organização, o negócio e, quando solicitado, a conversa, o vendedor e o afiliado em todo o grafo. Ela não importa dinheiro nem altera valor, status, liquidação, datas ou identificadores do gateway. Um contato novo é apenas proposto na prévia e só nasce após a confirmação final. Pré-requisitos - O módulo Recuperação de vendas precisa estar habilitado para a conta. - Você precisa da permissão de gestão de Comércio. - As integrações e importações históricas já devem ter trazido os registros que deseja revisar. Passo a passo 1. Abra Recuperação de vendas no menu comercial e selecione a aba Reconciliação. 2. Clique em Executar verificação. A análise é enfileirada; ela pode levar alguns instantes em contas com muito histórico. 3. Atualize a lista. Filtre por situação, tipo de origem, motivo ou ID de origem. Cada linha reúne cliente, e-mail/telefone, organização, negócio, responsável ou criador, afiliado, conversa e os principais fatos da origem disponíveis. Campos protegidos podem aparecer mascarados ou ocultos conforme seu perfil. 4. Abra um item pendente. Só use Vincular quando a sugestão mostrar a mesma origem de gateway e o mesmo identificador externo. 5. Quando o cliente estiver ausente ou divergente, escolha Corrigir cliente e vínculos da venda na própria linha da fila, na cobrança, no pedido ou no evento. Selecione um contato existente ou proponha um novo com nome e e-mail, telefone ou documento. Decida também como tratar uma conversa incompatível. 6. Revise a prévia completa: registros alcançados, alterações, conflitos, projeções históricas e impacto em crédito/comissão. Confirme o impacto de atribuição quando houver e aplique. Se algum registro mudar entre a prévia e a confirmação, a operação é recusada inteira e você precisa revisar novamente. 7. Confirme o vínculo. A fila registra a decisão, o responsável e a data. 8. Se o registro não for uma venda da conta, escolha Ignorar e informe um motivo quando útil. 9. Use Desfazer se a decisão ainda precisar ser revertida. A plataforma só desfaz quando o vínculo continua exatamente como foi gravado, para não substituir uma alteração mais recente. Configurações & opções - Pendente: precisa de revisão humana. - Vinculado: a relação entre registros existentes foi confirmada. - Ignorado: a conta decidiu que o item não deve voltar à fila. Para cobranças, a exclusão também é respeitada por importações e webhooks futuros. - Duplicado: reservado para consolidações de registros equivalentes. - Ações em massa: é possível ignorar ou desfazer itens acionáveis selecionados. Selecionar todos os itens acionáveis destes filtros percorre todas as páginas, pula decisões que não admitem ação em massa e respeita o limite de 500 itens. O resultado mostra cada falha; uma seleção mista nunca é apresentada como sucesso total. - Filtros e ordenação: ficam no endereço da página, permitindo retomar ou compartilhar o mesmo recorte. - Correção do grafo da venda: usa uma transação única. Ou cobrança, pedido e recuperação ficam alinhados, ou nada é alterado. Projeções históricas ausentes são internas e não enviam mensagem, automação nem conversão externa. Ao concluir, todos os itens ainda pendentes dos registros alcançados são encerrados na fila; uma verificação posterior também encerra automaticamente um alerta já sanado. Casos de uso - Uma cobrança importada no Asaas já tem um pedido antigo com o mesmo ID de pagamento. - Um evento histórico da Hotmart ou Kiwify chegou antes do pedido correspondente. - Uma cobrança de teste, de outra empresa ou que não representa venda deve ser excluída de novas análises. Dicas, limites e boas práticas - Confirme sempre gateway + identificador externo. Nomes, e-mails, datas e valores parecidos não são prova suficiente de que duas vendas são a mesma. - A correção automática não associa contatos ou organizações por aproximação. Para um cliente sem correspondência exata, faça uma escolha manual explícita na prévia. - Use Corrigir cliente e vínculos para associações. Para valor, status, liquidação ou identificador do gateway, corrija a operação financeira ou a fonte de origem; esses fatos continuam imutáveis aqui. - Revise os itens pendentes antes de ignorá-los em massa. Cobranças ignoradas deixam de reaparecer até uma ação explícita de desfazer. - A reconciliação não cria receita nem comissão. Ela reutiliza as chaves canônicas dos registros existentes para que relatórios e créditos não sejam contados duas vezes. Solução de problemas - A fila está vazia: execute uma verificação e aguarde a conclusão; também confirme os filtros ativos. - Não há sugestão para vincular: não existe uma contraparte com identidade exata. Deixe o item pendente ou corrija/sincronize a origem. - Não consigo desfazer: alguém ou alguma integração alterou o vínculo depois da sua decisão. Revise o histórico em vez de sobrescrever a mudança. - A correção foi bloqueada por conflito: a mesma identidade externa aponta para mais de uma cobrança, pedido ou conversa incompatível. Resolva a duplicidade indicada e gere outra prévia; nada foi alterado. - A prévia ficou desatualizada: algum registro mudou antes da confirmação. Abra a correção novamente e revise o novo impacto. - Uma cobrança ignorada não volta: isso é esperado. Desfaça a decisão na própria fila antes de executar nova importação ou verificação. - Não vejo a aba Reconciliação: confirme a habilitação do módulo e a permissão de gestão de Comércio. Veja também - Registro de pedidos (Orders Registry) no CRM - Importar histórico de cobranças - Recuperação de vendas
Endpoint de ingestão de pedidos
Visão geral O registro de Pedidos aceita vendas vindas de fora da plataforma. Você recebe uma URL de ingestão própria da conta e envia cada pedido por POST — de um checkout próprio, de um ERP, de uma automação ou de um gateway que a Conversa Labs ainda não integre nativamente. A URL carrega um token opaco que identifica a conta. Não existe outro cabeçalho de autenticação: quem tem a URL consegue registrar pedidos na sua conta, então trate-a como senha. Pré-requisitos - O módulo Pedidos precisa estar habilitado na conta. Com ele desligado, a URL responde 404. - Perfil de administrador (ou permissão de gestão do CRM) para abrir e girar o token. Passo a passo 1. Abra Pedidos e clique em Endpoint de ingestão. 2. Copie a URL de ingestão. O campo Token aparece mascarado — use o olho para revelar e o botão ao lado para copiar apenas o token. 3. Cole a URL no seu sistema de origem e envie o pedido conforme o exemplo abaixo. 4. Confirme que o pedido apareceu na lista. Reenviar o mesmo external_id atualiza o pedido, não cria outro. curl -X POST 'https://SUA-INSTALACAO/public/api/v1/orders/ingest/SEU-TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "gateway": "meu_checkout", "external_id": "PED-10231", "email": "cliente@example.com", "title": "Plano Pro anual", "amount": 149.9, "currency": "BRL", "status": "paid", "ordered_at": "2026-08-11T10:00:00-03:00", "line_items": [ { "name": "Plano Pro anual", "quantity": 1, "unit_price": 149.9 } ] }' Campos do corpo | Campo | Obrigatório | O que é | |---|---|---| | gateway | Sim | Identifica a origem do pedido (ex.: meu_checkout, hotmart). | | contact_id / email / phone_number | Sim (um deles) | Referência para encontrar ou criar o contato. Envie também name para nomear um contato novo. | | external_id | Não, mas recomendado | O identificador do pedido no seu sistema. É o que torna o reenvio idempotente. | | status | Não | Um entre pending, partially_paid, paid, overdue, failed, canceled, refunded. | | amount e currency | Não | Valor total em unidades maiores (149.9 = R$ 149,90) e a moeda em ISO-4217. | | ordered_at e paid_at | Não | Datas ISO-8601 com fuso. Sem elas, vale o momento do recebimento. | | line_items | Não | Itens com name, quantity, unit_price e, quando houver, catalog_product_id, catalog_variant_id, discount e metadata. | | title, crm_item_id, affiliate_id, metadata, raw | Não | Complementos. O afiliado só é creditado se pertencer a esta conta e estiver ativo. | Respostas - 201 — {"status": "ok"}. Pedido registrado ou atualizado. - 422 — invalid_payload (falta gateway), contact_reference_required (falta a referência de contato), invalid_order_status (status fora da lista) ou contact_unresolvable (não foi possível encontrar nem criar o contato). - 404 — token ausente, já girado, ou módulo de Pedidos desligado na conta. Dicas, limites e boas práticas - Sempre envie external_id. Sem ele, uma reentrega do seu gateway vira um pedido duplicado. - O endpoint é limitado por taxa por token. Em cargas grandes, envie em série e trate 429 com espera progressiva. - Girar o token invalida a URL antiga na hora. Faça isso apenas com a integração pronta para receber a nova URL — e atualize-a imediatamente. - Valores vão em unidades maiores, com ponto decimal. Não envie centavos como inteiro. Solução de problemas - Recebo 404 em tudo: a URL foi girada ou o módulo Pedidos está desligado na conta. - Recebo 422 contact_reference_required: o corpo não trouxe contact_id, email nem phone_number. - O mesmo pedido aparece duas vezes: o envio saiu sem external_id, ou com um valor diferente a cada tentativa. - O afiliado não recebeu comissão: o affiliate_id não pertence a esta conta ou está inativo. Veja também - Central de reconciliação de vendas - Ciclo de vida do comércio
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. | 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 - Sincronização e WhatsApp Business Catalog - Ciclo de vida de e-commerce: webhooks Kiwify/Hotmart/Nuvemshop/Shopify