Combora — Manual do utilizador

1O que é a Combora

A Combora cria pacotes e ofertas automáticas na sua loja Shopify: agrupa produtos, aplica o desconto correto no carrinho e no checkout, e mostra a oferta no seu tema através de blocos já prontos. Você configura a oferta no admin, e o desconto é calculado por uma Shopify Function dentro do próprio checkout — o preço cobrado é o que a própria plataforma calcula, não um script no navegador.

Existem 8 tipos de pacote. Esta tabela ajuda a escolher:

Se estiver indeciso entre tipos, a própria app tem um guia: em Criar pacote, a ligação "Não sabe qual escolher?" abre um assistente, e cada tipo tem um painel "Ver como funciona" com exemplos.

2Primeiros passos

2.1 O que a app cria ao instalar

Instalar a Combora não altera nada visível na sua loja. Em segundo plano, a app prepara as estruturas de dados onde vai publicar os seus pacotes (metaobjects e metafields com o prefixo combora — o detalhe técnico está no anexo para programadores) mais um único desconto automático chamado "Combora" em Descontos, que é o que aplica todos os preços. Não o elimine nem o edite manualmente: a app mantém-o sozinha.

2.2 Ative o motor de presentes (app embed)

Se vai usar Presente por compra (ou combos com presente), ative o app embed Combora Gift: Loja online → Personalizar → Definições do tema → App embeds → Combora Gift. É o componente que adiciona e remove o presente do carrinho automaticamente. Sem ele, o desconto do presente continuaria correto, mas o produto-presente não se adicionaria sozinho.

2.3 Adicione os blocos ao seu tema

Cada tipo de pacote é mostrado na loja online através de um bloco de tema. Adiciona-os uma vez em Loja online → Personalizar, no template correspondente:

Não precisa de memorizar isto: cada editor de pacote tem um cartão "Onde isto aparece" que indica o bloco correto, mais uma ligação "Pré-visualizar no seu tema em direto" que abre o editor de temas com esse bloco já pronto para inserir no template correto.

3Visita guiada à app

A app está em Apps → Combora. O menu tem seis entradas — Início, Pacotes, Estatísticas, Planos, Ajuda e Definições — mais o chat de suporte, presente em todos os ecrãs:

Início

O ecrã de boas-vindas e o pulso da sua instalação. Enquanto ainda está a configurar, mostra uma lista de três passos — criar o seu primeiro pacote, publicá-lo e (se a sua oferta for um presente por compra) ativar o motor de presentes no seu tema. A lista não é decorativa: cada passo só se assinala quando aconteceu mesmo na sua loja, o botão de ação só existe no passo pendente, e se mais tarde despublicar tudo, a lista volta a refletir a realidade. Uma vez completa, o Início celebra com uma ligação direta para ver a sua loja (pode dispensar o aviso quando quiser).

Abaixo da lista: os seus pacotes mais recentes com o respetivo estado, uma faixa de atenção se um pacote precisar de revisão (por exemplo, porque arquivou um produto que o compunha — a app deteta isso sozinha e assinala-o sem despublicar nada), e uma faixa com o seu plano atual.

Pacotes

A lista de todos os seus pacotes: pesquisa por nome, filtro por estado (Publicado / Rascunho), ações por linha (duplicar, publicar/mover para rascunho, eliminar) e seleção múltipla com ações em massa. Tudo é criado a partir daqui com Criar pacote.

Estatísticas

Métricas de desempenho dos seus pacotes sobre encomendas reais: receita atribuída, % de encomendas com um pacote, poupança entregue, valor médio de encomenda e um gráfico ao longo do tempo. Detalhe na secção 17.

Planos

O seu plano atual e as opções de upgrade. O plano Gratuito permite 3 pacotes publicados em simultâneo; os planos pagos não têm limite (secção 18).

Ajuda

Perguntas frequentes e explicações dos conceitos (arbitragem entre pacotes, presentes, blocos).

Diagnóstico (um separador dentro de Ajuda)

O painel de saúde e suporte está como um separador dentro de Ajuda (seletor "Guias | Diagnóstico" no topo): verificações ao vivo de toda a instalação, o registo de eventos e o relatório de suporte que copia quando algo corre mal (secção 19).

Chat de suporte (balão flutuante)

No canto inferior direito de todos os ecrãs há um balão de chat 💬 para falar diretamente com o suporte: conversas por tema, histórico e um aviso sobre se o suporte está disponível ou ausente. Apenas o que você escreve é partilhado — nunca os dados dos seus clientes.

Definições

Idioma da app (7 idiomas), Design do widget (o modelo de estilo aplicado a toda a loja — secção 13), sincronização manual de descontos e acesso de programador.

4Anatomia do editor

Todos os tipos partilham o mesmo editor; só muda a secção de produtos e preço. Um pacote totalmente novo tem este aspeto:

4.1 Básico

Nome do pacote

Interno. Só você o vê; serve para o encontrar na sua lista.

Título na loja online

O que o cliente vê como nome da oferta no carrinho e no checkout. É traduzível. É também o texto da linha de desconto (limitado a 100 carateres).

Texto da insígnia

Uma insígnia curta opcional ("Melhor valor") que o seu tema pode mostrar em destaque.

4.2 Agendamento

Datas de início e fim opcionais. Vazio = a oferta entra em vigor ao publicar e nunca expira. Um pacote publicado fora da sua janela deixa de aplicar o desconto automaticamente e volta a aplicá-lo assim que regressa à janela, sem que tenha de mexer em nada.

4.3 Produtos

Consoante o tipo escolhido, seleciona produtos específicos (e, dentro de cada produto, pode marcar apenas algumas das suas variantes) ou uma coleção. O âmbito "qualquer produto da loja" só existe em presente por compra, como condição. O seletor é o padrão da Shopify:

4.4 Preço

Cada tipo tem a sua própria secção (percentagem, valor, preço fixo, níveis, recompensa…). Está documentado no capítulo de cada tipo. Em todos os casos, o preço cobrado é calculado pela Shopify no checkout a partir da configuração publicada: o que os blocos mostram é informativo.

4.5 Subscrições

Por defeito, um cliente não pode comprar um artigo de pacote como subscrição (isto protege o checkout de misturar o preço de subscrição com os descontos de pacote). Nos tipos onde faz sentido (combine e poupe, monte a sua caixa e presente por compra) há uma opção avançada, "Permitir subscrições neste pacote (avançado)"; ao ativá-la, o editor mostra um aviso a lembrar o que isso implica.

4.6 A barra lateral direita (e duas secções do corpo)

Além de Guardar (e Guardar como rascunho num pacote ainda não publicado), com a barra Alterações não guardadas / Guardar / Descartar no topo, o editor organiza o resto assim:

Estado + ação (barra lateral)

Publicar (ou Atualizar pacote se já estiver publicado) e Mover para rascunho. Publicar coloca a oferta ao vivo; mover para rascunho retira-a mantendo toda a configuração.

Modo de teste (corpo)

