Schéma du catalogue

Quand vous uploadez un catalogue via l’API Dialog, le JSON doit respecter ce schéma. L’assistant IA Dialog utilise ces données structurées pour comprendre vos produits et recommander juste.

À quoi Dialog utilise le catalogue

• Comprendre les features, variantes et specs des produits.
• Faire des comparaisons produit intelligentes.
• Fournir des recommandations contextuelles selon les besoins du client.
• Répondre aux questions détaillées sur votre inventaire.

Plus votre catalogue est complet et structuré, meilleures sont les réponses.

JSON Schema

Collez-le dans votre validateur (Ajv, jsonschema, Pydantic via model_json_schema, etc.) pour valider vos payloads avant l’upload.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Dialog product catalog",
  "type": "object",
  "required": ["products"],
  "properties": {
    "products": {
      "type": "array",
      "items": { "$ref": "#/definitions/product" }
    }
  },
  "definitions": {
    "product": {
      "type": "object",
      "required": ["id", "title", "status", "variants", "metafields", "collections", "tags"],
      "properties": {
        "id": {
          "type": "string",
          "description": "Identifiant unique du produit dans votre système. Doit être stable entre imports."
        },
        "title": { "type": "string" },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL canonique de la fiche produit. Utilisée pour les liens dans les recommandations du chat."
        },
        "status": { "$ref": "#/definitions/status" },
        "variants": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/productVariant" }
        },
        "metafields": {
          "type": "array",
          "items": { "$ref": "#/definitions/metafield" }
        },
        "collections": {
          "type": "array",
          "items": { "$ref": "#/definitions/collection" }
        },
        "tags": {
          "type": "array",
          "items": { "type": "string" }
        },
        "description": { "type": "string" },
        "translations": { "$ref": "#/definitions/productTranslations" },
        "featuredImage": { "$ref": "#/definitions/image" },
        "images": {
          "type": "array",
          "items": { "$ref": "#/definitions/image" }
        },
        "options": {
          "type": "array",
          "items": { "$ref": "#/definitions/option" }
        }
      }
    },
    "productVariant": {
      "type": "object",
      "required": ["id", "displayName", "inStock", "price"],
      "properties": {
        "id": { "type": "string" },
        "displayName": { "type": "string" },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL de la fiche spécifique à la variante. Fortement recommandée : les recommandations du chat pointent vers cette URL pour les variantes en stock. Fallback sur l'URL du produit si absente."
        },
        "inStock": { "type": "boolean" },
        "price": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/price" },
          "description": "Une entrée par devise supportée."
        },
        "translations": { "$ref": "#/definitions/variantTranslations" },
        "selectedOptions": {
          "type": "array",
          "items": { "$ref": "#/definitions/selectedOption" }
        },
        "metafields": {
          "type": "array",
          "items": { "$ref": "#/definitions/metafield" }
        },
        "compareAtPrice": {
          "type": "array",
          "items": { "$ref": "#/definitions/price" },
          "description": "Prix d'origine, pour afficher la remise."
        },
        "image": { "$ref": "#/definitions/image" }
      }
    },
    "image": {
      "type": "object",
      "required": ["url"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL directe : HTTPS fortement recommandé."
        }
      }
    },
    "price": {
      "type": "object",
      "required": ["amount", "currencyCode"],
      "properties": {
        "amount": {
          "type": "string",
          "pattern": "^\\d+(\\.\\d+)?$",
          "description": "Décimal encodé en string, ex. \"29.99\". Pas un nombre."
        },
        "currencyCode": { "$ref": "#/definitions/currencyCode" }
      }
    },
    "metafield": {
      "type": "object",
      "required": ["name", "value"],
      "properties": {
        "name": {
          "type": "string",
          "description": "ex. \"material\", \"weight\", \"brand\"."
        },
        "value": {
          "type": "string",
          "description": "ex. \"cotton\", \"2.5kg\", \"Nike\"."
        }
      }
    },
    "collection": {
      "type": "object",
      "required": ["title"],
      "properties": {
        "title": { "type": "string" },
        "description": { "type": "string" }
      }
    },
    "option": {
      "type": "object",
      "required": ["id", "name", "values", "position"],
      "properties": {
        "id": { "type": "string" },
        "name": {
          "type": "string",
          "description": "ex. \"Color\", \"Size\", \"Material\"."
        },
        "values": {
          "type": "array",
          "items": { "type": "string" }
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Ordre d'affichage 0-based."
        },
        "translations": {
          "type": "array",
          "items": { "$ref": "#/definitions/optionTranslations" }
        }
      }
    },
    "selectedOption": {
      "type": "object",
      "required": ["name", "value"],
      "properties": {
        "name": { "type": "string" },
        "value": { "type": "string" },
        "translations": {
          "type": "object",
          "description": "Map locale → nom/valeur traduits.",
          "additionalProperties": {
            "type": "object",
            "required": ["name", "value"],
            "properties": {
              "name": { "type": "string" },
              "value": { "type": "string" }
            }
          }
        }
      }
    },
    "productTranslations": {
      "type": "object",
      "description": "Map locale (ISO en minuscules, ex. \"en\", \"fr\") → champs traduits.",
      "additionalProperties": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL de la fiche produit spécifique à la locale. Vous pouvez aussi la définir par variante dans `productVariant.translations`."
          }
        }
      }
    },
    "variantTranslations": {
      "type": "object",
      "description": "Map locale → champs traduits.",
      "additionalProperties": {
        "type": "object",
        "required": ["displayName"],
        "properties": {
          "displayName": { "type": "string" },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL de la fiche variante spécifique à la locale."
          }
        }
      }
    },
    "optionTranslations": {
      "type": "object",
      "required": ["key", "value"],
      "properties": {
        "key": { "type": "string" },
        "value": { "type": "string" }
      }
    },
    "currencyCode": {
      "type": "string",
      "enum": ["EUR", "USD", "CAD", "GBP", "PLN"]
    },
    "status": {
      "type": "string",
      "enum": ["ACTIVE", "ARCHIVED", "DRAFT", "UNLISTED"],
      "description": "ACTIVE : disponible à la vente. ARCHIVED : plus disponible, gardé pour référence. DRAFT : pas encore prêt à la vente. UNLISTED : caché des recommandations."
    }
  }
}

