Documentación técnica

Guía de Integración
de Feeds y XML / JSON

Todo lo que tu equipo técnico necesita para conectar tu tienda con el motor de recomendaciones Xellers. El proceso completo toma menos de 2 horas.

🛒

Tu tienda

Shopify, WooCommerce,
VTEX, Odoo...

→

Feed XML/JSON Productos Catálogo de productos

Feed XML/JSON Ventas Historial de pedidos

→

🧠
Motor Xellers
IA aprende y genera
recomendaciones

→

Productos relacionados

Complementarios

Más vendidos

→

📈

Más ventas

Widgets en tu tienda
desde el día 1

¿Qué necesitamos y por qué?

Xellers necesita dos fuentes de datos de tu tienda/ecommerce para generar recomendaciones personalizadas. Ambas deben estar disponibles como endpoints públicos (con token de seguridad básicos, deben venir por GET con nombre token).

Feed de Productos (JSON / XML) — Le dice al motor qué productos existen, sus atributos, precio, stock e imagen. Se actualiza diariamente.

Feed de Ventas (JSON / XML) — Le dice al motor qué productos se compran juntos. Contiene el historial de pedidos pagados. Se actualiza diariamente.

Importante: El ID de producto, SKU o la variable identificadora debe ser idéntica en ambos archivos. De lo contrario, no será posible realizar la unión de los productos y el sistema no podrá procesar la información correctamente. No te preocupes; en el 99% de los e-commerce esto ya viene configurado así por defecto, por lo que seguramente en el tuyo también se podrá hacer sin problemas.

Feed de Productos (XML/JSON)

Un endpoint que devuelve todos los productos activos de la tienda. El formato puede ser cualquiera pero recomendamos en formato JSON o XML.

Campo	Tipo(max)	Estado	Descripción / Ejemplo
id	string(20)	Obligatorio	ID único del producto. Ej: `"1234"`
sku	string(20)	Obligatorio	Código comercial. Ej: `"SKU-001"`
nombre	string(50)	Obligatorio	Nombre completo del producto
familia	string(50)	Obligatorio	Familia principal. Ej: `"Herramientas"`
categoria	string(50)	Obligatorio	Categoría. Ej: `"Herramientas Eléctricas"`
link	string(100)	Obligatorio	URL completa de la ficha del producto. Ej: `"https://tienda.cl/ficha/1234"`
thumbs	string(100)	Obligatorio	URL de la imagen principal del producto
stock	int(11)	Obligatorio	Cantidad en stock. > 0
keyword	string(255)	Recomendado	Palabras clave del producto. Mejora la IA semántica.
marca	string(50)	Recomendado	Marca del producto
descripcion	string(300)	Recomendado	Descripción del producto. A más texto, mejor la IA.
precio	int(11)	Recomendado	Precio actual del producto
precio_descuento	int(11)	Recomendado	Precio con descuento si aplica

RESPUESTAEjemplo de respuesta esperada

[
      {
        "id":                       "1234",
        "sku":                      "TALADRO-001",
        "nombre":                   "Taladro Percutor 650W Bosch",
        "familia":                  "Herramientas",
        "categoria":                "Herramientas Eléctricas",
        "link":                     "https://micienda.cl/ficha/1234/taladro-percutor-650w",
        "thumbs":                   "https://mitienda.cl/imagenes/1234-1.jpg",
        "stock":                    15,
        "precio":                   89990,
        "precio_descuento":         79990,
        "marca":                    "Bosch",
        "descripcion":              "Taladro percutor de 650W ideal para trabajos en madera y metal...",
        "keyword":                  "taladro, percutor, bosch, herramienta eléctrica"
      },
      {
        "id":                       "5678",
        "sku":                      "TALADRO-002",
        "nombre":                   "Taladro Electrico Dewalt",
        "familia":                  "Herramientas",
        "categoria":                "Herramientas Eléctricas",
        "link":                     "https://micienda.cl/ficha/5678/taladro-electrico-dewalt",
        "thumbs":                   "https://mitienda.cl/imagenes/5678-1.jpg",
        "stock":                    234,
        "precio":                   129990,
        "precio_descuento":         10990,
        "marca":                    "Dewalt",
        "descripcion":              "Taladro Electrico ideal para trabajos en madera y metal...",
        "keyword":                  "taladro, percutor, dewalt, herramienta eléctrica"
      },
      // ... más productos
    ]

