Lien vers la documentation technique de l’API Présentation de l’API Data Guide de démarrage rapide Endpoints disponibles experience/(optionnel) collections/

💡

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 de l’API

Potions Experiences API - Swagger UI

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

Vous pouvez utiliser le site_id : 504 et le token Z8gib1CBfF2xQyrYVb0PewD4b7KThm8o pour accéder à des données d’exemple.

Présentation de l’API Data

L’API Data vous donne un accès programmatique aux données de Potions. Elle permet notamment de récupérer des listes de produits en fonction d’un contexte qui lui sera passé en paramètres.

Guide de démarrage rapide

Il suffit de quelques lignes de code pour appeler l'API afin de récupérer votre première liste de produits. Vous trouverez ci-dessous un exemple dans plusieurs langages de programmation.

Python

python
import requests
import json

SITE_ID = 1
EXPERIENCE_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa'
TOKEN = 'aaaaaaaaaa'


query = json.dumps({
	'product_id': '123'
})

res = requests.get(
	f'https://client.experiences.get-potions.com/v1/{SITE_ID}/experience/{EXPERIENCE_ID}?variables={query}',
	headers={'Authorization': f'Bearer {TOKEN}'}
)
res.raise_for_status()
data = res.json()
# {"name":"RP - Ajout panier","description":null,"products":["1","2","4"]}

JavaScript

javascript
const SITE_ID = 1;
const EXPERIENCE_ID = 'aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa';
const TOKEN = 'aaaaaaaaaa';

const query = JSON.stringify({
	product_id: '123'
});

const res = await fetch(
	`https://client.experiences.get-potions.com/v1/${SITE_ID}/experience/${EXPERIENCE_ID}?variables=${query}`,
	{
		headers: {
			Authorization: `Bearer ${TOKEN}`
		}
	}
);
const data = await res.json();
// {"name":"RP - Ajout panier","description":null,"products":["1","2","4"]}

Curl

bash
curl -X 'GET' \
  'https://client.experiences.get-potions.com/v1/$SITE_ID/experience/$EXPERIENCE_ID?variables=$QUERY' \
	-H 'Authorization: Bearer $TOKEN'
# {"name":"RP - Ajout panier","description":null,"products":["1","2","4"]}

Endpoints disponibles

L’accès aux données Potions se fait au travers d’endpoints sur les serveurs Potions.

L’endpoint principal est le endpoint experience/ permettant de récupérer programmatiquement les produits listés dans une expérience

GET https://client.experiences.get-potions.com/v1/{siteId}/experience/{experienceId}?variables={query}

Les autres endpoints sont optionnels et ne sont mis à disposition que si nécessaire.

experience/

Une expérience est un emplacement visible de vos clients et géré via Potions.

Chaque expérience dispose d’un nom et d’un id unique, par exemple :

nom : recommandations de produits - ajout panier

id : 125749

Suivant le type d’expérience, l’id d’expérience se retrouve sur votre site, dans votre outil d’e-mail, votre CMS, vos analytiques, le Lab Potions…

Il constitue également le point d’entrée de l’API Potions dans le cas d’expérience récupérant des listes de produits recommandés ou des tris de pages catégories (e-merchandizing)

Pour récupérer une liste de produits à partir d’un id d’expérience, l’endpoint à appeler est le suivant : GET https://client.experiences.get-potions.com/v1/{siteId}/experience/{experienceId}{queryString}

Avec :

siteId : l’id de votre site, fourni par Potions

experienceId : l’id d’expérience fourni par Potions, il diffèrera pour chaque emplacement

queryString contenant ces paramètres :

variables : un objet JSON contenant des variables contextuelles facultatives. Certaines variables sont nécessaires pour appeler des expériences, l’information vous sera alors transmise par Potions.

product_id : l’id du produit
product_ids : les ids des produits de la page
category_id : l’id de la catégorie
cart_product_ids : les ids des produits ajoutés au panier
…

Cet endpoint est aussi disponible en POST :

POST https://client.experiences.get-potions.com/v1/{siteId}/experience/{experienceId}

Avec :

siteId : l’id de votre site, fourni par Potions

experienceId : l’id d’expérience fourni par Potions, il diffèrera pour chaque emplacement

Un body en JSON contenant des variables contextuelles facultatives. Certaines variables sont nécessaires pour appeler des expériences, l’information vous sera alors transmise par Potions.

product_id : l’id du produit
product_ids : les ids des produits de la page
category_id : l’id de la catégorie
cart_product_ids : les ids des produits ajoutés au panier

Exemples d’utilisation

(optionnel) collections/

Présentation

L’API fournie par Potions permet si nécessaire de récupérer également des listes de produits directement via des collections.

Une collection est l’association de règles et d’algorithmes, dont l’execution fournit une listes de produits. Une collection peut être commune à plusieurs expériences.

Par exemple la collection “produits recommandés apèrs ajout panier” peut être utilisée à la fois dans l’expériences “pop-up ajout panier” et l’expérience “mail après ajout panier”.

Il existe trois types de collections :

Collection manuelle : 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ée dans la requête précédente,
	"parameters": {
		"product_ids": [],
		"cart_product_ids": []
		ou
		"category_id": "",
		"colors": [],
		"sizes": []
	}
}

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 manuelle

Une collection manuelle 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.

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.

Algorithm

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 GET /v1/{site_id}/algorithms

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

Settings

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.

La liste des champs disponibles est disponible sur l’endpoint GET /v1/{site_id}/fields

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.

Potions Data API