Marque "Publicar em modo de teste" para experimentar o pacote sem o expor aos seus clientes. Os widgets aparecem só no editor de temas — abra aí o modelo de produto e o pacote aparece exatamente onde vai ficar. Na sua loja nunca aparecem, nem sequer pela ligação de pré-visualização de um tema rascunho. Enquanto o pacote está em modo de teste, o desconto só é calculado para clientes com a etiqueta combora-test; para todos os outros, é como se o pacote não existisse. Para percorrer o checkout completo, adicione essa etiqueta ao seu próprio cliente de teste (Admin → Clientes) e inicie sessão como esse cliente na loja online. Desmarque a caixa e clique em Atualizar pacote e ele entra ao vivo, aplicando-se a quem cumprir as condições. Na lista, um pacote em modo de teste tem a insígnia Modo de teste.

Visibilidade no catálogo (corpo)

Apenas pacotes fixos: se o produto principal do pacote aparece ou não no seu catálogo (secção 5).

Antes de publicar (barra lateral)

A lista que bloqueia a publicação até que o essencial esteja pronto (título, produtos, preço…).

O que o seu cliente vê (barra lateral)

Enquanto a oferta ainda tiver algo em falta, este cartão explica o que falta e pré-visualiza o conteúdo. Assim que a oferta estiver completa, o cartão dá lugar à pré-visualização real do widget em Ver pré-visualização. O aspeto final depende do seu tema.

Estilo de pré-visualização (barra lateral, só em pacotes já criados)

Indica o design de widget ativo deste pacote e oferece Ver pré-visualização (o widget em tamanho real numa modal) e Personalizar design (o estúdio de design deste pacote: predefinições, ordem dos elementos e estilo por elemento — secção 13). Num pacote totalmente novo, aparece depois da primeira gravação.

Onde isto aparece (barra lateral)

O bloco de tema que renderiza este tipo e a ligação direta para o editor de temas.

Um pacote com agendamento mostra também a sua insígnia de janela (Agendado / Ativo / Terminado) e o botão Remover agendamento para voltar a "ativo ao publicar".

4.7 Avisos que o editor pode mostrar

• Sobreposição: se os produtos do pacote já estiverem noutros pacotes publicados, uma faixa avisa: "No checkout só se aplica a melhor oferta por linha: os pacotes não se somam". Não é um erro — é informação (ver secção 14).
• Sem poupança / preço 0: num pacote fixo com preço de pacote, se o preço escolhido não poupar nada (ou for 0), o editor assinala-o antes de publicar.
• Grupo vazio: uma coleção sem produtos elegíveis mostra uma nota na pré-visualização e, se tentar publicar, um erro com a explicação.

4.8 Editar um pacote publicado

Ao editar um pacote publicado, as suas alterações são guardadas sem chegarem à sua loja. O editor mostra a sua edição, os seus clientes continuam a ver a versão publicada ao preço publicado, e o pacote fica marcado como Alterações não publicadas na sua lista. Clique em “Atualizar pacote” para as publicar, ou descarte-as no aviso do editor. Assim pode preparar as alterações com calma. "Mover para rascunho" retira a oferta da loja online de imediato; publicar de novo repõe-a exatamente como estava.

5Pacote fixo

Um conjunto fechado de produtos vendido como uma única unidade. É o único tipo que também cria um produto comprável com um clique no seu catálogo: um produto "principal" (um pacote nativo da Shopify) cujos componentes se expandem automaticamente no checkout.

5.1 Configuração

1. Produtos: adicione os componentes (variantes específicas) e a quantidade de cada um. Máximo de 30 componentes por pacote.
2. Preço — dois modos mutuamente exclusivos:
   • Preço fixo do pacote: insere o preço total (por exemplo, $1,299.00). A poupança é calculada face à soma dos componentes.
   • Aplicar um desconto: uma percentagem ou um valor sobre a soma dos componentes.
3. Visibilidade no catálogo: os pacotes fixos são produtos reais da Shopify, por isso decide se o pacote também aparece no seu catálogo ou só é acessível a partir do widget:
   • Oculto — apenas a partir do widget (por defeito): o pacote não aparece em coleções, na pesquisa da loja online, nem em recomendações. A sua página de produto continua ativa para que o botão do widget funcione.
   • Visível — um produto normal do catálogo: aparece em coleções e na pesquisa como qualquer outro produto.
4. Publicar. Ao publicar, a Combora cria (ou atualiza) o produto principal no seu catálogo — e, se o pacote ainda não tiver imagem, copia-lhe a do primeiro componente, em AMBOS os modos de visibilidade (um pacote oculto continua a aparecer no carrinho, no checkout e nos emails da encomenda). Nunca substitui uma imagem que já tenha definido; pode alterá-la a qualquer momento em Admin → Produtos.

5.2 O que o seu cliente vê

5.3 Detalhes e limites deste tipo

• Os componentes devem ser variantes com stock; o produto principal herda a disponibilidade.
• O produto principal gere-se sozinho: mover o pacote para rascunho ou eliminá-lo retira-o da loja online (verificado ao escrever este manual). Não o elimine manualmente.
• Por defeito, o principal fica oculto do catálogo. Antes de essa opção existir, aparecia em /collections/all como um cartão sem imagem; os pacotes que já tinha publicados foram mudados automaticamente para "Oculto". Se preferir o comportamento antigo, mude para Visível.
• Máximo de 30 componentes. O preço fixo é repartido pelos componentes com arredondamento exato (a soma das partes é sempre igual ao total).
• O pacote fixo também se aplica se o cliente adicionar os componentes separadamente nas quantidades exatas — o checkout agrupa-os e desconta-os da mesma forma.

6Combine e poupe

O cliente escolhe pelo menos N artigos de um grupo e todo o grupo sai com desconto.

6.1 Configuração

1. Produtos: o grupo elegível pode ser produtos específicos — marcando, se quiser, apenas algumas variantes de cada um dentro do seletor — ou uma coleção (que se atualiza sozinha).
2. Quantidade: o número mínimo de artigos para se qualificar e, opcionalmente, um máximo (acima do máximo, os artigos extra pagam o preço integral).
3. Desconto: uma percentagem ou um valor, aplicado a todos os artigos elegíveis no carrinho assim que o mínimo é atingido.

6.2 O que o seu cliente vê

6.3 Detalhes deste tipo

• Um carrinho abaixo do mínimo não é bloqueado: o cliente paga o preço integral até se qualificar.
• Com um máximo definido, o seletor deixa de aceitar marcações ao atingir o limite e, no carrinho, só as primeiras unidades até ao máximo são descontadas.
• As quantidades contam por unidades: 3 unidades do mesmo produto elegível também se qualificam para um mínimo de 3.

7Desconto por volume

Níveis de preço por quantidade: "compre pelo menos 2 → 10%, pelo menos 4 → 20%". O nível é decidido por produto: a quantidade de cada produto elegível no carrinho determina o seu próprio nível, e o nível atingido aplica-se às unidades desse produto. Exemplo com "4+ → 20%": 4 unidades da mesma prancha → 20% de desconto nas 4; mas 2 unidades de uma prancha + 2 de outra → cada produto fica no nível de 2+ (10%), não no de 4+. As quantidades de produtos diferentes não se somam entre si.

7.1 Configuração

1. Produtos: produtos específicos ou uma coleção (tal como no mix). Se só quiser algumas variantes de um produto, marque-as dentro do seletor ao escolhê-lo.
2. Níveis: cada nível é "Compre pelo menos N" + um desconto (percentagem ou valor). Adicione quantos precisar com "Adicionar nível" (até 50).

7.2 O que o seu cliente vê

7.3 Detalhes deste tipo

