À retenir : Notre collection Postman permet d’explorer l’API en configurant votre clé dans une variable. Ce guide vous montre comment vérifier le service, rechercher des produits et des ingrédients, utiliser les filtres et les lots, puis comprendre les réponses d’erreur.

Postman vous permet d’observer les requêtes et les réponses sans écrire votre intégration. La collection comprend des scripts de test : l’onglet des résultats indique si chaque appel s’est comporté comme prévu.

Étape 1 : obtenir une clé API

Connectez-vous au tableau de bord et créez une clé. Les nouveaux clients bénéficient d’un essai de sept jours avec 100 requêtes au total. L’offre payante sélectionnée commence à la fin des sept jours, sauf résiliation. La clé n’est affichée qu’une fois : conservez-la dans un emplacement sûr. Choisissez une offre incluant les codes-barres pour essayer cette fonction. Les autres points d’accès sont disponibles dans toutes les offres.

Étape 2 : importer la collection

Téléchargez le fichier de collection, the-beauty-api.postman_collection.json, au format Postman v2.1. Dans Postman, choisissez File → Import et sélectionnez le fichier, ou faites-le glisser dans la barre latérale. La collection The Beauty API contient quatre dossiers dont les noms sont conservés en anglais dans le fichier :

  1. Start here : état du service, recherche et consultation d’un produit.
  2. Products : filtres, lots et codes-barres.
  3. Ingredients : recherche et consultation d’un ingrédient.
  4. Errors you should expect : requêtes prévues pour renvoyer des erreurs.

Chaque requête comprend une description. La description générale de la collection résume également son fonctionnement.

Étape 3 : configurer votre clé

Sélectionnez la collection, ouvrez Variables et renseignez la valeur locale de apiKey. Selon votre version de Postman, cette valeur peut être appelée Current value. Gardez votre clé privée et vérifiez qu’elle n’est pas incluse dans les valeurs partagées ou les exports.

L’onglet Authorization est déjà configuré avec le type API Key, l’en-tête x-api-key et la valeur {{apiKey}}. Les requêtes héritent de cette configuration. Les autres variables sont :

  • baseUrl : https://api.thebeautyapi.com, pour toutes les offres, y compris la recherche par code-barres.
  • productId et ingredientId : des identifiants d’exemple. Les recherches les remplacent par le premier résultat, pour vous permettre d’ouvrir ensuite la fiche complète.
  • barcode : un UPC d’exemple pour la recherche par code-barres.

Étape 4 : vérifier le service, rechercher et ouvrir une fiche

Health. Envoyez cette requête en premier. Elle ne nécessite pas de clé et indique l’état du service, les nombres de produits et d’ingrédients du catalogue API ainsi que sa date de préparation. Voici un exemple de réponse de la version du 3 novembre 2026 :

{"status": "ok", "products": 258648, "ingredients": 26420, "built_at": "2026-11-03"}

Si cette requête échoue, vérifiez l’adresse baseUrl, la connexion et la disponibilité du service.

Search products. GET /v1/products/search?q=ordinary niacinamide&page=1 recherche par marque et nom, avec prise en charge des préfixes et 20 résultats par page. La réponse contient des fiches résumées avec notamment id, brand, name, category et image_url. Le script enregistre le premier identifiant dans productId.

Get a product. GET /v1/products/{{productId}} renvoie la fiche complète : informations produits, indicateurs de formulation et ingrédients liés aux fiches INCI. Les tests contrôlent la structure et l’ordre des listes uniques, sections et composants de coffrets. La documentation des ingrédients décrit ces champs.

Étape 5 : explorer les filtres, les lots et les ingrédients

Le dossier Products présente trois recherches filtrées : des soins sans parfum, des produits contenant un ingrédient avec has_ingredient et des produits excluant des ingrédients avec excludes_ingredient. Ce dernier accepte jusqu’à dix identifiants séparés par des virgules. Modifiez les paramètres dans l’onglet Params puis renvoyez la requête.

Batch utilise POST et un corps JSON contenant entre 1 et 50 identifiants. Il renvoie les fiches complètes dans une seule réponse. Vous pouvez y ajouter des identifiants obtenus lors d’une recherche pour simuler une routine.

Le dossier Ingredients recherche par nom de référence et synonymes. Par exemple, vitamin b3 permet de retrouver Niacinamide. La fiche détaillée contient les numéros CAS et CE disponibles. Pour filtrer les produits, utilisez l’identifiant id renvoyé par l’API pour chaque ingrédient.

Étape 6 : observer volontairement les erreurs

Dans le dernier dossier, les requêtes sont conçues pour échouer ou renvoyer un résultat vide. Un test réussi indique que l’API a répondu comme prévu :

RequêteRéponseTraitement dans votre application
Clé API manquante403, Invalid or missing API keyVérifiez la présence et la validité de apiKey.
Recherche sans correspondance, q=asdfghjkl200, results: [], has_more: falseIndiquez qu’aucun résultat n’a été trouvé, sans relancer la même recherche automatiquement.
Recherche ne contenant que des symboles, q=???400, q contains no searchable charactersDemandez une recherche contenant des lettres ou des chiffres.
Page au-delà de la limite, page=99400Les pages vont de 1 à 51. Arrêtez lorsque has_more vaut faux.
Identifiant produit mal formé400Utilisez un UUID valide.
Identifiant inconnu404Indiquez que la fiche n’a pas été trouvée.
Tableau ids vide400Le lot doit contenir entre 1 et 50 identifiants.

Vous pouvez aussi recevoir 429 lorsque vous atteignez une limite de fréquence ou le quota d’essai. Espacez les requêtes en cas de limitation de fréquence. Si le quota d’essai est épuisé, vous pouvez activer l’offre payante ou attendre la fin de l’essai. Une recherche par code-barres renvoie 403 si votre offre ne l’inclut pas. La documentation détaille les erreurs.

Passer de Postman à votre code

Le bouton Code, représenté par </>, permet de copier une requête en curl, JavaScript, Python ou dans un autre langage. Gardez la clé sur votre serveur dans une variable d’environnement. Ne l’intégrez pas au code distribué dans un navigateur ou une application mobile. Notre guide de recommandation de soins montre comment relier ces appels.

Questions fréquentes

La collection fonctionne-t-elle pendant l’essai ?

Oui, dans la limite de 100 requêtes au total sur sept jours. Choisissez une offre avec codes-barres pour essayer ce point d’accès. Pendant l’essai, une requête par lot compte pour une requête ; avec une offre payante, chaque élément demandé est comptabilisé dans votre consommation.

Pourquoi Health fonctionne-t-il sans clé ?

C’est une vérification publique de disponibilité. Tous les points d’accès /v1 nécessitent l’en-tête x-api-key.

Peut-on exécuter toute la collection ?

Oui, avec Run collection. Le Collection Runner envoie les requêtes dans l’ordre et rassemble les résultats. Les tests du dossier d’erreurs doivent réussir puisqu’ils attendent précisément ces codes d’erreur.

Le fichier contient-il ma clé ?

Le fichier téléchargé contient une variable apiKey vide. Gardez votre valeur locale privée et vérifiez tout export avant de le partager.

Préparer votre intégration

Importez la collection, configurez la clé, puis parcourez les dossiers en observant les réponses et les tests. La documentation explique chaque champ, et le tableau de bord présente votre consommation.