Procedimiento de integración del servicio de recomendaciones a través de la API

Copiar enlace al artículo

Copiado

Contenido

1. Registro y configuración del servicio de recomendaciones
   • Obtención de la lista de recomendaciones para un producto

Para mostrar en un pedido los productos complementarios deseados, es posible conectar un servicio de recomendaciones propio mediante la API.

Registro y configuración del servicio de recomendaciones

Para registrar y configurar el servicio de recomendaciones, es necesario utilizar el método POST /api/v5/integration-modules/{code}/edit. Si ya existe un módulo con el código {code}, el método actualiza su configuración; de lo contrario, crea un nuevo módulo de integración del servicio de recomendaciones. Los parámetros actuales del módulo pueden consultarse mediante el método GET /api/v5/integration-modules/{code}.

Al registrar el servicio, es necesario indicar su nombre en integrationModule[name], su código en integrationModule[code], la URL base en integrationModule[baseUrl] y el identificador de usuario en integrationModule[clientId]. clientId permite identificar al usuario en el sistema al realizar solicitudes de callback. Encontrará más información en el artículo sobre la activación de módulos.

El conjunto de pestañas se envía como un array en integrationModule[integrations][recommendation][modes]. Para cada pestaña deben definirse un código y sus nombres en los idiomas del sistema. El código de la pestaña se envía en el parámetro de URL mode al llamar al servicio de recomendaciones.

Los nombres se envían como un array asociativo: la clave corresponde al idioma del sistema (es o en) y el valor contiene el nombre de la pestaña en ese idioma. La clave en es obligatoria y la clave es puede omitirse. Si no se proporciona un nombre para un idioma, se utiliza el nombre correspondiente a en. El envío de una clave de idioma inexistente en el sistema provoca un error de validación.

[
    [
        'code' => 'upsell',
        'names' => [
            'es' => 'Productos de venta adicional',
            'en' => 'Products for upsell',
        ],
    ],
    [
        'code' => 'presents',
        'names' => [
            'en' => 'Presents',
        ],
    ],
]

Con este array, el sistema considera que el módulo de recomendaciones proporciona dos pestañas:

• Para la pestaña con el código upsell, en el idioma es se utiliza el valor de [names][es] y en en se utiliza Products for upsell.
• Para la pestaña con el código presents, se utiliza el nombre Presents en todos los idiomas.

También puede indicarse integrationModule[integrations][recommendation][addDefaultModes] con el valor true o false. El valor true permite mostrar, además de las pestañas del módulo, las pestañas del sistema «Con este producto compran» y «Análogos».

Si el módulo admite las pestañas del sistema, sus propias pestañas no pueden utilizar los códigos analogs ni buying_with. En la configuración del módulo pueden desactivarse las pestañas del sistema aunque addDefaultModes tenga el valor true.

Las pestañas se muestran en el siguiente orden:

• Pestaña del sistema «Con este producto compran», si está activada en la configuración del módulo.
• Pestaña del sistema «Análogos», si está activada en la configuración del módulo.
• Pestañas proporcionadas por el módulo, en el mismo orden en que aparecen en integrationModule[integrations][recommendation][modes].

También puede indicarse el logotipo del servicio en integrationModule[logo]. El logotipo se muestra en la lista de integraciones de la sección Marketplace.

Para activar los métodos de callback, es necesario enviar la configuración de cada método requerido en integrationModule[integrations][recommendation][actions]. Para cada método deben indicarse el código code y la URL url. La dirección de la solicitud se forma a partir de integrationModule[baseUrl] y la url del método concreto.

Obtención de la lista de recomendaciones para un producto

Para obtener la lista de recomendaciones, el sistema realiza una solicitud GET al método con el código recommendation del array integrationModule[integrations][recommendation][actions]. A la url del método se añaden los siguientes parámetros:

• ids[]: ID de los productos.
• externalIds[]: externalId de los productos.
• mode: código de la pestaña. Los valores posibles se toman de los códigos incluidos en integrationModule[integrations][recommendation][modes] al crear o editar el módulo.

Como respuesta, el servicio de recomendaciones debe devolver un objeto con los siguientes campos:

• by: campo mediante el cual el sistema debe identificar los productos. Los valores posibles son id y externalId.
• ids: array con los identificadores de los productos.