Das Wichtigste: Mit einem Scanner können Nutzer ihre Kamera auf eine Verpackung richten und direkt Informationen zum Produkt und seinen Inhaltsstoffen abrufen. Planen Sie dabei ein, wie Nutzer weitersuchen können, wenn ein Code nicht erkannt wird. Dieser Leitfaden erklärt GTINs, die Suche mit The Beauty API und den Wechsel zur Namenssuche.
Produktbarcodes verstehen
Die Nummern zur Identifikation von Artikeln sind GTINs, kurz für Global Trade Item Numbers, im GS1-System. Bei der Vergabe kommt ein GS1-Unternehmenspräfix zum Einsatz. Die letzte Ziffer dient als Prüfziffer.
Separat verkaufte Varianten können unterschiedliche GTINs haben: Farbtöne einer Foundation, Füllmengen einer Creme oder Duftvarianten einer Produktlinie. Der Produktname allein reicht deshalb nicht aus, um Variante oder Formulierung zu bestimmen.
Dieselbe Kennung kann außerdem in verschiedenen Formen dargestellt werden. Häufig sind UPC-A mit 12 Stellen, EAN-13 mit 13 Stellen und GTIN-8 mit 8 Stellen. Durch führende Nullen lassen sie sich mit 14 Stellen darstellen. So stehen 769915195941 und 00769915195941 für denselben Code. Scanner-Bibliotheken können unterschiedliche Formen zurückgeben.
Schritt 1: Den Code lesen
Verwenden Sie eine Scanner-Bibliothek für Ihre Plattform, etwa ML Kit, das Vision-Framework von iOS oder eine Integration für React Native oder Flutter. Aktivieren Sie Handelsformate wie EAN-13, UPC-A und EAN-8. Nachdem Sie geprüft haben, dass das Ergebnis zu einem dieser Codetypen gehört, entfernen Sie Trennzeichen und Leerzeichen:
// Nur die Ziffern des Scanergebnisses beibehalten
const normalize = (raw) => raw.replace(/\D/g, "");
Schritt 2: Das Produkt suchen
Tarife von The Beauty API mit Barcode-Suche bieten einen Suchendpunkt, der 8 bis 14 Ziffern ohne Trennzeichen akzeptiert. Führen Sie diese Suche von Ihrem Server aus durch, damit Ihr Schlüssel vertraulich bleibt:
const BASE = "https://api.thebeautyapi.com"; // dieselbe Basis-URL für alle Tarife
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; // kein Datensatz für diesen Code gefunden
if (!res.ok) throw new Error(`lookup failed: ${res.status}`); // 403 = Tarif ohne Barcode-Suche
return res.json(); // der vollständige Produktdatensatz
}
Ein Treffer liefert einen vollständigen Datensatz: Marke, Name, mit INCI-Datensätzen verknüpfte Inhaltsstoffe, Formulierungsinformationen und Bild. Die API erkennt auch gleichwertige Formen desselben Codes mit führenden Nullen. Ein fehlerhaft formatierter Code liefert 400. So lässt sich eine ungültige Anfrage von einer Suche ohne Ergebnis unterscheiden.
Zeigen Sie Name und Bild an, damit Nutzer das Produkt erkennen können. Wenn die Auswahl von Füllmenge oder Variante abhängt, zeigen Sie diese Angaben auch während der Auswahl an.
Schritt 3: Bei fehlenden Treffern eine Namenssuche anbieten
Ein 404 bedeutet, dass für diesen Code kein Datensatz gefunden wurde. Das Produkt kann dennoch unter seinem Namen vorhanden sein. Bieten Sie unmittelbar eine Suche nach Marke und Name an:
async function resolveScan(code) {
const product = await lookupBarcode(code);
if (product) return { via: "barcode", product };
return { via: "search" }; // Suche anzeigen: GET /v1/products/search?q=...
}
Die Suche unterstützt Präfixe. Eine Eingabe wie ordinary niac kann daher passende Datensätze finden.
Zeigen Sie den Nutzern mit einer klaren Meldung, wie sie fortfahren können: „Dieser Barcode wurde nicht gefunden. Suchen Sie das Produkt über seinen Namen.“ So können Nutzer fortfahren, ohne erneut scannen zu müssen.
Speichern Sie bereits gefundene Zuordnungen zwischen, um wiederholte Scans zu beschleunigen. Eine einheitliche GTIN-Darstellung als Cache-Schlüssel verhindert mehrere Einträge für denselben Code. Wählen Sie eine Speicherdauer, die zum Veröffentlichungsrhythmus und zu Ihrer Anwendung passt.
Die Abdeckung kann sich mit Katalogaktualisierungen verändern. Mit der Namenssuche bleibt Ihre App auch dann hilfreich, wenn ein Barcode noch nicht zugeordnet werden kann.
Warum eine Suche ohne Treffer weiterführen sollte
Der Scanner ist ein Einstieg in Ihren Katalog. Wenn Sie bei einem Code ohne Ergebnis eine Suche anbieten, haben Nutzer weiterhin eine Möglichkeit, ihr Produkt zu finden. Scannen und Texteingabe ergänzen sich im selben Ablauf.
Den vollständigen Ablauf ausprobieren
Für die Barcode-Suche benötigen Sie einen Tarif mit Barcode-Zugriff. Namenssuche sowie Produkt- und Inhaltsstoffdatensätze sind in allen Tarifen verfügbar. Neue Kunden können mit einer siebentägigen Testphase mit insgesamt 100 Anfragen beginnen. Anschließend startet der ausgewählte kostenpflichtige Tarif, sofern Sie nicht kündigen.
Die Dokumentation stellt die Endpunkte vor, und unser Postman-Leitfaden enthält eine sofort nutzbare Barcode-Anfrage. Kontaktieren Sie uns, um Ihr Projekt zu besprechen.