• Só se aplica o nível mais alto atingido (os níveis não se somam).
• Os níveis podem misturar tipos de valor (alguns %, outros valor).
• Um valor de desconto fixo é repartido pelas linhas de forma proporcional e exata.

8Compre X, leve Y (BOGO)

Compre X unidades e as próximas Y unidades vêm com uma recompensa. A recompensa pode ser grátis (100%), uma percentagem, um valor de desconto ou um preço fixo por unidade.

8.1 Configuração

8.2 O que o seu cliente vê

8.3 Detalhes deste tipo

• A oferta repete-se em blocos inteiros: com "2+1", 6 unidades = 2 grátis; 5 unidades = 1 grátis.
• O bloco de tema que a renderiza é o Combora volume table (apresenta o "compre X leve Y" como uma tabela de poupança).
• A recompensa "preço fixo" cobra exatamente esse preço por cada unidade recompensada.

9Presente por compra (GWP)

Adiciona um produto-presente (a $0.00) automaticamente quando o carrinho cumpre a condição, e remove-o se deixar de a cumprir. É o tipo mais automatizado: o app embed Combora Gift gere o presente sem que o cliente faça nada.

9.1 Configuração

1. O presente: uma variante específica que se adiciona quando o cliente se qualifica.
2. Condição para desbloquear — quatro opções:
   • Por gasto mínimo: o carrinho atinge um valor (por exemplo, $1,000).
   • Por número de artigos: atinge N unidades.
   • Gasto e quantidade (ambos): são exigidos os dois.
   • Por ter uma combinação de produtos: uma lista específica de artigos (de 2 a 5; uma unidade de cada) que têm todos de estar no carrinho.
3. O que conta para a condição: qualquer produto da loja, produtos específicos ou coleções.

9.2 O que o seu cliente vê

A barra tem quatro estados e, desde o carrinho vazio, dá o nome do presente e do que conta: antes de o cliente começar, enuncia a regra ("gaste $1,000 nessa prancha e leve a cera grátis"), a meio caminho diz o que falta, ao ultrapassar o limite anuncia o presente pelo nome, e se o cliente o retirar à mão di-lo em vez de ficar em "a aplicar". Quando contam mais de três produtos, a barra diz produtos elegíveis e acrescenta um painel "Que produtos contam?" que os lista.

9.3 Detalhes e proteções deste tipo

• O próprio presente não conta para o gasto de qualificação.
• O limite é medido sobre o preço de tabela do que conta, não sobre o que o cliente acaba por pagar: outra oferta que desconte essas mesmas linhas nunca o consome. A barra, o presente automático e o checkout leem o mesmo número.
• Se o cliente remover o presente manualmente, a app respeita isso e não o volta a adicionar nessa sessão; a barra do carrinho diz exatamente isso ("Presente removido") em vez de ficar em "a aplicar".
• Se retirar a oferta (mover para rascunho, fim da janela) enquanto há carrinhos abertos que já tinham o presente, o motor remove sozinho essa linha órfã assim que o carrinho voltar a mudar — nunca se transforma numa cobrança.
• Se o presente ficar sem stock, a oferta simplesmente não o adiciona (não bloqueia a compra).
• Proteção contra cobrança: uma validação no checkout impede pagar por um presente que está assinalado como presente mas chegou com um preço — o cliente nunca paga por engano por um artigo marcado como presente. A validação atua só no checkout, nunca durante a navegação.
• Quando "o que conta" são coleções, a app resolve os produtos da coleção no momento da publicação (e atualiza-os todas as noites, ou de imediato se voltar a publicar — as duas velocidades da secção 4.3), pelo que a barra de progresso e o presente automático funcionam tal como com produtos específicos. A única exceção: uma coleção enorme (mais de ~150 produtos) não pode ser prevista a partir do navegador — a barra não é mostrada para essa oferta, mas o presente e o preço continuam corretos (o servidor decide-os).
• Um presente cujo "o que conta" seja qualquer produto da loja pode ser anunciado com o bloco Combora gift offer em todas as páginas de produto: ao escolher esse âmbito, o editor mostra a caixa de verificação "Mostrar esta oferta de presente em todas as páginas de produto". Desativada (por defeito), a oferta só é vista no carrinho — a barra de progresso e o presente automático funcionam da mesma forma; ativada, também é anunciada com um cartão em todas as páginas de produto (a oferta não tem produtos específicos para marcar, por isso o bloco lê-a a partir do índice publicado da loja). A exceção deliberada continua a ser a página do próprio produto-presente: um prémio não é um isco.

10Monte a sua caixa

O cliente enche uma caixa de tamanho fixo (por exemplo, 3 artigos) com o que escolher de um grupo. Cada caixa completa é cobrada com um desconto ou a um preço de caixa fechado.

10.1 Configuração

10.2 O que o seu cliente vê

Usa o mesmo bloco Combora mix & match e o mesmo seletor com contador da secção 6: "selecione 3", um contador de progresso, um CTA com a quantidade. A diferença está na matemática: aqui as caixas são cobradas por caixa completa — com uma caixa de 3, seis artigos são duas caixas; sete artigos são duas caixas mais um artigo ao preço integral.

10.3 Detalhes deste tipo

• Grupo elegível: produtos específicos (com as suas variantes, se marcar apenas algumas) ou uma coleção (o seletor visual aparece em qualquer âmbito, tal como no mix — com coleções, a lista é resolvida no momento da publicação e atualizada todas as noites).
• O preço de caixa é repartido pelos artigos de forma exata; com moedas de 0 casas decimais (JPY) ou de 3 casas decimais (BHD), a repartição respeita a moeda.
• Suporta a opção de subscrições (secção 4.5).

11Complementos (frequentemente comprados juntos)

Um produto principal sugere produtos complementares; se o cliente levar o conjunto, recebe um desconto. É o clássico "frequentemente comprados juntos" na página do produto.

11.1 Configuração

11.2 O que o seu cliente vê

11.3 Detalhes deste tipo

• O desconto aplica-se assim que o produto principal e pelo menos um complemento estão no carrinho; cobre as linhas do conjunto.
• O bloco também pode ser adicionado ao template do carrinho como um último incentivo de cross-sell.
• Os complementos sem stock aparecem desativados com o respetivo aviso, e nunca vêm pré-marcados.

12Combo

O tipo avançado: empilha duas ou mais sub-ofertas (de qualquer um dos outros tipos) num único pacote. A diferença chave face a publicar pacotes separados: dentro de um combo as sub-ofertas somam-se — o cliente pode obter o desconto de volume e o presente ao mesmo tempo.

12.1 Configuração

Cada linha expande no local com o chevron, e a sub-oferta é editada em linha: os seus próprios produtos, os seus próprios níveis ou recompensa. Cada sub-oferta só afeta os seus próprios produtos.

12.2 O que o seu cliente vê

Um combo não é anunciado como cartão no bloco Combora bundle: esse bloco lista pacotes fixos, que têm um preço e um botão, e um combo não tem nenhum dos dois. Cada sub-oferta é promovida pelo seu próprio bloco — a tabela de volume para uma sub-oferta de volume, a barra de presente para uma de presente — e o combo mostra o seu efeito completo no carrinho, onde cada parte atua com a sua própria insígnia: o desconto de volume nas suas linhas e o presente adicionado automaticamente a $0.00.

