> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kameleoon.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Kameleoon.API.Products: Recommendations and search

> Referencia de los métodos Kameleoon.API.Products que recuperan productos recomendados, resultados de búsqueda, interacciones con productos, datos de producto y colecciones recomendadas.

Use estos métodos para recuperar productos recomendados, resultados de búsqueda, interacciones con productos, datos de producto y colecciones recomendadas.

> [!NOTE]
>
> Este módulo está disponible al suscribirse al módulo Product Recommendation o al add-on Product Targeting.

Las recomendaciones necesitan un seguimiento de productos correcto para devolver resultados útiles. Consulte [Kameleoon.API.Products: Tracking](https://docs.kameleoon.com/es/developer-docs/apis/activation-api-js/api-reference/modules/products-tracking.md).

## obtainRecommendedProducts

El método `obtainRecommendedProducts()` recupera los productos recomendados calculados por el algoritmo especificado mediante una llamada asincrónica al servidor.

```javascript theme={null}
Kameleoon.API.Products.obtainRecommendedProducts(
  "1a2b3c4d",
  {
    item: 123500,
    exclude: [3, 14, 159, 26535],
    category: 146,
    search_query: "To be or not to be",
    limit: 15,
    brands: ["Alas", "poor", "Yorick", 'kameleooner'],
    categories: [1, 146, 123500]
  },
  function (response) {
    // funcionalidad para renderizar un bloque de recomendaciones de producto
  },
  function (error) {
    // cuando algo ha ido mal
  }
);
```

> [!WARNING]
>
> Este método requiere un seguimiento de producto correcto, como `trackProductView()` o `trackCategoryView()`, para devolver resultados significativos.

**Argumentos**

| Nombre | Tipo | Descripción |
| - | - | - |
| code | String | Código único del bloque de recomendaciones. |
| params | Object | [Parámetros para controlar los datos devueltos por la plataforma de recomendaciones.](#parámetros-para-controlar-los-datos-devueltos-por-la-plataforma-de-recomendaciones) |
| successCallback | Function | Función callback que recibe el objeto de respuesta de la API. Este campo es obligatorio. |
| errorCallback | Function | Función callback que se ejecuta si se produce un error. Este campo es opcional. |

### Parámetros para controlar los datos devueltos por la plataforma de recomendaciones

| Nombre | Tipo | Descripción |
| - | - | - |
| item | String | ID del producto actual. Obligatorio para los algoritmos "Similar" y "They also bought this product". |
| exclude | Array | Lista separada por comas de identificadores de producto que se van a excluir. |
| extended | Number | Cuando es "1", el método devuelve los detalles completos del producto. Si se omite, solo devuelve los IDs de producto. |
| category | Number | Obligatorio para los algoritmos en páginas de categoría. Limita las recomendaciones a la categoría especificada. |
| categories | Array | Este campo es opcional. Si se utiliza, devuelve productos recomendados únicamente de las categorías especificadas (lista separada por comas de IDs de categoría). |
| brands | Array | Este campo es opcional. Si se utiliza, devuelve productos recomendados únicamente de las marcas especificadas (lista separada por comas de marcas). |
| locations | Array | Este campo es opcional. Si se utiliza, devuelve productos recomendados disponibles en las ubicaciones indicadas (lista separada por comas de IDs de ubicación). |
| limit | Number | Este campo es opcional. Número máximo de productos recomendados. |
| exclude\_brands | Number | Este campo es opcional. Lista de marcas separadas por comas que se excluirán de la recomendación. |

**Respuesta de la API**

La función callback recibe el objeto de respuesta de la API con los siguientes valores.

| Nombre | Tipo | Descripción |
| - | - | - |
| html | String | El código HTML del bloque. Personalice la plantilla HTML en la cuenta personal de Kameleoon. |
| title | String | Título del bloque. Corresponde al valor del elemento "Action" en las reglas del bloque. |
| products | Array | Lista de IDs de producto. |
| id | Number | Identificador único del bloque. Corresponde al ID del bloque en la lista de bloques de la cuenta personal de Kameleoon. |

## obtainInstantSearchProducts

El método `obtainInstantSearchProducts()` recupera resultados de búsqueda instantánea personalizados de Kameleoon Search mediante una llamada asincrónica al servidor.

```javascript theme={null}
Kameleoon.API.Products.obtainInstantSearchProducts(
 {
  search_query: "To be or not to be"
 },
 function (response) {
  // funcionalidad para renderizar un bloque desde instant search
 },
 function (error) {
  // para gestionar cuándo algo va mal
 }
);
```

**Argumentos**

| Nombre | Tipo | Descripción |
| - | - | - |
| search\_query | String | Consulta de búsqueda proporcionada por el usuario. Este campo es obligatorio. |
| successCallback | Function | Función callback que recibe el objeto de respuesta de la API. Este campo es obligatorio. |
| errorCallback | Function | Función callback que se ejecuta si se produce un error. Este campo es opcional. |

**Respuesta de la API**

La función de devolución de llamada recibe el objeto de respuesta de la API con los siguientes valores. En la tabla, `[]` indica un array de objetos, por lo que `products[].name` es el nombre de cada producto.

| Nombre | Tipo | Descripción |
| - | - | - |
| search\_query | String | Consulta de búsqueda. |
| categories | Array | Array con información sobre las categorías. |
| categories\[].id | String | ID de la categoría. |
| categories\[].name | String | Nombre de la categoría. |
| categories\[].url | String | URL de la categoría. |
| categories\[].count | Number | Número de productos de la categoría. |
| filters | Array | Array con información sobre los filtros. |
| filters\[].filter.count | Number | Número total de productos con estos parámetros. |
| filters\[].filter.values\[].value | String | Etiqueta del valor. |
| filters\[].filter.values\[].count | Number | Número de productos con este parámetro. |
| html | String | Código HTML del bloque con productos. Personalice la plantilla en su cuenta personal de Kameleoon. |
| price\_range | Object | Precio mínimo y máximo de los productos. |
| price\_range.min | Number | Precio mínimo. |
| price\_range.max | Number | Precio máximo. |
| products | Array | Array con información sobre los productos. |
| products\[].description | String | Descripción del producto. |
| products\[].url | String | URL absoluta del producto. |
| products\[].url\_handle | String | URL relativa del producto. |
| products\[].picture | String | URL de la imagen del producto en el almacenamiento de Kameleoon. |
| products\[].name | String | Nombre del producto. |
| products\[].price | Number / int | Precio del producto. |
| products\[].price\_full | Number / float | Precio del producto. |
| products\[].price\_formatted | String | Precio del producto con la moneda. |
| products\[].price\_full\_formatted | String | Precio del producto con la moneda. |
| products\[].image\_url | String | URL absoluta de la imagen del producto en el almacenamiento de Kameleoon. |
| products\[].image\_url\_handle | String | URL relativa de la imagen del producto en el almacenamiento de Kameleoon. |
| products\[].image\_url\_resized | Array | URL de las versiones redimensionadas de la imagen del producto. |
| products\[].currency | String | Moneda del producto. Corresponde a la moneda de su cuenta personal de Kameleoon o a un valor personalizado especificado en la configuración de la tienda de la cuenta. |
| products\[].id | String | ID del producto. |
| products\[].old\_price | Number / int | Precio anterior del producto. El valor por defecto es 0. |
| products\[].old\_price\_full | Number / float | Precio anterior del producto. |
| products\[].old\_price\_formatted | String | Precio anterior del producto con la moneda. |
| products\[].old\_price\_full\_formatted | String | Precio anterior del producto con la moneda. |
| products\[].categories | Array | Categorías del producto. Solo se incluyen cuando la petición pasa el parámetro `extended`. |
| products\[].categories\[].id | String | ID de la categoría. |
| products\[].categories\[].name | String | Nombre de la categoría. |
| products\[].categories\[].parent\_id | String | ID de la categoría padre. |
| products\[].categories\[].url | String | URL de la categoría. |
| products\[].categories\[].category\_ids | Array | IDs de las categorías del producto. |
| search\_query\_redirects | Array | Array con información sobre las redirecciones. |
| search\_query\_redirects\[].query | String | Consulta de búsqueda. |
| search\_query\_redirects\[].redirect\_link | String | URL de la redirección. |
| search\_query\_redirects\[].deep\_link | String | URL para aplicaciones móviles. |
| products\_total | Number | Número total de productos. |

## obtainFullSearchProducts

Use el método `obtainFullSearchProducts()` para recuperar resultados de búsqueda completos de la solución Kameleoon Search con opciones de filtrado.

```javascript theme={null}
Kameleoon.API.Products.obtainFullSearchProducts(
 {
  search_query: "To be or not to be",
  limit: 15,
  brands: ["Alas", "poor", "Yorick"],
  categories: [1, 146, 100500],
  filters: { key: ["value"], key: ["value"] },
  sort_by: "price",
  order: "asc"
 },
 function (response) {
  // funcionalidad para renderizar un bloque desde full search
 },
 function (error) {
  // cuando algo ha ido mal
 }
);
```

**Argumentos**

| Nombre | Tipo | Descripción |
| - | - | - |
| search\_query | Object | Consulta de búsqueda proporcionada por el usuario y parámetros opcionales de filtro. Revise los parámetros de filtrado en la siguiente sección. Este campo es obligatorio. |
| successCallback | Function | Función callback que recibe el objeto de respuesta de la API. Este campo es obligatorio. |
| errorCallback | Function | Función callback que se ejecuta si se produce un error. Este campo es opcional. |

### Parámetros para filtrar los resultados

| Nombre | Tipo | Descripción |
| - | - | - |
| search\_query | String | Consulta de búsqueda. Este campo es obligatorio. |
| limit | Number | Límite de resultados. Este campo es opcional. |
| offset | Number | Offset de resultados. Este campo es opcional. |
| category\_limit | Number | Cuántas categorías devolver para el filtro lateral. Este campo es opcional. |
| categories | Array | Lista separada por comas de categorías para filtrar. Este campo es opcional. |
| extended | Number | Establezca en `true` para obtener resultados de búsqueda completos. |
| sort\_by | String | Parámetro de ordenación: `popular`, `price`, `discount`, `sales_rate`, `date`. Este campo es opcional. |
| order | String | Dirección de ordenación: asc o desc (por defecto). Este campo es opcional. |
| locations | Array | Lista separada por comas de IDs de ubicaciones. Este campo es opcional. |
| brands | Array | Lista separada por comas de marcas para filtrar. Este campo es opcional. |
| filters | String | Cadena JSON escapada opcional con parámetros de filtro. Por ejemplo: `{"bluetooth":["yes"],"offers":["15% cashback"],"weight":["1.6"]}`. Este campo es opcional. |
| price\_min | Number | Precio mínimo. Este campo es opcional. |
| price\_max | Number | Precio máximo. Este campo es opcional. |
| colors  false | Array | Lista separada por comas de colores. Este campo es opcional. |
| fashion\_sizes | Array | Lista separada por comas de tallas. Este campo es opcional. |
| exclude | Array | Lista separada por comas de IDs de producto que se excluirán de los resultados. Este campo es opcional. |
| email | String | Solo para integración S2S, cuando el servicio no dispone de la sesión del usuario. El SDK móvil no lo usa. Este campo es opcional. |
| no\_clarification | Boolean | Desactiva la búsqueda aclarada. El valor por defecto es **false**. No use este parámetro salvo que el soporte de Kameleoon se lo indique. |
| merchants | Array | Lista separada por comas de comerciantes. Este campo es opcional. |
| filters\_search\_by | String | Opciones disponibles para el filtro: `name`, `quantity`, `popularity`. Este campo es opcional. |

**Respuesta de la API**

La función de devolución de llamada recibe el objeto de respuesta de la API con los siguientes valores. En la tabla, `[]` indica un array de objetos, por lo que `products[].name` es el nombre de cada producto.

| Nombre | Tipo | Descripción |
| - | - | - |
| search\_query | String | Consulta de búsqueda introducida por el usuario. |
| brands | Array | Array con información sobre las marcas. |
| brands\[].name | String | Nombre de la marca. |
| brands\[].picture | String | Imagen de la marca. |
| categories | Array | Array con información sobre las categorías. |
| categories\[].alias | String | Alias de la categoría. |
| categories\[].id | String | ID de la categoría. |
| categories\[].name | String | Nombre de la categoría. |
| categories\[].parent | String | ID de la categoría padre. |
| categories\[].url | String | URL de la categoría. |
| filters | Array | Array con información sobre los filtros. |
| filters\[].filter.count | Number | Número total de productos con estos parámetros. |
| filters\[].filter.values\[].value | String | Etiqueta del valor. |
| filters\[].filter.values\[].count | Number | Número de productos con este parámetro. |
| html | String | Código HTML del bloque con productos. Personalice la plantilla en su cuenta personal de Kameleoon. |
| price\_range | Object | Precio mínimo y máximo de los productos. |
| price\_range.min | Number | Precio mínimo. |
| price\_range.max | Number | Precio máximo. |
| products | Array | Array con información sobre los productos. |
| products\[].brand | String | Marca del producto. |
| products\[].currency | String | Moneda del producto. Corresponde a la moneda de su cuenta personal de Kameleoon o a un valor personalizado especificado en la configuración de la tienda de la cuenta. |
| products\[].id | String | ID del producto. |
| products\[].is\_new | Boolean | Propiedad del producto. El valor por defecto es null. |
| products\[].name | String | Nombre del producto. |
| products\[].old\_price | String | Precio anterior del producto. El valor por defecto es 0. |
| products\[].picture | String | URL de la imagen del producto en el almacenamiento de Kameleoon. |
| products\[].price | Number | Precio del producto. |
| products\[].price\_formatted | String | Precio del producto con la moneda. |
| products\[].url | String | URL del producto. |
| products\[].barcode | String | Código de barras del producto. Solo se incluye cuando la petición pasa el parámetro `extended`. |
| products\[].categories | Array | Categorías del producto. |
| products\[].categories\[].id | String | ID de la categoría. |
| products\[].categories\[].name | String | Nombre de la categoría. |
| products\[].categories\[].parent | String | ID de la categoría padre. |
| products\[].params | Array | Información sobre los parámetros del producto. |
| products\[].params\[].key | String | Nombre del parámetro. |
| products\[].params\[].values | Array | Valores del parámetro. |
| products\_total | Number | Número total de productos. |

## obtainProductInteractions

El método `obtainProductInteractions()` recupera métricas de interacción de productos rastreados mediante `trackProductView()`, `trackTransaction()` o `trackAddToCart()`.

```javascript theme={null}
Kameleoon.API.Products.obtainProductInteractions("123456", product => {
  console.log("product", product); // {123456: {views: 1, cartQuantities: 0, boughtQuantities: 0}}
});
Kameleoon.API.Products.obtainProductInteractions(["123456", "654321"], products => {
  console.log("products", products);
});
Kameleoon.API.Products.obtainProductInteractions(
  "123456",
  callback,
  new Date().getTime() - 1000 * 60 * 60 * 24, // timeBegin
  new Date().getTime() // timeEnd
);
```

**Argumentos**

| Nombre | Tipo | Descripción |
| - | - | - |
| eans | Array | IDs de producto (como Strings). Este campo es obligatorio. |
| callback | Function | Función callback que recibe los datos del producto. Este campo es obligatorio. |
| timeBegin | Number | Inicio del rango de fechas (timestamp UNIX en milisegundos). |
| timeEnd | Number | Fin del rango de fechas (timestamp UNIX en milisegundos). |

**Respuesta de la API**

| Nombre | Tipo | Descripción |
| - | - | - |
| eans | Array | Identificador único del producto. Cada ID de producto se asigna a un objeto que contiene métricas de interacción. |
| views | integer | Número de veces que los visitantes vieron el producto. |
| cartQuantities | integer | Número total de veces que los visitantes añadieron el producto a su carrito. |
| boughtQuantities | integer | Número total de veces que los visitantes compraron el producto. |

## obtainProductData

El método `obtainProductData()` recupera la información de los productos enviados mediante `trackProductView()`.

```javascript theme={null}
Kameleoon.API.Products.obtainProductData("123456", product => {
  console.log("product", product);
});
Kameleoon.API.Products.obtainProductData(["123456", "654321"], products => {
  console.log("products", products);
});
Kameleoon.API.Products.obtainProductData("123456", callback, {
  name: true,
  categoryId: true
}); // {123456: {name: '', categoryId: '' }}
```

**Argumentos**

| Nombre | Tipo | Descripción |
| - | - | - |
| eans | Array | IDs de producto (como Strings). Este campo es obligatorio. |
| callback | Function | Función callback que recibe los datos del producto. Este campo es obligatorio. |
| parameters | Object | Parámetros opcionales para recuperar campos específicos. Por defecto `{ all: true }`. |

**Respuesta de la API**

| Nombre | Tipo | Descripción |
| - | - | - |
| eans | Array | Identificador único del producto. Cada ID de producto se asigna a un objeto que contiene métricas de interacción. |
| productData | Object | [Objeto Product](https://docs.kameleoon.com/es/developer-docs/apis/activation-api-js/api-reference/objects/goal-segment-trigger-and-product.md#product). Este campo recibe el mismo objeto que envía `trackProductView`. |

## obtainRecommendedCollections

El método `obtainRecommendedCollections()` recupera los productos de la colección especificada.

```javascript theme={null}
Kameleoon.API.Products.obtainRecommendedCollections("123456", collections => {
    /* Funcionalidad para renderizar un bloque de colección de productos */
    console.log("collections", collections);
}, error => {
    /* Lógica de gestión de errores si algo va mal */
});
```

**Argumentos**

| Nombre | Tipo | Descripción |
| - | - | - |
| collectionId | String | ID de la colección de productos, disponible en la sección del dashboard de Product Collections. |
| successCallback | Function | Función callback que recibe el objeto de respuesta de la API. Este campo es obligatorio. |
| errorCallback | Function | Función callback que se ejecuta si se produce un error. Este campo es opcional. |

**Respuesta de la API**

**Products**

La API devuelve un array de objetos. Cada objeto del array `products` contiene lo siguiente:

| **Parámetro** | **Tipo** | **Descripción** |
| - | - | - |
| name | String | Nombre del producto |
| url | String (URL) | URL de la página del producto |
| description | String | Descripción del producto |
| category\_ids | Array of Strings | Lista de IDs de categorías a las que pertenece el producto |
| brand | String | Marca del producto |
| fashion\_feature | String | Característica fashion (por ejemplo, `"adult"`) |
| fashion\_gender | String | Género al que se destina el producto |
| sales\_rate | Integer | Tasa de ventas del producto |
| relative\_sales\_rate | Float | Tasa de ventas relativa a otros productos |
| picture | String (URL) | URL de la imagen principal del producto |
| categories | Array of Objects | Lista de objetos de categoría (estructura definida por el sistema) |
| price\_formatted | String | Precio formateado del producto (por ejemplo, `$29.99`) |
| price\_full\_formatted | String | Precio completo/original formateado |
| price | Float | Precio actual del producto |
| price\_full | Float | Precio original/completo antes de descuentos |
| image\_url | String (URL) | URL de la imagen redimensionada del producto |
| image\_url\_handle | String (URL) | URL procesada de la imagen (basada en handle) |
| image\_url\_resized | String (URL) | URL redimensionada de la imagen |
| url\_handle | String | URL handle utilizada para acceder al producto dentro de la colección |
| currency | String | Código de moneda utilizado para el precio del producto (por ejemplo, `USD`, `EUR`) |
| id | String | ID del producto (numérico o string según el sistema) |
| html | String (HTML) | La plantilla HTML seleccionada al crear la colección |