Conectar a atribuição do Visualizer a pedidos pagos#

Capture o instantâneo de atribuição publicado pelo Visualizer SDK, mantenha-o junto ao carrinho ou checkout do cliente e reporte o pedido final pago a partir do seu servidor.

O SDK não modifica seu carrinho nem reporta pedidos automaticamente. Sua integração deve:

1. capturar o instantâneo mais recente na loja virtual;
2. manter o instantâneo completo junto ao carrinho e ao pedido; e
3. enviar o pedido pago ao Ideal House a partir de um servidor confiável.

1. Capturar o instantâneo#

Leia o cookie ih_visualizer quando sua loja virtual inicializar e ouça ih:visualizer para receber atualizações. O cookie contém JSON codificado em URL. O evento do navegador fornece o mesmo objeto em event.detail.

function readVisualizerAttribution() {
  const prefix = 'ih_visualizer='
  const value = document.cookie
    .split(';')
    .map(part => part.trim())
    .find(part => part.startsWith(prefix))
    ?.slice(prefix.length)

  if (!value) return null

  try {
    return JSON.parse(decodeURIComponent(value))
  } catch {
    return null
  }
}

window.addEventListener('ih:visualizer', event => {
  saveAttributionWithCart(event.detail)
})

const currentAttribution = readVisualizerAttribution()
if (currentAttribution) {
  saveAttributionWithCart(currentAttribution)
}

Implemente saveAttributionWithCart com os atributos do carrinho da sua plataforma de comércio, metadados de checkout ou sessão no lado do servidor por meio de uma API.

Os campos do snapshot são:

{
  "visitor_id": "anonymous-visitor-id",
  "session_id": "visualizer-session-id",
  "categories": ["wall", "furniture"],
  "last_used_at": "2026-09-10T12:34:56.000Z"
}

Armazene e substitua o snapshot completo em conjunto. Não renomeie, copie parcialmente ou modifique seus valores. Trate os dados lidos de um cookie como não confiáveis e descarte-o se não for um objeto completo com esta estrutura.

Se seu checkout usar outro nome de host ou uma plataforma externa, copie o instantâneo para o carrinho ou para a sessão no lado do servidor antes que o cliente saia da página da loja virtual.

2. Manter junto ao pedido#

Quando o pagamento for concluído, reconstitua o instantâneo original a partir dos metadados do seu carrinho, checkout ou pedido. Se nenhum instantâneo completo estiver disponível, use null em vez de construir um objeto parcial.

Armazene a captura instantânea como um valor JSON ou use estes campos de metadados recomendados:

Converta idealhouse_categories de volta para um array de strings JSON antes de reportar o pedido.

3. Reportar o pedido pago#

Chame este endpoint a partir do seu back-end ou do manipulador de webhooks de pedidos pagos. Nunca o chame a partir de JavaScript no navegador.

POST <IDEALHOUSE_API_URL>/integrations/commerce/order-events
Content-Type: application/json
X-Client-Id: <CLIENT_ID>
X-Client-Secret: <CLIENT_SECRET>

Use credenciais da mesma loja Ideal House do SDK da loja virtual. Não inclua shop_id nem shopId no corpo da solicitação.

curl -X POST "<IDEALHOUSE_API_URL>/integrations/commerce/order-events" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: <CLIENT_ID>" \
  -H "X-Client-Secret: <CLIENT_SECRET>" \
  -d '{
    "schema_version": 1,
    "event_id": "store-42-order-paid-1001",
    "event_type": "order.paid",
    "source": {
      "platform": "custom",
      "store_id": "store-42"
    },
    "order": {
      "id": "order-1001",
      "order_number": "#1001",
      "customer_po_number": null,
      "created_at": "2026-09-10T11:55:00.000Z",
      "paid_at": "2026-09-10T12:00:00.000Z",
      "financial_status": "paid",
      "currency": "USD",
      "subtotal": "125.50",
      "total": "143.25",
      "line_items": [
        {
          "id": "line-1",
          "product_id": "product-1",
          "variant_id": "variant-1",
          "sku": "WP-100",
          "product_type": "Wallpaper",
          "quantity": 2,
          "unit_price": "62.75",
          "total_price": "125.50"
        }
      ]
    },
    "visualizer": {
      "visitor_id": "anonymous-visitor-id",
      "session_id": "visualizer-session-id",
      "categories": ["wall", "furniture"],
      "last_used_at": "2026-09-09T12:00:00.000Z"
    }
  }'

Envie os valores monetários como strings JSON. Inclua um fuso horário em todos os timestamps. Envie apenas os campos documentados; nomes de clientes, endereços de e-mail, números de telefone e endereços de cobrança ou envio não são aceitos.

Para um pedido sem um instantâneo de atribuição completo, o campo visualizer ainda é obrigatório:

{
  "visualizer": null
}

4. Tratar retentativas#

Crie um event_id estável para o evento de pedido pago e reutilize-o para cada nova tentativa.

Resposta de sucesso de exemplo:

{
  "accepted": true,
  "duplicate": false,
  "visualizer_assisted": true
}

5. Lista de verificação de integração#

1. Confirme que a loja virtual consegue ler ih_visualizer após usar o Visualizer.
2. Confirme que o ouvinte ih:visualizer atualiza os metadados do carrinho ou do checkout.
3. Confirme que o snapshot completo chegue ao pedido pago.
4. Envie um pedido de teste pago a partir do seu servidor e aguarde HTTP 200.
5. Envie o mesmo evento novamente com o mesmo event_id e considere duplicate: true como sucesso.
6. Envie um pedido sem atribuição usando "visualizer": null.
7. Confirme que o Client Secret e os dados pessoais do cliente nunca aparecem em solicitações no navegador ou nos dados de pedido submetidos.