Formato del endpoint: Debe ser accesible vía GET idealmente con un token de seguridad en la URL. Ej: https://mitienda.cl/api/productos?token=MITOKEN

RESPUESTAEjemplo de respuesta esperada

<productos>
    <item>
        <id>1234</id>
        <sku>TALADRO-001</sku>
        <nombre>Taladro Percutor 650W Bosch</nombre>
        <familia>Herramientas</familia>
        <categoria>Herramientas Eléctricas</categoria>
        <link>https://micienda.cl/ficha/1234/taladro-percutor-650w</link>
        <thumbs>https://mitienda.cl/imagenes/1234-1.jpg</thumbs>
        <stock>15</stock>
        <precio>89990<precio>
        <precio_descuento>79990</precio_descuento>
        <marca>Bosch</marca>
        <descripcion>Taladro percutor de 650W ideal para trabajos en madera y metal...</descripcion>
        <keyword>taladro, percutor, bosch, herramienta eléctrica</keyword>
    </item>
    <item>
        <id>1234</id>
        <sku>TALADRO-001</sku>
        <nombre>Taladro Percutor 650W Bosch</nombre>
        <familia>Herramientas</familia>
        <categoria>Herramientas Eléctricas</categoria>
        <link>https://micienda.cl/ficha/1234/taladro-percutor-650w</link>
        <thumbs>https://mitienda.cl/imagenes/1234-1.jpg</thumbs>
        <stock>15</stock>
        <precio>89990<precio>
        <precio_descuento>79990</precio_descuento>
        <marca>Bosch</marca>
        <descripcion>Taladro percutor de 650W ideal para trabajos en madera y metal...</descripcion>
        <keyword>taladro, percutor, bosch, herramienta eléctrica</keyword>
    </item>
</productos>
                    
                // ... más productos

Formato del endpoint: Debe ser accesible vía GET idealmente con un token de seguridad en la URL. Ej: https://mitienda.cl/api/productos?token=MITOKEN

XML / JSON de Ventas

Un endpoint que devuelve el historial de pedidos pagados. Incluye qué productos se compraron en cada pedido. Este archivo es la base del motor de co-compras.

Campo XML / JSON	Estado	Descripción / Ejemplo
ID (pedido)	Obligatorio	Identificador único del pedido. Ej: `<ID>5001</ID>`
Fecha	Obligatorio	Fecha del pedido. Formato: `YYYY-MM-DD`. Ej: `<Fecha>2024-01-15</Fecha>`
Estado	Obligatorio	Estado del pedido. El motor filtra solo pedidos pagados. Ej: `"Pagado"`, `"Acreditado"`
ID_producto	Obligatorio	ID del producto comprado. Debe coincidir con el ID del feed de Productos. Ej: `<ID_producto>1234</ID_producto>`
Cantidad	Obligatorio	Unidades compradas. Ej: `<Cantidad>2</Cantidad>`
email	Obligatorio	Email del cliente. Usado para segmentación en email marketing.
SKU	Obligatorio	SKU del producto. Ej: `<SKU>SKU-001</SKU>`
Nombre	Obligatorio	Nombre del producto en el pedido
Precio_unitario	Obligatorio	Precio unitario del producto en el pedido
Familia	Recomendado	Familia del producto en el pedido
Categoria	Recomendado	Categoría del producto en el pedido
URL_Producto	Recomendado	Link del producto.
Thumbs	Recomendado	URL de imagen.

JSONEstructura esperada del JSON de ventas

[
      {
        "ID":       "1234",
        "Fecha":    "2024-01-15",
        "Estado":   "Pagado",
        "email":    "cliente@email.com",
        "productos_pedidos"[
                {
                    "ID_producto":      "1234",
                    "Cantidad":         1,
                    "Precio_unitario":  89990,
                    "Nombre":           "Taladro Percutor 650W Bosch",
                    "Codigo":           "TALADRO-001"
                },{
                    "ID_producto":      "454",
                    "Cantidad":         2,
                    "Precio_unitario":  89990,
                    "Nombre":           "Taladro 650W Bosch",
                    "Codigo":           "TDRO-001"
                }
            ]                
      }
      
      // ... más productos
    ]

Historial mínimo recomendado: 365 días de pedidos pagados. Con menos de 90 días el motor de co-compras puede no tener suficientes datos para generar recomendaciones de calidad.

XMLEstructura esperada del XML de ventas

