Integração do carrinho

O widget transforma uma disposição terminada em linhas de carrinho concretas e entrega-as à sua loja. A sua loja continua responsável por preços, descontos, stock e checkout.

Carga útil do callback

Quando o comprador clica em Adicionar ao carrinho, o widget chama onAddToCart com:

{
  lines: [
    { sku: 'TILE-600-300', qty: 5, unit: 'box' },
  ],
  layoutFingerprint: '…',
  layoutToken: '…',
}

lines são os artigos a adicionar. Cada linha é um SKU do catálogo, uma quantidade numérica e uma unidade. A resposta inclui sempre uma linha de azulejos — o total de azulejos a comprar, expresso em caixas.

Os consumíveis são opcionais

Cola, betume e primário são sempre calculados e mostrados no orçamento no ecrã e no Blueprint PDF. Se também sincronizam para o carrinho é uma definição opcional, ativada para comerciantes que vendem esses artigos. Quando está ativada, essas linhas são adicionadas ao lado do azulejo:

{
  lines: [
    { sku: 'TILE-600-300', qty: 5, unit: 'box' },
    { sku: 'ADHESIVE-25', qty: 12.5, unit: 'kg' },
    { sku: 'GROUT-2KG', qty: 3, unit: 'kg' },
    { sku: 'PRIMER-10L', qty: 1, unit: 'l' },
  ],
  layoutFingerprint: '…',
  layoutToken: '…',
}

Fale connosco se vende consumíveis e quer incluí-los — ativamo-lo para a sua loja durante a configuração.

layoutFingerprint é um identificador estável da disposição. layoutToken é um token assinado que pode guardar para reabrir mais tarde a disposição exata — por exemplo, para anexar o plano a uma encomenda.

Adicionar ao seu carrinho

O seu callback adiciona as linhas através da própria API da sua loja:

onAddToCart(payload) {
  payload.lines.forEach((line) => {
    yourStore.addToCart({
      sku: line.sku,
      quantity: line.qty,
      unit: line.unit,
    });
  });
}

Para WooCommerce isso significa uma chamada cart/add-item por linha; para Shopify, uma mutação de carrinho; para uma loja personalizada, o seu próprio serviço de carrinho. O widget nunca chama a sua loja diretamente — fá-lo você, com os SKU e as quantidades que resolveu.

O preço fica na sua loja

O widget nunca envia um preço. Pode mostrar preços de tabela do seu catálogo no orçamento como contexto, mas o preço final, impostos, promoções e descontos de fidelização são todos aplicados pelo seu checkout quando as linhas são adicionadas. Isso mantém um único motor de preços e evita qualquer desvio entre o widget e o carrinho.

O stock fica na sua loja

O widget adiciona o que a disposição exige. A sua loja valida o stock desses SKU exatamente como em qualquer outro «adicionar ao carrinho». Se um SKU está baixo ou indisponível, o seu fluxo existente de encomendas pendentes e notificações aplica-se sem alterações.

Endpoint de intenção de carrinho

Para integrações headless ou no lado do servidor existe um endpoint de intenção de carrinho que devolve as mesmas linhas resolvidas. O seu servidor chama-o com a disposição e adiciona o resultado ao carrinho de sessão:

curl -X POST "https://embed.scalarcut.com/v1/tiling/cart-intent" \
  -H "Authorization: Bearer $WIDGET_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "catalog": "YOUR_CATALOG_SLUG",
    "sku": "TILE-600-300",
    "layoutFingerprint": "…",
    "quantities": { "boxes": 5 }
  }'

Resposta:

{
  "lines": [
    { "sku": "TILE-600-300", "qty": 5, "unit": "box" }
  ],
  "layoutFingerprint": "…",
  "layoutToken": "…"
}

Com os consumíveis ativados na sua loja, o pedido pode também levar adhesiveKg, groutKg e primerL, e a resposta ganha as linhas correspondentes.

Veja a referência da API para o contrato completo do endpoint.