Schema del catálogo

Cuando subes un catálogo vía la API Dialog, el JSON debe matchear este schema. El asistente IA de Dialog usa estos datos estructurados para entender tus productos y recomendar con precisión.

Para qué usa Dialog el catálogo

• Entender features, variantes y specs de los productos.
• Hacer comparaciones de producto inteligentes.
• Proporcionar recomendaciones contextuales según las necesidades del cliente.
• Responder a preguntas detalladas sobre tu inventario.

Cuanto más completo y estructurado sea tu catálogo, mejores serán las respuestas.

JSON Schema

Pégalo en tu validador (Ajv, jsonschema, Pydantic vía model_json_schema, etc.) para validar tus payloads antes del 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": "Identificador único del producto en tu sistema. Debe ser estable entre imports."
        },
        "title": { "type": "string" },
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL canónica de la página del producto. Usada para los enlaces en las recomendaciones del 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 específica de la variante. Muy recomendada — las recomendaciones del chat enlazan a esta URL para las variantes en stock. Fallback a la URL del producto si falta."
        },
        "inStock": { "type": "boolean" },
        "price": {
          "type": "array",
          "minItems": 1,
          "items": { "$ref": "#/definitions/price" },
          "description": "Una entrada por moneda soportada."
        },
        "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": "Precios originales, para mostrar el descuento."
        },
        "image": { "$ref": "#/definitions/image" }
      }
    },
    "image": {
      "type": "object",
      "required": ["url"],
      "properties": {
        "url": {
          "type": "string",
          "format": "uri",
          "description": "URL directa — HTTPS fuertemente recomendado."
        }
      }
    },
    "price": {
      "type": "object",
      "required": ["amount", "currencyCode"],
      "properties": {
        "amount": {
          "type": "string",
          "pattern": "^\\d+(\\.\\d+)?$",
          "description": "Decimal codificado como string, ej. \"29.99\". No es un número."
        },
        "currencyCode": { "$ref": "#/definitions/currencyCode" }
      }
    },
    "metafield": {
      "type": "object",
      "required": ["name", "value"],
      "properties": {
        "name": {
          "type": "string",
          "description": "ej. \"material\", \"weight\", \"brand\"."
        },
        "value": {
          "type": "string",
          "description": "ej. \"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": "ej. \"Color\", \"Size\", \"Material\"."
        },
        "values": {
          "type": "array",
          "items": { "type": "string" }
        },
        "position": {
          "type": "integer",
          "minimum": 0,
          "description": "Orden de display 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 de locale → name/value traducidos.",
          "additionalProperties": {
            "type": "object",
            "required": ["name", "value"],
            "properties": {
              "name": { "type": "string" },
              "value": { "type": "string" }
            }
          }
        }
      }
    },
    "productTranslations": {
      "type": "object",
      "description": "Map de locale (ISO en minúsculas, ej. \"en\", \"fr\") → campos traducidos.",
      "additionalProperties": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string" },
          "description": { "type": "string" },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL de la página del producto específica de la locale. También puedes definirla por variante en `productVariant.translations`."
          }
        }
      }
    },
    "variantTranslations": {
      "type": "object",
      "description": "Map de locale → campos traducidos.",
      "additionalProperties": {
        "type": "object",
        "required": ["displayName"],
        "properties": {
          "displayName": { "type": "string" },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "URL de la página de la variante específica de 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 para la venta. ARCHIVED: ya no disponible, guardado para referencia. DRAFT: aún no listo para la venta. UNLISTED: oculto de las recomendaciones."
    }
  }
}

Payload ejemplo

{
  "products": [
    {
      "id": "prod_001",
      "title": "Camiseta Premium de Algodón",
      "url": "https://example.com/products/premium-cotton-tshirt",
      "description": "Camiseta cómoda 100% algodón orgánico perfecta para uso diario.",
      "status": "ACTIVE",
      "collections": [
        { "title": "Colección Verano", "description": "Esenciales de verano ligeros y transpirables" },
        { "title": "Eco-Friendly" }
      ],
      "tags": ["algodon", "verano", "casual", "organico"],
      "metafields": [
        { "name": "material", "value": "100% Algodón Orgánico" },
        { "name": "care_instructions", "value": "Lavar en frío, secar a temperatura baja" }
      ],
      "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": "Camiseta Roja - Mediana",
          "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 validación

• El objeto raíz debe contener products como array.
• Cada producto debe tener al menos una variante.
• price.amount es un string, no un número.
• Usa códigos ISO en minúsculas para las locales (en, fr, es).
• url es muy recomendada en cada variante y en cada producto — sin eso, las recomendaciones del chat no pueden enlazar a tu sitio.

Comportamiento al hacer clic

Cuando un comprador hace clic en un producto en el widget, Dialog elige la URL de destino en este orden:

1. La url de la variante seleccionada (si la variante es conocida y tiene una).
2. La url del producto.

Envía siempre al menos la url del producto — y una url por variante cuando las variantes viven en páginas distintas (ej. ?variant=red-m).

Sube el archivo usando la URL pre-firmada de la Referencia de la API.