Payload exemple

{
  "products": [
    {
      "id": "prod_001",
      "title": "T-shirt premium en coton",
      "url": "https://example.com/products/premium-cotton-tshirt",
      "description": "T-shirt confortable 100% coton bio, parfait pour tous les jours.",
      "status": "ACTIVE",
      "collections": [
        { "title": "Collection Été", "description": "Essentiels d'été légers et respirants" },
        { "title": "Eco-Friendly" }
      ],
      "tags": ["coton", "été", "casual", "bio"],
      "metafields": [
        { "name": "material", "value": "100% coton bio" },
        { "name": "care_instructions", "value": "Lavage à froid, séchage doux" }
      ],
      "featuredImage": { "url": "https://example.com/images/tshirt-main.jpg" },
      "images": [
        { "url": "https://example.com/images/tshirt-front.jpg" },
        { "url": "https://example.com/images/tshirt-back.jpg" }
      ],
      "options": [
        { "id": "color", "name": "Color", "values": ["Red", "Blue", "Green"], "position": 0 },
        { "id": "size", "name": "Size", "values": ["S", "M", "L", "XL"], "position": 1 }
      ],
      "variants": [
        {
          "id": "var_001",
          "displayName": "T-shirt rouge - Medium",
          "url": "https://example.com/products/premium-cotton-tshirt?variant=red-m",
          "inStock": true,
          "price": [
            { "amount": "29.99", "currencyCode": "USD" },
            { "amount": "25.99", "currencyCode": "EUR" }
          ],
          "selectedOptions": [
            { "name": "Color", "value": "Red" },
            { "name": "Size", "value": "M" }
          ],
          "compareAtPrice": [{ "amount": "39.99", "currencyCode": "USD" }],
          "image": { "url": "https://example.com/images/tshirt-red-m.jpg" }
        }
      ]
    }
  ]
}

Tips de validation

• L’objet racine doit contenir products en array.
• Chaque produit doit avoir au moins une variante.
• price.amount est une string, pas un nombre.
• Utilisez les codes ISO en minuscules pour les locales (en, fr, es).
• url est fortement recommandée sur chaque variante et sur chaque produit : sans ça, les recommandations dans le chat ne peuvent pas renvoyer vers votre site.

Comportement du clic

Quand un utilisateur clique sur un produit dans le widget, Dialog choisit l’URL de destination dans cet ordre :

1. L’url de la variante sélectionnée (si la variante est connue et a une URL).
2. L’url du produit.

Envoyez toujours au moins l’url du produit, et une url par variante quand les variantes vivent sur des pages distinctes (ex. ?variant=red-m).

Uploadez le fichier en utilisant l’URL pré-signée de la Référence API.