Medido na loja de demonstração num combo que soma "2 ou mais desta prancha → 15% de desconto" e "um gorro grátis assim que levar $900.00 dela": duas pranchas passam de $1,040.00 para $850.00 — os 15% e o gorro a $0.00 — e três passam de $1,540.00 para $1,275.00. Dois pacotes separados nunca fariam as duas coisas na mesma linha; dentro de um combo as sub-ofertas somam-se (secção 14).

12.3 Detalhes deste tipo

• As sub-ofertas somam-se dentro do combo, mas o combo compete como um todo contra os outros pacotes segundo a regra da melhor oferta por linha.
• O presente numa sub-oferta GWP usa o mesmo motor de adição automática do tipo presente.
• Limite de tamanho: o conjunto achatado de produtos do combo não pode exceder 50 entradas (o editor mostra-o: "Usa X de 50").
• O editor tem uma modal "Como funcionam os combos" com um exemplo guiado, e cada sub-oferta define "Produtos a que esta oferta se aplica" — uma sub-oferta sem produtos específicos mostra um aviso porque não vai conseguir precificar nada.
• Uma sub-oferta BOGO dentro de um combo oferece uma recompensa de percentagem ou valor (o "preço fixo por unidade" é exclusivo do BOGO autónomo).

13Desenhar o widget

Os blocos da Combora vêm com um aspeto que se adapta a qualquer tema, mas pode desenhá-los a partir da app, sem tocar em CSS: escolha um estilo, reordene e oculte elementos, e ajuste cores, tamanhos e formas elemento a elemento. Tudo com uma pré-visualização que usa o mesmo motor de renderização da sua loja online, por isso o que vê é o que é publicado.

13.1 Dois lugares onde se desenha

Um pacote que ainda não mexeu em nada mostra o aviso "Este pacote segue o modelo de widget da sua loja". Assim que escolher uma predefinição ali, esse pacote segue o seu próprio caminho.

13.2 Os estilos (predefinições)

Modelo da loja

Só no design de um pacote: segue o que definiu em Definições. É o valor inicial. Se ainda não houver modelo, aplicam-se as definições do bloco no editor de temas.

Editor de temas

Prevalecem as definições próprias do bloco no seu editor de temas (destaque, cantos, modo de estilo). Este é o comportamento clássico, o que tinha antes de o estúdio existir.

Combora

O aspeto trabalhado da Combora: um cartão com o seu próprio fundo, contornos e sombras. Consistente em qualquer tema.

Como o tema

Decoração mínima: a tipografia e as cores do seu tema dominam. Para temas com personalidade forte.

Sem estilo

Markup limpo, sem decoração, para o seu programador escrever o seu próprio CSS (editor de temas → CSS personalizado). Os pontos de ligação são a classe .combora-w e as variáveis --combora-*.

Personalizado

Abre os controlos abaixo: layout, estilo global e ajuste fino por elemento.

13.3 Layout: reordenar e ocultar

Com a predefinição Personalizado, aparece o Layout: uma lista dos elementos do widget que pode arrastar (ou mover com as setas) para mudar a sua ordem, mais um ícone de olho para ocultar os opcionais.

Os elementos dependem do tipo de pacote, porque cada tipo desenha um widget diferente:

13.4 Estilo global e ajuste fino

O Estilo global é o que muda todo o widget de uma vez: cor de destaque, fundo do cartão, cor do texto, cantos (aguçados / suaves / arredondados), sombra (nenhuma / suave / média) e densidade.

O Ajuste fino por elemento abre cada elemento em separado — título, preço, poupança, insígnia, botão, cartão, miniaturas, etiquetas — com o que fizer sentido para cada um: tamanho, peso, cor, maiúsculas, espaçamento, forma, cor do contorno, cor do preço riscado… Todos os controlos têm um "Voltar ao tema" para desfazer só esse ajuste, e no fundo há um "Repor toda a personalização".

• Se não definir a Poupança, esta segue o estilo da Insígnia.
• A cor do texto do botão não pode ser escolhida: é derivada automaticamente por contraste face ao fundo que escolher, para que nunca fique ilegível.
• Os valores têm limites sensatos: não pode inserir um tamanho que quebre o widget no telemóvel.

13.5 A pré-visualização (e o que ela NÃO é)

À direita há um painel identificado como "Apenas pré-visualização". A diferença importa:

• Esquerda = o seu design. O que ajustar ali é guardado e vai para a loja online.
• Direita = a lente. Fundo de pré-visualização (claro / escuro / uma cor personalizada), tamanho de texto base, largura do espaço (uma coluna de produto estreita vs. uma secção larga) e uma aproximação da sua tipografia. Existe para verificar se o seu design se aguenta em diferentes lugares. Não altera nada na sua loja nem no seu design.

E na barra lateral do editor de pacote, o cartão "Estilo de pré-visualização" diz qual o design ativo ("Design ativo: Combora") e oferece dois botões: Ver pré-visualização, que abre o widget em tamanho real numa modal ("É assim que vai ficar na sua loja"), e Personalizar design, que abre o estúdio deste pacote. A tipografia e o fundo reais vêm do seu tema, por isso, para a aprovação final, veja o widget no editor de temas.

14Combinar pacotes entre si

Pode publicar tantos pacotes quantos o seu plano permitir, mesmo sobre os mesmos produtos. As regras de coexistência são fixas e previsíveis:

1. A melhor oferta por linha. Para cada artigo do carrinho, a Shopify aplica a oferta que mais desconta esse artigo. Dois pacotes nunca se somam na mesma linha.
2. Pacotes diferentes podem coexistir no mesmo carrinho — cada um nas suas próprias linhas. Um desconto de mix nas pranchas e um presente por gasto podem aplicar-se ao mesmo tempo porque atuam em linhas diferentes.
3. Em caso de empate, ganha o pacote mais antigo (o primeiro que criou).
4. A exceção é o combo: as suas sub-ofertas somam-se entre elas (secção 12).

E os descontos que não são da Combora? A regra acima governa os packs da Combora entre si. Com descontos de terceiros manda a Shopify, e verificámo-lo numa loja real: dois descontos de produto (um pack da Combora e um desconto automático ou código de produto seu) nunca se somam sobre o mesmo artigo — a Shopify aplica apenas o maior dos dois, mesmo que ambos estejam marcados como combináveis; podem conviver em linhas diferentes da mesma encomenda. Um desconto de encomenda (por exemplo um código de −10% sobre toda a encomenda) subtrai-se depois, sobre os preços já descontados — o comportamento padrão da Shopify com qualquer app.

Um exemplo numérico real (verificado na loja)

Na loja de demonstração há um produto que pertence de propósito a dois pacotes: a prancha que é componente do pacote fixo é também o sujeito do pacote de volume. Sozinha leva o escalão de volume que a sua quantidade lhe der; junto com o outro componente do pacote fixo, nas quantidades exatas, o pacote fixo entra também como candidato e a linha fica com a melhor das duas. Mesmo produto, dois pacotes, um preço por linha — nunca os dois.

15Criação em massa

Na galeria Criar pacote há dois fluxos para criar muitos pacotes de uma vez. Ambos criam rascunhos: nada chega à loja online até rever e publicar.

15.1 Gerar a partir de uma coleção

1. Escolha a coleção.
2. Escolha o modelo: "Um multipack por produto" (um pacote fixo de N unidades para cada produto) ou "Um único pacote para toda a coleção".
3. Configure as unidades e o desconto, e depois clique em Criar rascunhos.

