O Provei oferece dois runtimes de visualização. O runtime Fashion veste uma peça na foto enviada pelo cliente. O runtime Home visualiza um produto no ambiente do cliente e atende às famílias Móveis, Revestimentos e Pisos. A experiência disponível depende do produto provisionado para a conta e da correspondência com a página atual.
A interface é contextual: o runtime selecionado, a configuração da conta e os dados da página determinam o que o cliente pode fazer. Não há uma quantidade fixa de telas ou de ações para todos os produtos.
O endpoint de geração é/api/v2/widget-fashion/try-one a página do iframe usa/widget-v2-fashion/[userId].
O endpoint de geração é/api/v2/widget/composee a página do iframe usa/widget-v2/[userId].
Gates opcionais de identidade
Antes da seleção, a conta pode exigir login da loja ou captura de lead. Comauth_mode=none, o cliente segue sem esse gate;store_login observa o login da loja;lead_capture usa os campos e perguntas configurados; elead_capture_whatsapp combina a captura com a liberação da imagem pelo WhatsApp. Quando o gate está ativo, seleção, geração e resultado ficam disponíveis depois que a identidade exigida é concluída.
O User ID precisa ter o runtime correspondente liberado, a conta precisa estar provisionada para o tipo de produto e o produto deve estar ativo. O widget também verifica a disponibilidade comercial da conta, incluindo plano ativo e créditos, antes de exibir o launcher.
Quando auto_detect_url está habilitado, o runtime consulta/api/v2/widget/matchcom o User ID e a URL atual. O servidor procura um produto Home ativo para essa URL, confere o provisionamento da conta e resolve o modo permitido. Os valores técnicos sãofurniture,revestimento episos; na interface, eles aparecem como Móveis, Revestimentos e Pisos. O navegador não envia um override manual para escolher o modo.
Se a página não corresponder a um produto ativo ou a um modo provisionado, a resposta de match indica que não houve correspondência. Em geral, o botão é ocultado; porém, quandoshow_on_all_pages e button_enabled estão ativos, o launcher pode continuar visível. Isso não libera a experiência:open() e a geração continuam exigindo um produto correspondente. O runtime Home usa a URL canônica da página também quando a navegação acontece em uma SPA.
O runtime Fashion usa o matcher próprio de URL em/api/v2/widget-fashion/matche exige o produto Fashion correspondente à página. A geração usa o modo técnicofashion; a página não deve tentar substituir essa identificação com um tipo manual.
Para cadastrar vários produtos, abra Produtos › Adicionar produtos e escolha Vários por link ou Planilha. O fluxo atual cria um job assíncrono: as URLs são validadas, o tipo de produto é conferido contra o provisionamento da conta e o processamento continua em segundo plano.
await fetch("/api/v2/importacao", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
urls: [
"https://loja.exemplo/produtos/cadeira",
"https://loja.exemplo/produtos/sofa"
],
productType: "furniture",
filterImagesWithAI: true
})
})O endpoint aceita um array com pelo menos uma URL válida e até 50.000 URLs por importação. Esse é o limite do schema atual da rota.
fashion.furniture.revestimento.pisos.A requisição só é aceita quando o tipo está provisionado para a conta. A opção Selecionar melhores fotos e ângulos com IA envia filterImagesWithAI: true; desligada, envia false.
Acompanhe o job assíncrono
Uma criação aceita retorna 201 com o identificador do job. O painel consultaGET /api/v2/importacao/<id>imediatamente e depois a cada 5 segundos. A resposta pode vir diretamente ou emdata; os campos aceitos pelo painel usam camelCase ou snake_case.
pending,processing e termina em completed,failed oucancelled.itemStatus comopending,processing,success,partial oufailure.Resultado da importação
URLs com status success oupartial aparecem nos resultados do job; falhas permanecem identificadas por URL e mensagem quando o serviço a fornece. Depois da conclusão, use Ver catálogo (ou Produtos › Catálogo) para revisar os registros.
O produto precisa ter uma imagem de catálogo utilizável e a página precisa passar pelo matcher correspondente. As recomendações abaixo são para a foto enviada pelo cliente e para a referência visual de cada runtime.
A seleção da imagem de origem do cliente aceita JPEG/JPG, PNG, WebP, HEIC e HEIF, com limite de 10 MiB por arquivo(10 × 1024 × 1024 bytes). Esse é o limite da fonte escolhida pelo cliente: arquivos válidos entre 4 e 10 MiB não são rejeitados por tamanho nessa etapa.
Antes da submissão à API, o navegador converte HEIC e HEIF para JPEG e aplica recorte (crop) e compressão. O payload já processado pode obedecer a um teto de transporte/API de 4 MiB; esse teto não reduz o limite de seleção da fonte original. Se a conversão falhar, o cliente recebe uma mensagem para tentar outra foto; o arquivo original não é enviado como geração.
Recomende uma foto nítida, com uma única pessoa para Fashion ou com o ambiente visível para Home. Essas são orientações de qualidade, não novos limites de formato ou resolução.
No resultado normal, depois de uma geração concluída e fora do modo de liberação pelo WhatsApp, o runtime pode exibir as ações compatíveis com a experiência e a loja. Elas não são uma garantia de que toda plataforma terá o mesmo botão.
Salva a visualização gerada como uma imagem PNG quando o resultado normal está disponível.
Abre o compartilhamento da imagem e do texto do produto quando o navegador ou a plataforma da loja oferece essa ação.
Expande a imagem para inspeção. Em uma loja incorporada, a visualização é aberta pela galeria da página pai; fora de um iframe, o runtime abre seu próprio modal.
Quando a página e a plataforma permitem a integração, o resultado mostra Adicionar ao Carrinho; caso contrário, usa a CTA configurada ou redireciona para a referência do produto. Fashion pode pedir a escolha de uma variante antes de adicionar ao carrinho.
Overlay de liberação pelo WhatsApp
Quando a configuração usaauth_mode=lead_capture_whatsappe há um telefone de WhatsApp configurado, o resultado é coberto pelo overlay Liberar foto pelo WhatsApp. O cliente clica no botão para receber a imagem no WhatsApp da loja; nesse modo os controles normais da imagem ficam ocultos, permanecendo disponível a possibilidade de tentar uma nova visualização.
Escolha o tema em Experiência na loja › Provador. A configuração visual do runtime aceita os temas técnicosdefault,light,dark eminimal. O tema altera cores, contraste, bordas e alguns detalhes de apresentação; não altera a identificação do produto, os guards de provisionamento nem o endpoint de geração.
Nos temas default e dark, a Cor principal (em Experiência na loja › Marca) define a cor exata dos botões, ícones, textos e bordas de destaque, sem clareamento ou degradê. Os fundos de apoio permanecem neutros. A opção Cor ao passar o mouse permite configurar o hover de forma independente. Ao restaurar o hover automático, o widget usa um tom mais escuro da cor base, sem alterar a cor escolhida para os demais destaques.
defaultTema padrão com a cor de destaque configurada.
lightTema claro para superfícies luminosas.
darkTema escuro para interfaces de alto contraste.
minimalApresentação reduzida, sem acentos visuais extras.
Se o produto não aparecer, confirme primeiro o User ID, o provisionamento do modo, o status ativo do produto e a URL canônica. Para Home, lembre que a resolução defurniture,revestimento oupisos acontece no servidor.
Nossa equipe pode ajudar a conferir o provisionamento, a URL do produto e a configuração do runtime mais adequado para sua loja.