<pedidos>

      <pedido>
        <ID>5001</ID>
        <Fecha>2024-01-15</Fecha>
        <Estado>Pagado</Estado>
        <email>cliente@email.com</email>

        <productos_pedidos>

          <producto>
            <ID_producto>1234</ID_producto>    <!-- debe coincidir con feed de productos -->
            <Cantidad>1</Cantidad>
            <Precio_unitario>89990</Precio_unitario>
            <Nombre>Taladro Percutor 650W Bosch</Nombre>
            <Codigo>TALADRO-001</Codigo>
          </producto>

          <producto>
            <ID_producto>5678</ID_producto>
            <Cantidad>2</Cantidad>
            <Precio_unitario>4990</Precio_unitario>
            <Nombre>Broca Set 10 Piezas</Nombre>
            <Codigo>BROCA-SET-010</Codigo>
          </producto>

        </productos_pedidos>
      </pedido>

      <!-- ... más pedidos -->

    </pedidos>

Historial mínimo recomendado: 365 días de pedidos pagados. Con menos de 90 días el motor de co-compras puede no tener suficientes datos para generar recomendaciones de calidad.

Instrucciones por plataforma

Selecciona tu plataforma de eCommerce para ver las instrucciones específicas de cómo generar los endpoints requeridos.

Shopify

REST Admin API

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Crear una app privada en tu Shopify con acceso de lectura a productos y pedidos
→Generar un endpoint con todos los productos activos de la tienda
→Generar un endpoint con todos los pedidos pagados del último año
→Proteger ambos endpoints con un token de seguridad en la URL

Shopify tiene una API REST nativa que expone productos y pedidos. Se recomienda crear una app privada para generar el token de acceso.

Crear app privadaVe a Configuración → Apps → Desarrollar apps → Crear app. Asigna permisos: read_products y read_orders.

Feed de ProductosUsar el endpoint nativo: GET /admin/api/2024-01/products.json?limit=250&fields=id,title,variants,product_type,vendor,images,handle. Tu dev debe crear un endpoint custom que normalice la respuesta al formato requerido.

XML / JSON de VentasUsar GET /admin/api/2024-01/orders.json?status=any&financial_status=paid&limit=250&created_at_min=FECHA. Tu dev debe transformar la respuesta JSON a XML o dejarlo como JSON, en el formato requerido.

PaginaciónShopify usa cursor-based pagination. Para catálogos grandes (+1.000 productos) tu dev debe implementar paginación con page_info.

Campos Shopify → Xellers: id → id, title → nombre, product_type → categoria, vendor → marca, images[0].src → thumbs, handle → construir URL del producto.

WooCommerce

REST API nativa

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Generar una clave API de solo lectura desde el panel de WooCommerce
→Crear un endpoint XML / JSON con todos los productos publicados de la tienda
→Crear un endpoint XML / JSON con todos los pedidos completados del último año
→Asegurarse de incluir los productos de cada pedido (line items) en el XML/JSON

WooCommerce incluye una API REST. Se accede con claves Consumer Key y Consumer Secret generadas desde el panel.

Generar credencialesVe a WooCommerce → Configuración → Avanzado → API REST → Añadir clave. Permiso: Solo lectura.

Feed de ProductosEndpoint: GET /wp-json/wc/v3/products?per_page=100&consumer_key=CK&consumer_secret=CS. Normalizar al formato requerido.

XML / JSON de VentasEndpoint: GET /wp-json/wc/v3/orders?status=completed&per_page=100. Transformar a XML / JSON en el formato requerido incluyendo los line_items de cada pedido.

CategoríasWooCommerce maneja categorías jerárquicas. Se recomienda usar categories[0].name como categoria y categories[0].parent como familia.

Campos WooCommerce → Xellers: id → id, name → nombre, sku → sku, stock_quantity → stock, images[0].src → thumbs, permalink → link.

VTEX

API REST + AppKey

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Generar credenciales de API (AppKey y AppToken) con acceso de solo lectura a productos y pedidos
→Crear un endpoint XML / JSON con todos los productos del catálogo en el formato requerido
→Crear un endpoint XML / JSON con todos los pedidos facturados del último año
→Incluir el stock consolidado de cada producto (sumado por warehouse si aplica)

VTEX tiene una API robusta. Se requiere AppKey y AppToken generados desde el panel de administración.

Generar credencialesEn el admin VTEX: Configuración de la cuenta → Gestión de la cuenta → Claves de aplicación. Asignar roles: Read products y Read orders.

Feed de ProductosUsar el endpoint de búsqueda de productos: GET /api/catalog_system/pub/products/search?_from=0&_to=49 con headers X-VTEX-API-AppKey y X-VTEX-API-AppToken.