O que cada modelo cria realmente

Um multipack por produto percorre a coleção e cria um rascunho de pacote fixo por produto: N unidades da primeira variante desse produto (por ordem de posição), com o desconto que escolheu aplicado à soma. Cada rascunho é um pacote fixo normal — abra-o para mudar a variante, definir um preço de pacote fechado, adicionar uma insígnia… — e, ao publicá-lo, torna-se o seu próprio produto comprável com um clique, como qualquer pacote fixo (secção 5).

Um único pacote para toda a coleção cria exatamente um rascunho do tipo flexível que escolher (volume, combine e poupe, monte a sua caixa ou compre X leve Y) cujo grupo elegível é a própria coleção. A pertença segue o seu catálogo: o grupo é resolvido quando publica e atualizado todas as noites (ou de imediato ao republicar), pelo que os produtos que acrescentar à coleção mais tarde entram na oferta sem tocar no pacote.

Os produtos são ignorados — e a faixa de resultado avisa — quando não estão Ativos no seu catálogo, quando não têm nenhuma variante comprável — e quando são eles próprios produtos de pacote da Combora: um pacote gerado nunca aninha outro pacote.

Exemplos práticos

O mesmo ecrã, sete configurações e exatamente o que cada uma produz:

15.2 Importar de um CSV

Para catálogos grandes ou para migrar de outra app. A página inclui a referência completa do formato, um modelo descarregável com um exemplo por tipo e um botão de exportação (descarrega todos os seus pacotes no mesmo formato, prontos a reimportar noutra loja).

• Tipos importáveis: fixed, volume, mix_and_match, build_a_box, bogo (os tipos com presente, âncora ou sub-ofertas são criados no editor).
• Referências por handle de produto ou coleção, ou por GID da Shopify.
• Em components (só fixos): handle:quantity separados por |.
• Até 200 linhas por importação; um ficheiro maior é recortado e a app avisa.

16Gestão do dia a dia

16.1 A lista

Pesquisa por nome, filtro por estado e, em cada linha: Duplicar (cria uma cópia em rascunho), Publicar / Mover para rascunho e Eliminar. A data em cada linha é a última atualização (passe o rato para a dica).

16.2 Ações em massa

16.3 O ciclo de vida de um pacote

Rascunho

Invisível na loja online. Editável sem limites.

Publicado

A oferta está ativa (dentro da sua janela de agendamento). Editar não altera nada ao vivo até clicar em Atualizar pacote.

Mover para rascunho

Retira a oferta de imediato; a configuração fica intacta para poder republicar.

Eliminar

Elimina o pacote e retira o seu desconto (e o produto principal, se era um pacote fixo). Não pode ser desfeito. As estatísticas de encomendas passadas mantêm-se.

16.4 O que a Combora faz sozinha, enquanto você dorme

Quatro processos automáticos mantêm a sua loja atualizada sem que tenha de fazer nada. Não precisa de os configurar nem de os vigiar — estão documentados aqui para saber por que razão as coisas se resolvem sozinhas:

17Estatísticas

Se vende em várias moedas, um seletor de moeda fica junto às métricas: os valores monetários são mostrados na moeda escolhida (os contadores de encomendas são globais).

Abaixo das métricas há três gráficos para o intervalo escolhido, todos com uma marca por dia e uma dica:

• Encomendas com pacote ao longo do tempo — barras, com o valor impresso acima das barras que têm dados.
• Receita atribuída por dia — uma linha, para ver a tendência.
• Poupança entregue por dia — barras: quanto desconto os seus pacotes deram cada dia.

18Definições e planos

18.1 Definições

• Idioma da app: 7 idiomas (inglês, espanhol, francês, alemão, italiano, português, neerlandês). Afeta o admin; o que o seu cliente vê segue o idioma do seu tema/mercado.
• Design do widget: Editar modelo do widget abre o estúdio de design aplicado a toda a loja — o estilo que todos os pacotes herdam (secção 13). Guardar aqui volta a sincronizar os pacotes publicados.
• Sincronizar descontos: não precisa de clicar — tudo se sincroniza sozinho quando publica. Existe como rede de segurança: se algum pacote alguma vez deixar de descontar, isto regenera o desconto da Shopify a partir de todos os seus pacotes publicados. É seguro usar quantas vezes quiser, e se não houver nada a corrigir, diz-o: Já estava tudo atualizado.
• Acesso de programador: os dados públicos que o seu tema pode ler (anexo 22). A documentação do contrato está aberta em todos os planos.

18.2 Planos

Preço fixo: nunca cobramos uma percentagem das suas vendas, e o preço não depende do seu plano Shopify — uma loja Basic e uma loja Plus pagam o mesmo.

• Gratuito ($0/mês): até 3 pacotes publicados em simultâneo (os rascunhos não contam) com os 8 tipos incluídos. Ao tentar publicar o 4º, a app bloqueia com o aviso correspondente: mova outro para rascunho ou faça upgrade. No plano gratuito, os blocos mostram uma discreta insígnia Powered by Combora.
• Pro ($14.99/mês): pacotes publicados ilimitados e sem insígnia.
• Plus ($39.99/mês): tudo o que o Pro tem, mais suporte prioritário, importação/exportação CSV em massa (até 200 pacotes por ficheiro) e suporte de integração direta para o seu programador (lojas headless e temas personalizados).

A faturação passa pela Shopify (Managed Pricing) — é gerida e cancelada a partir da própria página de Planos. Os planos pagos incluem um período de teste gratuito de 7 dias, e se cancelar mantém o plano até ao fim do ciclo que já pagou. As lojas fundadoras (as primeiras 100 instalações) mantêm o produto completo grátis para sempre.

19Diagnóstico e suporte

O Diagnóstico (o segundo separador de Ajuda) é a sua primeira paragem quando algo não bate certo — e o que o suporte vai pedir se abrir um ticket. A Combora regista automaticamente, por loja, tudo o que falha por baixo (no servidor e na sua loja online) mesmo quando o cliente nunca o vê, e este painel coloca-o ao seu alcance. Não guarda quaisquer dados de clientes.

19.1 Verificações de saúde

O estado ao vivo do que o suporte pergunta primeiro, verificado junto da Shopify a cada carregamento:

19.2 Registo de eventos

Cada entrada é algo que aconteceu e ficou registado: uma falha ao publicar, um presente que a Shopify recusou adicionar (com o motivo exato), um desconto que colidiu com outro, um webhook que falhou… Filtre por nível (Info = esperado mas relevante, como o limite do plano; Aviso; Erro) e por área (publicação, descontos, plano e faturação, loja online, sincronização…). Um registo vazio é bom sinal: só se enche quando algo corre mal. Os eventos são mantidos durante 30 dias.

19.3 O relatório de suporte

Um único documento com tudo o que é preciso para diagnosticar a sua loja de uma só vez: as verificações de saúde, o seu plano e configuração (sem dados sensíveis), o estado de publicação de todos os pacotes e os últimos eventos. Ao contactar o suporte, clique em Copiar relatório (ou Descarregar como ficheiro) e anexe-o ao ticket — assim, quem o ajudar vê exatamente o que aconteceu sem pedir capturas de ecrã nem acesso.

