Conectar la atribución del Visualizer a pedidos pagados#

Capture la instantánea de atribución publicada por el Visualizer SDK, consérvela junto al carrito o la finalización de compra del cliente y informe el pedido pagado final desde su servidor.

El SDK no modifica tu carrito ni reportará pedidos automáticamente. Tu integración debe:

1. capturar la última instantánea en el sitio de venta;
2. conservar la instantánea completa junto al carrito y el pedido; y
3. enviar el pedido pagado a Ideal House desde un servidor de confianza.

1. Capturar la instantánea#

Lea la cookie ih_visualizer cuando se inicialice su sitio de venta y escuche ih:visualizer para recibir actualizaciones. La cookie contiene JSON codificado en URL. El evento del navegador proporciona el mismo objeto en 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 con los atributos del carrito de su plataforma de comercio, los metadatos de la finalización de compra o la sesión del lado del servidor API.

Los campos de la instantánea son:

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

Guarda y reemplaza la instantánea completa en su conjunto. No renombres, copies parcialmente ni modifiques sus valores. Trata los datos leídos desde una cookie como no confiables y deséchala si no es un objeto completo con esta estructura.

Si su finalización de compra usa otro nombre de host o una plataforma externa, copie la instantánea en el carrito o en la sesión del lado del servidor antes de que el cliente salga de la página del sitio de venta.

2. Conservarla con el pedido#

Cuando se complete el pago, reconstruya la instantánea original a partir de los metadatos de su carrito, finalización de compra o pedido. Si no hay ninguna instantánea completa disponible, use null en lugar de construir un objeto parcial.

Almacene el capture como un valor JSON o utilice estos campos de metadatos recomendados:

Convierta idealhouse_categories nuevamente a un arreglo de cadenas JSON antes de informar el pedido.

3. Informar el pedido pagado#

Llame a este extremo desde su backend o desde el controlador de webhook de pedido pagado. Nunca lo llame desde JavaScript del navegador.

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

Use credenciales de la misma tienda Ideal House que el SDK del sitio de venta. No incluya shop_id ni shopId en el cuerpo de la solicitud.

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"
    }
  }'

Envía valores monetarios como cadenas JSON. Incluye una zona horaria en cada marca de tiempo. Envía únicamente los campos documentados; no se aceptan nombres de clientes, direcciones de correo electrónico, números de teléfono ni direcciones de facturación o envío.

Para un pedido sin una instantánea de atribución completa, el campo visualizer sigue siendo obligatorio:

{
  "visualizer": null
}

4. Manejar reintentos#

Cree un event_id estable para el evento de pedido pagado y reutilícelo en cada reintento.

Ejemplo de respuesta exitosa:

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

5. Lista de verificación de integración#

1. Confirme que el sitio de venta puede leer ih_visualizer después de usar el Visualizer.
2. Confirme que el oyente ih:visualizer actualiza los metadatos del carrito o de la finalización de compra.
3. Confirma que la instantánea completa llegue al pedido pagado.
4. Envíe un pedido de prueba pagado desde su servidor y espere HTTP 200.
5. Envíe el mismo evento nuevamente con el mismo event_id y acepte duplicate: true como éxito.
6. Envíe un pedido sin atribución usando "visualizer": null.
7. Confirme que el Client Secret y los datos personales del cliente nunca aparecen en las solicitudes del navegador ni en los datos del pedido enviado.