Lien vers la documentation technique Collections Récupérer une collection existante Paramètres Créer une requête de collection Collection personnalisée Collection dynamique Algorithme Configuration Collection composée

💡

Pour utiliser cette API, vous aurez besoin d’un token d’authentification ainsi que de votre site_id. Ces deux informations sont présentes dans le cowork fourni par Potions.

Pour authentifier vos requêtes, il faut rajouter un header Authorization contenant le token d’API à chaque requête.

Pour s’authentifier dans la documentation, il faut cliquer sur le bouton “Authorize” puis rentrer le token. Le header contenant le token sera ensuite automatiquement rajouté à chaque requête.

Lien vers la documentation technique

Potions Experiences API - Swagger UI

https://client.experiences.get-potions.com/v1/docs

Collections

L’API fournie par Potions permet de récupérer des collections de produits.

Il y a trois types de collections :

Collection personnalisée : renvoie une liste de produits prédéfinie

Collection dynamique : renvoie une liste de produits générée par un algorithme en fonction des paramètres qui lui sont envoyés

Collection composée : renvoie une liste de produits générée à partir d’autre collections, elle permet de mixer des collections personnalisées, dynamiques et composées

Il existe deux moyens de requêter des collections : en utilisant l’id d’une collection existante ou en créant une requête de collection.

Récupérer une collection existante

Pour lister les collections existantes, il faut appeler l’endpoint GET /v1/{site_id}/collections.

Ensuite, il faut appeler l’endpoint POST /v1/{site_id}/collection en lui passant un body en JSON sous cette forme :

json
{
	"collection_id": id de la collection récupéré dans la requête précédente,
	"parameters": {
		"product_id": "",
		ou
		"product_ids": [],
		ou
		"category_id": "",
		"colors": [],
		"sizes": []
	}
}

Paramètres

Les paramètres sont utilisés pour indiquer à l’algorithme la valeur à récupérer.

Pour savoir quel paramètre renseigner, il faut regarder dans la clé required_parameter de la collection.

Créer une requête de collection

Une requête de collection se présente sous cette forme :

json
{
  "query": {
    "algorithm": "collaborative_filtering_transactions",
    "settings": {
      "size": 20,
      "fields": "all",
      "filters": []
    }
  },
  "parameters": {
    "product_id": "1001"
  }
}

Les différentes clés à inclure dans query pour chaque type de collection sont indiqués ci-dessous.

Pour parameters, il faut se référer à cette partie.

Collection personnalisée

Une collection personnalisée est constituée d’une liste d’id de produits dans la clé product_ids.

Collection dynamique

Une collection dynamique est constituée d’un algorithme et d’une configuration.

Algorithme

Un algorithme associe une liste de produits à un produit ou à une catégorie. Il peut par exemple fournir les informations sur les produits achetés ou vus ensemble.

La liste des algorithmes est disponible sur l’endpoint /v1/{site_id}/algorithms

Voici un exemple de liste d’algorithmes que Potions peut mettre à disposition

Configuration

La configuration permet de modifier la collection qui sera retournée, elle permet d’agir sur le nombre, les champs ainsi que les caractéristiques des produits retournés.

Nombre de produits :

La clé size accepte une valeur entière positive. La valeur -1 est aussi acceptée, elle indique qu’il n’y a pas de limite de nombre de produits.

Champs des produits :

La clé fields accepte soit une liste des champs à retourner, soit la valeur all qui permet de renvoyer l’ensemble des champs de chaque produit.

Filtres :

La clé filters permet d’appliquer des filtres sur les produits retournés ce qui permet par exemple d’exclure certains produits en fonction de leur prix ou de leur catégorie.

Elle accepte en argument une liste de règles.

Collection composée

Une collection composée est elle aussi composée d’un paramètre et d’une configuration, cependant elle remplace l’algorithme par une liste de collections.

Cette liste de collection se trouve dans la clé composed_collections, elle peut contenir aussi bien des ids que des requête de collections.

🇫🇷 Potions Experiences API v1