• O relatório não inclui quaisquer dados de clientes nem chaves: apenas saúde, configuração de pacotes e eventos técnicos.
• Se o botão de copiar não funcionar no seu navegador, o texto fica selecionado — prima Ctrl+C (Cmd+C num Mac) — ou use a descarga.

20Limites e regras importantes

A referência única para os limites, verificada face ao código da app:

Regras de dinheiro (sempre exatas)

• As percentagens arredondam o desconto para baixo (nunca se arredonda a favor de cobrar mais).
• Os valores e preços fixos são repartidos pelas linhas com um remanescente exato: a soma das partes é sempre igual ao total.
• As casas decimais dependem da moeda da sua loja (JPY sem nenhuma, BHD com três…) — nunca se assumem duas casas decimais.
• O preço cobrado é calculado pela Shopify no checkout a partir da configuração publicada. O que os blocos do tema mostram é informativo.

Multi-moeda (Shopify Markets)

Se vende em várias moedas, não há nada para configurar: define preços, limites e descontos na moeda da sua loja, e a Combora trata do resto. Um cliente a comprar noutra moeda vê os valores do widget convertidos para a sua (o limite do presente, o preço do pacote, a poupança de cada nível), e no checkout o desconto é convertido à taxa de câmbio da Shopify nesse momento — a mesma que converte os preços dos seus produtos. A regra de ouro mantém-se: o que o cliente vê anunciado é exatamente o que o checkout lhe cobra, na sua moeda.

Outras regras

• As subscrições são bloqueadas nas linhas de pacote a não ser que ative explicitamente essa opção (secção 4.5).
• Um presente GWP não é anunciado na própria página do produto-presente (um prémio não é um isco).
• Os pacotes publicados fora da sua janela de agendamento não aplicam nenhum desconto (reativam-se sozinhos).

21Resolução de problemas

Não consigo ver a oferta na minha loja online

① O pacote está Publicado (não em rascunho) e dentro da sua janela de datas? ② Adicionou o bloco certo ao template (o cartão Onde isto aparece no editor)? ③ Se editou um pacote publicado, clicou em Atualizar pacote?

O presente não se adiciona sozinho

① O app embed Combora Gift está ativado? ② O carrinho cumpre a condição contando apenas o que se qualifica (o presente não conta)? ③ O cliente removeu-o manualmente nesta sessão? ④ O presente tem stock?

O desconto do carrinho não é o que eu esperava

Lembre-se da regra: só a melhor oferta por linha. Se dois pacotes competirem pelo mesmo artigo, ganha o que desconta mais (e em caso de empate, o mais antigo). A soma só acontece dentro de um combo.

A app diz: Tem outro desconto automático ativo

Isto é informação, não um erro. Significa que tem os seus próprios descontos automáticos de produto na Shopify. Onde um pacote da Combora e um desses descontos incidem sobre o mesmo produto, a Shopify aplica apenas o melhor dos dois — sobrepor dois descontos de produto no mesmo artigo exige Shopify Plus. Isso é uma regra da Shopify, não da Combora. Os seus pacotes combinam-se com os seus descontos de encomenda e de envio, e com descontos de produto que incidam sobre outros produtos. O aviso identifica o desconto específico em sobreposição para saber qual analisar.

Publiquei e diz limite do plano

O plano Gratuito permite 3 pacotes publicados em simultâneo. Mova outro para rascunho ou faça upgrade.

A barra de progresso do presente não aparece

Renderiza no template do carrinho (o bloco Combora gift progress) e só para ofertas cujo critério possa ser avaliado no navegador. Com coleções como o que conta, também funciona, porque a app resolve os produtos da coleção ao publicar; a única exceção é uma coleção muito grande (mais de ~150 produtos), onde a barra não é mostrada mesmo que o presente continue a funcionar.

O seletor de caixas de verificação não aparece no mix / caixa

O seletor aparece em qualquer âmbito: com variantes específicas mostra exatamente essas caixas de verificação, e com produtos ou uma coleção a lista é resolvida ao publicar (e atualizada todas as noites, ou de imediato se voltar a publicar). Se continuar vazio, o grupo elegível não tem produtos compráveis — verifique a nota de pré-visualização no editor. De qualquer forma, o cliente pode adicionar produtos como habitualmente e o desconto ativa-se ao qualificar-se.

Erros ao importar um CSV

Cada linha falhada é listada com o seu motivo. Corrija essas linhas e volte a executar só com elas — as linhas boas já foram criadas.

Suspeito que um desconto ficou órfão

Definições → Sincronizar descontos repara o estado. Nunca edite manualmente o desconto Combora na secção de Descontos da Shopify.

22Anexo para programadores: o contrato público

A Combora publica os dados dos seus pacotes na sua loja como metaobjects e metafields sob o namespace combora, publicamente legíveis a partir da loja online. Qualquer programador pode construir uma interface totalmente personalizada lendo estes dados a partir do Liquid ou da Storefront API — sem chamar nenhuma API da app. Este contrato é versionado e apenas aditivo (versão atual: public.v1): os campos existentes nunca são renomeados nem reetipados.

22.1 O que é criado na instalação

A instalação disponibiliza as definições (os esquemas) — visíveis em Definições → Metafields e metaobjects e em Conteúdo → Metaobjects:

• Metaobjects: combora_bundle (o pacote), combora_component (cada linha de componente) e combora_tier (cada nível de volume/limiar). Todos os três com acesso PUBLIC_READ na loja online, publicáveis e traduzíveis.
• Metafields da loja: combora.index e combora.manifest (JSON, leitura pública), e combora.all_pdp_gwps (list.metaobject_reference → combora_bundle): os presentes aplicados à loja inteira que optaram por ser anunciados em todas as páginas de produto.
• Metafield de produto: combora.bundles (list.metaobject_reference → combora_bundle) — o índice inverso produto → os seus pacotes.

22.2 O que acontece ao publicar / atualizar / retirar

22.3 combora_bundle campo a campo

22.4 O descritor eligible

O grupo elegível do pacote, com a mesma forma em todos os tipos:

{ "mode": "all" | "products" | "collections" | "variants",
  "variants":   ["gid://shopify/ProductVariant/…"],
  "products":   ["gid://shopify/Product/…"],
  "collections":["gid://shopify/Collection/…"],
  "resolved_count": 12, "total_count": 12, "truncated": false }

Só as listas não vazias são incluídas. As três chaves de resolução são informativas (em grupos de coleção dizem quantos membros foram materializados e se o snapshot foi cortado) — pode ignorá-las. Repare na convenção: o config do metaobject usa snake_case (gift_variant, min_qty), enquanto o objeto gwp no index usa camelCase (giftVariant, minQty) — os mesmos dados em duas superfícies diferentes.

Atenção: os filhos role:"option" de um grupo de coleção são um snapshot tirado no momento da publicação; a pertença ao vivo (e o preço) é sempre resolvida pela Function no checkout.

22.5 combora.index e combora.manifest

shop.metafields.combora.index — a tabela de encaminhamento dos pacotes publicados (existe para nunca ter de percorrer metaobjects.combora_bundle.values, que o Liquid corta silenciosamente aos 50):

{ "schema": 1, "revision_highwater": 128, "generated_at": "…",
  "bundles": [
    { "id": "f3062319-9d6e-…", "handle": "combora-bundle-f3062319-9d6e-…", "type": "fixed",
      "gid": "gid://shopify/Metaobject/…", "status": "active", "revision": 42 }
  ] }