XML / JSON de VentasUsar GET /api/oms/pvt/orders?f_status=invoiced&page=1&per_page=100. Transformar a XML / JSON incluyendo los items de cada orden.

StockVTEX maneja stock por warehouse. Usar GET /api/logistics/pvt/inventory/skus/{skuId} para obtener el stock total consolidado.

Campos VTEX → Xellers: productId → id, productName → nombre, brand → marca, categories → familia/categoria, images[0].imageUrl → thumbs, link → link.

PrestaShop

Webservice API

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Habilitar los Webservices de PrestaShop y crear una clave de acceso de solo lectura
→Crear un endpoint XML / JSON con todos los productos activos en el formato requerido
→Crear un endpoint XML / JSON con todos los pedidos pagados del último año, incluyendo el detalle de productos de cada pedido
→El stock de cada producto debe estar actualizado en el sistema

PrestaShop tiene su propio sistema de Webservices que debe habilitarse desde el panel de administración.

Habilitar WebservicesVe a Parámetros Avanzados → Webservices → Habilitar. Crear una clave con permisos GET en products, orders y order_details.

Feed de ProductosEndpoint: GET /api/products?output_format=JSON&display=[id,name,reference,price,categories,images,link_rewrite]. La URL del producto debe construirse con link_rewrite.

XML / JSON de VentasEndpoint de órdenes: GET /api/orders?output_format=JSON&filter[current_state]=5 (estado 5 = pagado). Luego cruzar con /api/order_details para obtener los productos de cada orden.

StockUsar GET /api/stock_availables?filter[id_product]=ID para obtener el stock de cada producto.

Nota: PrestaShop requiere dos llamadas para obtener los detalles de los productos de cada pedido (órdenes + order_details). Tu dev debe consolidar ambas en el XML / JSON final.

Magento 2

REST API + OAuth

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Crear una Integration en Magento con permisos de solo lectura en catálogo y ventas
→Generar un endpoint XML / JSON con todos los productos del catálogo en el formato requerido
→Generar un endpoint XML / JSON con todos los pedidos completados del último año
→Las URLs de imágenes deben ser absolutas (URL completa, no rutas relativas)

Magento 2 tiene una API REST completa. Se recomienda crear un Integration Token de solo lectura.

Crear IntegrationEn el admin: Sistema → Extensiones → Integraciones → Agregar nueva integración. Asignar permisos: Catalog → Products y Sales → Orders.

Feed de ProductosEndpoint: GET /rest/V1/products?searchCriteria[pageSize]=100&searchCriteria[currentPage]=1 con header Authorization: Bearer TOKEN.

XML / JSON de VentasEndpoint:

GET /rest/V1/orders?searchCriteria[filter_groups][0][filters][0][field]=status&searchCriteria[filter_groups][0][filters][0][value]=complete

. Los productos están en items[].items[].

ImágenesLas URLs de imágenes en Magento son relativas. Construir URL completa: BASE_URL/pub/media/catalog/product + media_gallery_entries[0].file.

Campos Magento → Xellers: id → id, sku → sku, name → nombre, extension_attributes.stock_item.qty → stock, custom_attributes[category_ids] → categoria.

Odoo

JSON-RPC / REST API

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Crear un usuario técnico de solo lectura en Odoo y generar una API Key
→Crear un endpoint XML / JSON con todos los productos publicados del catálogo en el formato requerido
→Crear un endpoint XML / JSON con todos los pedidos confirmados del último año, incluyendo los productos de cada pedido
→Las imágenes de productos deben tener URLs públicas accesibles (no base64)

Odoo expone sus datos a través de JSON-RPC (nativo en todas las versiones) y REST API (disponible desde Odoo 16 con el módulo web_rest_api). Se recomienda crear un usuario técnico de solo lectura.

Crear usuario técnicoEn el admin de Odoo: Configuración → Usuarios → Nuevo usuario. Asignar perfil de acceso interno con permisos de solo lectura en Inventario y Ventas. Generar API Key desde el perfil del usuario (Preferencias → API Keys).

Feed de ProductosUsar JSON-RPC sobre el modelo product.template. El endpoint es POST /web/dataset/call_kw con método search_read y campos: id, name, default_code, categ_id, list_price, qty_available, website_url, image_1920.

