Connecter l'attribution Visualizer aux commandes payées#

Capturez l'instantané d'attribution publié par le Visualizer SDK, conservez-le avec le panier ou la commande du client, et déclarez la commande payée finale depuis votre serveur.

Le SDK ne modifie pas votre panier ni ne déclare les commandes automatiquement. Votre intégration doit :

1. capturer le dernier instantané dans la boutique en ligne ;
2. conserver l'instantané complet avec le panier et la commande ; et
3. envoyer la commande payée à Ideal House depuis un serveur de confiance.

1. Capturer l'instantané#

Lisez le cookie ih_visualizer lors de l'initialisation de votre boutique en ligne et écoutez ih:visualizer pour recevoir les mises à jour. Le cookie contient un JSON encodé en URL. L'événement navigateur fournit le même objet dans 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)
}

Implémentez saveAttributionWithCart avec les attributs de panier, les métadonnées de paiement ou la session API côté serveur de votre plateforme commerciale.

Les champs de la capture d'attribution sont :

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

Enregistrez et remplacez la capture d'attribution complète en une seule opération. Ne renommez, ne copiez pas partiellement et ne modifiez pas ses valeurs. Traitez les données lues depuis un cookie comme non fiables et rejetez-les si elles ne forment pas un objet complet ayant cette structure.

Si votre processus de paiement utilise un autre nom d'hôte ou une plateforme externe, copiez l'instantané dans le panier ou la session côté serveur avant que le client ne quitte la page de la boutique en ligne.

2. Conserver l'instantané avec la commande#

Lorsque le paiement est terminé, reconstruisez l'instantané original à partir des métadonnées de votre panier, de votre processus de paiement ou de votre commande. Si aucun instantané complet n'est disponible, utilisez null au lieu de construire un objet partiel.

Conservez l'instantané sous forme de valeur JSON ou utilisez ces champs métadonnées recommandés :

Convertissez idealhouse_categories en un tableau de chaînes JSON avant de déclarer la commande.

3. Déclarer la commande payée#

Appelez ce point de terminaison depuis votre backend ou votre gestionnaire de webhook de commande payée. Ne l'appelez jamais depuis du JavaScript côté navigateur.

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

Utilisez les identifiants du même magasin Ideal House que celui utilisé par le SDK de la boutique en ligne. N'incluez pas shop_id ni shopId dans le corps de la requête.

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

Envoyez les montants sous forme de chaînes JSON. Indiquez un fuseau horaire dans chaque horodatage. Envoyez uniquement les champs documentés ; les noms des clients, adresses e-mail, numéros de téléphone et adresses de facturation ou de livraison ne sont pas acceptés.

Pour une commande sans instantané d'attribution complet, le champ visualizer reste obligatoire :

{
  "visualizer": null
}

4. Gérer les nouveaux essais#

Créez un event_id stable pour l'événement de commande payée et réutilisez-le pour chaque nouvelle tentative.

Exemple de réponse de succès :

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

5. Liste de contrôle d'intégration#

1. Vérifiez que la boutique en ligne peut lire ih_visualizer après utilisation du Visualizer.
2. Vérifiez que l'écouteur ih:visualizer met bien à jour les attributs de panier ou les métadonnées de paiement.
3. Confirmez que la capture d'attribution complète atteint la commande payée.
4. Soumettez une commande test payée depuis votre serveur et attendez un HTTP 200.
5. Soumettez à nouveau le même événement avec le même event_id et acceptez duplicate: true comme succès.
6. Soumettez une commande sans attribution en utilisant "visualizer": null.
7. Vérifiez que le Client Secret et les données personnelles des clients n'apparaissent jamais dans les requêtes navigateur ou les données de commande soumises.