O id é um identificador de texto, não um número. Só os pacotes que estão publicados e dentro da sua janela de agendamento são anunciados, pelo que o índice acompanha o preço do checkout. Algumas entradas trazem campos extra: gwp (a oferta de presente, só em pacotes de tipo presente), gwps (as ofertas de presente de um combo, pela ordem das sub-ofertas) e test (true se o pacote está em modo de teste: o JS da loja online ignora-o no tema publicado).

shop.metafields.combora.manifest — o descritor do contrato que uma ferramenta lê uma vez: contract_version, schema_version, o contador de pacotes e os GIDs das três definições. Pode trazer powered_by_badge: true, que é o que acende a insígnia Powered by Combora nos blocos (só em lojas do plano Gratuito; nas outras, o campo é omitido).

22.6 Ler a partir do Liquid

{%- comment -%} Numa página de produto: os pacotes DESTE produto {%- endcomment -%}
{%- for bundle in product.metafields.combora.bundles.value -%}
  <h3>{{ bundle.title.value | escape }}</h3>
  {%- if bundle.badge_label.value != blank -%}
    <span class="badge">{{ bundle.badge_label.value | escape }}</span>
  {%- endif -%}
  <ul>
    {%- for component in bundle.components.value -%}
      {%- comment -%} label é opcional: se estiver ausente, recorre ao título da variante e
          depois ao título do produto. CUIDADO: se o produto NÃO estiver publicado no canal
          Loja Online, a sua referência não se resolve em Liquid e TODOS os recursos
          alternativos devolvem blank — proteja o nome final ou vai renderizar um "1× " vazio. {%- endcomment -%}
      {%- assign name = component.label.value -%}
      {%- if name == blank -%}{%- assign name = component.variant.value.title -%}{%- endif -%}
      {%- if name == blank or name == 'Default Title' -%}{%- assign name = component.variant.value.product.title -%}{%- endif -%}
      {%- if name != blank -%}
        <li>{{ component.quantity.value }}× {{ name | escape }}</li>
      {%- endif -%}
    {%- endfor -%}
  </ul>
{%- endfor -%}

{%- comment -%} Ou por handle direto, em qualquer template {%- endcomment -%}
{%- assign bundle = metaobjects.combora_bundle['combora-bundle-{id}'] -%}

As duas vias são leituras limitadas (a lista do próprio produto, ou um handle direto) — nunca o .values global. Duas armadilhas do Liquid que lhe poupam uma tarde: (1) um for sobre uma lista de referências corta silenciosamente aos 50 — os pacotes da Combora nunca lá chegam (o maior limite é de 50 entradas no total), mas não itere coleções de outros assumindo que vê tudo; (2) os campos opcionais (label, badge_label, cta_label) chegam muitas vezes vazios — proteja com != blank como acima.

22.7 Ler a partir da Storefront API (localizado)

query BundleByHandle @inContext(language: FR) {
  metaobject(handle: { type: "combora_bundle", handle: "combora-bundle-{id}" }) {
    title:       field(key: "title")       { value }
    badge_label: field(key: "badge_label") { value }
    components:  field(key: "components") {
      references(first: 25) {
        nodes { ... on Metaobject {
          label:    field(key: "label")    { value }
          quantity: field(key: "quantity") { value }
        } }
      }
    }
  }
}

@inContext devolve as traduções semeadas pela app; o que não estiver traduzido recorre automaticamente ao idioma base.

22.8 O que pode construir com isto

• Uma interface de pacotes totalmente personalizada no tema, sem os blocos da Combora, lendo título, insígnia, componentes e poupança a partir do metaobject.
• Uma landing page de campanha: uma página que lista os pacotes ativos a partir de combora.index e renderiza cada um pelo seu handle.
• Headless / Hydrogen: a mesma leitura através da Storefront API com localização por mercado.
• Integrações (feeds, apps de recomendação): o manifest declara a versão do contrato e onde tudo está.

22.9 Regras para o programador

• O preço pertence à Function. Os campos do metaobject são para exibição: não some o discount_value de um combo nem recalcule preços no tema — o checkout é a autoridade.
• Apenas aditivo: podem surgir novos campos; os existentes não mudam. Escreva leituras tolerantes a campos desconhecidos.
• Combos: agrupe os filhos pela position dividida por 1000 (cada sub-oferta ocupa uma faixa de 1000) ou por config.of[].index — nunca por role, que se pode repetir.
• Estilo: se construir a sua própria interface, ignore style e escreva o seu CSS. Se, em vez disso, quiser respeitar o design que o comerciante escolheu na app, copie style.vars para o atributo style da sua raiz e style.mode_class como uma classe; a predefinição Sem estilo do estúdio existe exatamente para o caso oposto (markup limpo, o seu CSS, com .combora-w e as variáveis --combora-* como pontos de ligação).
• Privado ≠ contrato: os metafields $app:runtime, $app:fnvars e $app:validation do desconto são internos às Functions, não têm acesso na loja online, e a sua forma pode mudar sem aviso. Não construa sobre eles.
• Multi-moeda (Shopify Markets): todos os valores no contrato — config.price, threshold, fixed_amount.amount, box_price — estão sempre na moeda da loja, em unidades mínimas. Se a sua loja vende em várias moedas, converta ao apresentar (em Liquid, multiplique por cart.currency.rate; em JS, por Shopify.currency.rate) antes de formatar; renderizar o número em bruto com a moeda de apresentação do comprador mostra um preço errado. O desconto real do checkout é calculado pela app e está sempre correto — esta regra só se aplica ao que o SEU widget mostra.
• Não escreva no namespace combora. A Shopify dá-lhe acesso de escrita a ele (é a sua loja), mas a app regenera-o em cada publicação e uma revisão noturna repõe os campos que governam o plano. O que for seu vai no seu próprio namespace.
• Este anexo é a referência completa do contrato para programadores externos. Se faltar algo de que precise, escreva-nos através do chat da app ou para o suporte e nós documentamo-lo.

23Anexo para programadores: um widget por tipo, em Liquid

O anexo anterior descreve o que o contrato contém; este mostra como renderizar cada tipo de pacote com ele. Todo o código abaixo lê apenas o contrato público — nenhuma API da app, nenhum dos blocos da própria Combora — pelo que pode colá-lo num snippet ou num bloco Liquid personalizado no template de produto e adaptar o markup livremente. Três regras aplicam-se a tudo nesta página:

• O preço pertence à Function. Tudo aqui é exibição; o valor realmente cobrado é calculado pela Shopify Function da Combora no checkout. Nunca recalcule um total para o apresentar como o preço.
• Os valores são unidades mínimas na moeda da loja. Multiplique por cart.currency.rate antes de formatar, ou um comprador a navegar noutra moeda vê um número errado.
• Os campos opcionais chegam muitas vezes vazios. Proteja com != blank — incluindo o nome do componente depois dos seus recursos alternativos (ver 22.6).

23.1 O esqueleto em que todos os exemplos encaixam

Um cartão por pacote do produto atual, com título, insígnia e a poupança seja qual for a forma como o pacote a expressa (discount_value em pontos base ou unidades mínimas). Cada tipo renderiza depois o seu próprio corpo dentro do case:

{%- liquid
  assign bundles = product.metafields.combora.bundles.value
  assign rate = cart.currency.rate | default: 1
-%}