XML / JSON de VentasUsar el modelo sale.order con filtro state = 'sale' (pedidos confirmados/pagados). Cruzar con sale.order.line para obtener los productos de cada pedido. Tu dev debe transformar la respuesta a XML / JSON en el formato requerido.

ImágenesEn Odoo las imágenes se sirven como base64 en el campo image_1920 o como URL pública vía /web/image/product.template/ID/image_1920. Usar la URL pública para el campo thumbs.

CategoríasOdoo usa categ_id como categoría del producto. Si tienes categorías del sitio web (ecommerce), usar el modelo product.public.category para obtener la jerarquía familia/categoría.

Campos Odoo → Xellers: id → id, default_code → sku, name → nombre, categ_id[1] → categoria, qty_available → stock, list_price → precio, /web/image/product.template/ID/image_1920 → thumbs, website_url → link.

Nota Odoo eCommerce: Si usas el módulo de eCommerce de Odoo (website_sale), asegúrate de que los productos tengan is_published = True para que el link del producto sea accesible públicamente.

Jumpseller

REST API + OAuth2

👤Requerimiento— Esto es lo que se le tiene que pedir al desarrollador

→Crear un token de acceso API desde el panel de Jumpseller en Preferencias → API
→Generar un endpoint XML / JSON con todos los productos activos de la tienda en el formato requerido
→Generar un endpoint XML / JSON con todos los pedidos pagados del último año, incluyendo los productos de cada pedido
→Asegurarse de que las imágenes y links de productos sean URLs absolutas y públicas

Jumpseller tiene una API REST con autenticación OAuth2. Se accede con un Login (email) y un Token generado desde el panel de administración.

Obtener credencialesEn el admin de Jumpseller: Preferencias → API → Generar Token. Las credenciales son tu email de login + el token generado.

Feed de ProductosEndpoint: GET https://api.jumpseller.com/v1/products.json?login=EMAIL&authtoken=TOKEN&limit=100&page=1&status=available. Iterar páginas hasta obtener todos los productos.

XML / JSON de VentasEndpoint de órdenes: GET https://api.jumpseller.com/v1/orders.json?login=EMAIL&authtoken=TOKEN&status=paid&limit=100&page=1. Los productos de cada orden están en el campo products dentro de cada orden.

PaginaciónJumpseller limita a 100 registros por página. Para catálogos o historiales grandes tu dev debe iterar con &page=1, &page=2, etc. hasta que la respuesta venga vacía.

ImágenesLas imágenes están en images[0].url dentro de cada producto. Son URLs absolutas y públicas — úsalas directamente como thumbs.

Campos Jumpseller → Xellers: id → id, sku → sku, name → nombre, categories[0].name → categoria, stock → stock, price → precio, images[0].url → thumbs, url → link, brand → marca, description → descripcion.

Categorías: Jumpseller permite múltiples categorías por producto. Se recomienda usar categories[0] como categoria y categories[0].parent si existe como familia. Si no hay categoría padre, usar la misma categoría en ambos campos.

Checklist antes de entregar

Antes de enviar los endpoints a Xellers, verifica que todo esté correcto:

✓El Feed XML/JSON devuelve un array de productos (no un objeto con wrapper)
✓El campo id del feed XML / JSON coincide con el ID_producto del XML / JSON de ventas
✓Las URLs de imágenes (thumbs) son absolutas y accesibles públicamente
✓Las URLs de productos (link) son correctas y llevan a la ficha del producto
✓El campo stock refleja el inventario real (no siempre 0 ni siempre 99)
✓El XML / JSON de ventas incluye solo pedidos con estado Pagado o equivalente
✓El XML / JSON tiene al menos 90 días de historial de pedidos (ideal: 365 días)
✓Ambos endpoints tienen SSL activo (https://) con certificado válido
✓Los endpoints incluyen un token de seguridad en la URL
✓Las fechas en el XML / JSON están en formato YYYY-MM-DD

¿Dudas o problemas?

Contacto técnico Xellers: Una vez que tengas los endpoints listos, compártelos a tu ejecutivo de cuenta. Nuestro equipo técnico valida los feeds y hace el setup completo en menos de 48 horas.

Guía de Integraciónde Feeds y XML / JSON

¿Qué necesitamos y por qué?

Feed de Productos (XML/JSON)

XML / JSON de Ventas

Instrucciones por plataforma

Shopify

WooCommerce

VTEX

PrestaShop

Magento 2

Odoo

Jumpseller

Checklist antes de entregar

¿Dudas o problemas?

Guía de Integración
de Feeds y XML / JSON