À retenir : Un scanner permet à l’utilisateur de pointer son appareil photo vers un emballage pour retrouver un produit et ses ingrédients. Prévoyez également le parcours à suivre lorsque le code n’est pas reconnu. Ce guide explique les GTIN, la recherche avec The Beauty API et le retour vers une recherche par nom.
Comprendre les codes-barres des produits
Les numéros utilisés pour identifier les articles sont des GTIN, ou Global Trade Item Numbers, dans le système GS1. Le préfixe d’entreprise GS1 participe à leur attribution. Le dernier chiffre sert à contrôler la cohérence du numéro.
Les variantes commercialisées séparément peuvent avoir des GTIN distincts : teintes d’un fond de teint, contenances d’une crème ou parfums d’une gamme. Un nom de produit ne suffit donc pas à déterminer sa variante ou sa formule.
Un même identifiant peut aussi être représenté sous plusieurs formes. On rencontre notamment UPC-A à 12 chiffres, EAN-13 à 13 chiffres et GTIN-8 à 8 chiffres. Ces formes peuvent être représentées sur 14 chiffres en ajoutant des zéros à gauche. Ainsi, 769915195941 et 00769915195941 représentent le même code. Les bibliothèques de scan peuvent renvoyer des formes différentes.
Étape 1 : lire le code
Utilisez une bibliothèque de scan adaptée à votre plateforme, par exemple ML Kit, le framework Vision d’iOS ou une intégration pour React Native ou Flutter. Configurez les formats de commerce de détail tels que EAN-13, UPC-A et EAN-8. Après avoir vérifié que le résultat est un code de ce type, retirez les séparateurs et espaces :
// Conserver uniquement les chiffres du résultat du scan
const normalize = (raw) => raw.replace(/\D/g, "");
Étape 2 : rechercher le produit
Les offres de The Beauty API incluant les codes-barres donnent accès à un point d’accès de recherche acceptant de 8 à 14 chiffres, sans séparateurs. Effectuez cette recherche depuis votre serveur pour garder votre clé confidentielle :
const BASE = "https://api.thebeautyapi.com"; // même URL de base pour toutes les offres
async function lookupBarcode(code) {
const res = await fetch(`${BASE}/v1/products/barcode/${normalize(code)}`, {
headers: { "x-api-key": process.env.BEAUTY_API_KEY },
});
if (res.status === 404) return null; // aucune fiche trouvée pour ce code
if (!res.ok) throw new Error(`lookup failed: ${res.status}`); // 403 = offre sans recherche par code-barres
return res.json(); // la fiche produit complète
}
Une correspondance renvoie une fiche complète : marque, nom, ingrédients liés aux fiches INCI, informations de formulation et image. L’API reconnaît aussi les formes équivalentes d’un même code, complétées par des zéros à gauche. Un code mal formé renvoie 400, ce qui permet de distinguer une requête invalide d’une recherche sans résultat.
Affichez le nom et l’image pour que l’utilisateur puisse reconnaître le produit. Lorsque le choix dépend de la contenance ou de la variante, gardez ces informations visibles au moment de la sélection.
Étape 3 : prévoir les codes sans résultat
Un 404 signifie qu’aucune fiche n’a été trouvée pour ce code. Le produit peut néanmoins être présent sous son nom. Proposez immédiatement une recherche par marque et nom :
async function resolveScan(code) {
const product = await lookupBarcode(code);
if (product) return { via: "barcode", product };
return { via: "search" }; // afficher la recherche : GET /v1/products/search?q=...
}
La recherche prend en charge les préfixes. Une saisie comme ordinary niac peut ainsi retrouver les fiches correspondantes.
Expliquez l’étape suivante avec un message concret : « Ce code-barres n’a pas été trouvé. Recherchez le produit par son nom. » L’utilisateur peut poursuivre son parcours sans devoir relancer le scan.
Mettez en cache les correspondances déjà obtenues pour accélérer les scans répétés. Utiliser une représentation cohérente du GTIN comme clé de cache évite de conserver plusieurs entrées pour le même code. Choisissez une durée adaptée au rythme des versions et à votre application.
La couverture peut évoluer lors des mises à jour du catalogue. Votre interface doit rester utile dès aujourd’hui avec les résultats disponibles et la recherche par nom.
Pourquoi soigner le parcours sans résultat
Le scanner est un point d’entrée dans votre catalogue. Si vous proposez une recherche dès qu’un code ne renvoie rien, l’utilisateur dispose encore d’un moyen de retrouver son produit. Le scan et la saisie se complètent dans un même parcours.
Essayer le parcours complet
La recherche par code-barres est disponible dans les offres qui l’incluent. La recherche par nom et les fiches produits et ingrédients sont disponibles dans toutes les offres. Les nouveaux clients peuvent commencer par un essai de sept jours avec 100 requêtes au total. L’offre payante sélectionnée commence ensuite, sauf résiliation.
La documentation présente les points d’accès, et notre guide Postman comprend une requête de code-barres prête à utiliser. Contactez-nous pour discuter de votre projet.