{%- if bundles != blank -%}
  {%- for bundle in bundles -%}
    {%- liquid
      assign type = bundle.bundle_type.value
      assign dv = bundle.discount_value.value
      assign cfg = bundle.config.value
    -%}
    <article class="cx__card">
      <h3>{{ bundle.title.value | escape }}</h3>
      {%- if bundle.badge_label.value != blank -%}
        <span class="cx__badge">{{ bundle.badge_label.value | escape }}</span>
      {%- endif -%}

      {%- comment -%} A poupança, seja qual for a forma como este pacote a expressa {%- endcomment -%}
      {%- if dv.kind == 'percentage' -%}
        <p>Poupe {{ dv.bps | divided_by: 100 }}%</p>
      {%- elsif dv.kind == 'fixed_amount' -%}
        <p>Poupe {{ dv.amount | times: rate | money }}</p>
      {%- endif -%}

      {%- case type -%}
        {%- comment -%} um bloco por tipo — as secções 23.2 a 23.7 entram aqui {%- endcomment -%}
      {%- endcase -%}
    </article>
  {%- endfor -%}
{%- endif -%}

23.2 Pacote fixo

Liste os filhos com role == 'component' com a cadeia de recursos alternativos do nome, mostre o preço do pacote quando o pacote usa o modo de preço (config.price, unidades mínimas) e ligue ao produto-pai comprável:

{%- when 'fixed' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'component' -%}
        {%- liquid
          assign name = c.label.value
          if name == blank
            assign name = c.variant.value.title
          endif
          if name == blank or name == 'Default Title'
            assign name = c.variant.value.product.title
          endif
        -%}
        {%- if name != blank -%}
          <li>{{ c.quantity.value }}× {{ name | escape }}</li>
        {%- endif -%}
      {%- endif -%}
    {%- endfor -%}
  </ul>
  {%- if cfg.price -%}
    <p class="cx__price">{{ cfg.price | times: rate | money }}</p>
  {%- endif -%}
  {%- if bundle.product.value != blank -%}
    <a href="{{ bundle.product.value.url }}">Comprar este pacote</a>
  {%- endif -%}

Um pacote fixo em modo de preço traz config.price e nenhum discount_value; em modo de desconto é ao contrário — a linha de poupança do esqueleto já cobre o segundo caso.

Num produto com uma única variante, o título da variante é o marcador da Shopify «Default Title»: a cadeia de recursos alternativos ignora-o e usa o título do produto (é para isso que serve a condição extra).

23.3 Desconto por volume

A escada vive em tiers (ordenados por position), cada escalão com o seu próprio min_qty e discount_value:

{%- when 'volume' -%}
  <table>
    {%- for t in bundle.tiers.value -%}
      {%- assign tv = t.discount_value.value -%}
      <tr>
        <td>Compre {{ t.min_qty.value }}+</td>
        <td>
          {%- if tv.kind == 'percentage' -%}
            {{ tv.bps | divided_by: 100 }}% de desconto
          {%- else -%}
            {{ tv.amount | times: rate | money }} de desconto
          {%- endif -%}
        </td>
      </tr>
    {%- endfor -%}
  </table>

23.4 Compre X, leve Y

A regra são dois escalares em config; uma percentagem de 100% (bps == 10000) significa que os artigos de recompensa são grátis:

{%- when 'bogo' -%}
  <p>Compre {{ cfg.buy_qty }}, leve {{ cfg.get_qty }}
    {%- if dv.kind == 'percentage' and dv.bps == 10000 %} grátis{% else %} com desconto{% endif -%}.</p>

23.5 Combine e poupe e monte a sua caixa

Ambas são ofertas de "atingir uma quantidade": o combine e poupe lê o min_items do metaobject, a caixa lê config.slots (e config.box_price quando a caixa cobra um preço fechado). O grupo elegível está em config.eligible (ver 22.4):

{%- when 'mix_and_match' -%}
  <p>Escolha {{ bundle.min_items.value }} ou mais da seleção.</p>
{%- when 'build_a_box' -%}
  <p>Encha uma caixa de {{ cfg.slots }}.
    {%- if cfg.box_price %} Preço da caixa {{ cfg.box_price | times: rate | money }}.{% endif -%}</p>

23.6 Complementos (FBT)

Os componentes trazem papéis: o anchor é o produto principal, os filhos suggestion são os complementos:

{%- when 'fbt' -%}
  <ul>
    {%- for c in bundle.components.value -%}
      {%- if c.role.value == 'suggestion' or c.role.value == 'anchor' -%}
        <li>
          {{ c.variant.value.product.title | default: c.label.value | escape }}
          {%- if c.role.value == 'anchor' %} <em>(este artigo)</em>{% endif -%}
        </li>
      {%- endif -%}
    {%- endfor -%}
  </ul>

23.7 Combo

Um combo aninha sub-ofertas. Agrupe os seus filhos pela position dividida por 1000 (cada sub-oferta ocupa uma faixa de 1000) ou percorra config.of[] — nunca agrupe por role, que se repete entre sub-ofertas:

{%- when 'combo' -%}
  <ol>
    {%- for sub in cfg.of -%}
      <li>{{ sub.type | replace: '_', ' ' }}</li>
    {%- endfor -%}
  </ol>

23.8 Ofertas de presente de toda a loja, em qualquer página

Os presentes anunciados em todas as páginas de produto vivem num metafield de loja, e o Liquid do tema não resolve uma lista de metaobjects ao nível da loja (22.1). Leia antes o index JSON e resolva cada pacote pelo seu handle:

{%- assign index = shop.metafields.combora.index.value -%}
{%- if index != blank -%}
  {%- for entry in index.bundles -%}
    {%- if entry.all_pdp and entry.status == 'active' -%}
      {%- assign gift = metaobjects['combora_bundle'][entry.handle] -%}
      {%- if gift != blank -%}
        <aside class="cx__gift">
          <strong>{{ gift.title.value | escape }}</strong>
          {%- assign gcfg = gift.config.value -%}
          {%- if gcfg.threshold -%}
            <span>Gaste {{ gcfg.threshold | times: rate | money }} para o desbloquear.</span>
          {%- endif -%}
        </aside>
      {%- endif -%}
    {%- endif -%}
  {%- endfor -%}
{%- endif -%}

23.9 O snippet completo

Tudo o que está acima reunido num único ficheiro funcional — o esqueleto, os seis corpos de tipo, os presentes de toda a loja e um CSS mínimo para que seja legível à primeira: descarregar combora-custom-bundle.liquid. Guarde-o como snippets/combora-custom-bundle.liquid no seu tema e renderize-o a partir do template de produto com {% render 'combora-custom-bundle', product: product %}. O GWP não está no case de propósito: um presente é anunciado (23.8 ou os blocos da própria app) e adicionado automaticamente pela app — não há nada que um widget de cartão de produto tenha de vender.

24Histórico desta edição

Todos os fluxos deste manual foram testados numa loja real. Aqui fica o registo de quando foi verificado e o que mudou depois, para saber quão atual é o que está a ler.

As capturas de ecrã estão em app/combora/public/manual/img/ no repositório: as da interface da app em img/<idioma>/, um conjunto por idioma, e as da loja online e do admin da Shopify na raiz, porque essas seguem o seu tema e o seu admin, não o idioma da app. São refeitas a partir da loja de demonstração; ver docs/manual/CAPTURAS.md para o estado que cada uma precisa.