Das Wichtigste: Mit unserer Postman-Collection können Sie die API erkunden, sobald Sie Ihren API-Schlüssel als Variable hinterlegt haben. Dieser Leitfaden zeigt, wie Sie den Dienst prüfen, Produkte und Inhaltsstoffe suchen, Filter und Stapelabrufe nutzen und Fehlerantworten verstehen.
In Postman können Sie Anfragen und Antworten betrachten, bevor Sie die API in Ihre Anwendung integrieren. Die Collection enthält Testskripte: Im Reiter für Testergebnisse sehen Sie, ob sich jeder Aufruf wie erwartet verhalten hat.
Schritt 1: Einen API-Schlüssel erhalten
Melden Sie sich im Dashboard an und erstellen Sie einen Schlüssel. Neue Kunden erhalten eine siebentägige Testphase mit insgesamt 100 Anfragen. Der ausgewählte kostenpflichtige Tarif beginnt nach sieben Tagen, sofern Sie nicht kündigen. Der Schlüssel wird nur einmal angezeigt: Bewahren Sie ihn sicher auf. Wählen Sie einen Tarif mit Barcode-Suche, wenn Sie diese Funktion testen möchten. Die übrigen Endpunkte sind in allen Tarifen verfügbar.
Schritt 2: Die Collection importieren
Laden Sie die Collection-Datei the-beauty-api.postman_collection.json im Format Postman v2.1 herunter. Wählen Sie in Postman File → Import und die Datei aus, oder ziehen Sie sie in die Seitenleiste. Die Collection The Beauty API enthält vier Ordner, deren Namen in der Datei auf Englisch bleiben:
- Start here: Dienststatus, Suche und Abruf eines Produkts.
- Products: Filter, Stapelabrufe und Barcodes.
- Ingredients: Suche und Abruf eines Inhaltsstoffs.
- Errors you should expect: Anfragen, die absichtlich Fehler zurückgeben.
Jede Anfrage enthält eine Beschreibung. Auch die allgemeine Beschreibung der Collection fasst die Funktionsweise zusammen.
Schritt 3: Ihren Schlüssel hinterlegen
Wählen Sie die Collection, öffnen Sie Variables und tragen Sie den lokalen Wert von apiKey ein. Je nach Postman-Version heißt dieser Wert Current value. Halten Sie Ihren Schlüssel geheim und prüfen Sie, dass er nicht in geteilten Werten oder Exporten enthalten ist.
Der Reiter Authorization ist bereits mit dem Typ API Key, dem Header x-api-key und dem Wert {{apiKey}} eingerichtet. Die Anfragen übernehmen diese Konfiguration. Die übrigen Variablen sind:
baseUrl:https://api.thebeautyapi.comfür alle Tarife, einschließlich der Barcode-Suche.productIdundingredientId: Beispiel-IDs. Suchanfragen ersetzen sie durch das erste Ergebnis, damit Sie anschließend den vollständigen Datensatz öffnen können.barcode: ein Beispiel-UPC für die Barcode-Suche.
Schritt 4: Den Dienst prüfen, suchen und einen Datensatz öffnen
Health. Senden Sie diese Anfrage zuerst. Sie benötigt keinen Schlüssel und zeigt den Dienststatus, die Anzahl der Produkte und Inhaltsstoffe im API-Katalog sowie dessen Erstellungsdatum. Hier eine Beispielantwort der Version vom 3. November 2026:
{"status": "ok", "products": 258648, "ingredients": 26420, "built_at": "2026-11-03"}Falls diese Anfrage fehlschlägt, prüfen Sie baseUrl, die Verbindung und die Verfügbarkeit des Dienstes.
Search products. GET /v1/products/search?q=ordinary niacinamide&page=1 sucht nach Marke und Name, unterstützt Präfixe und liefert 20 Ergebnisse pro Seite. Die Antwort enthält verkürzte Datensätze mit unter anderem id, brand, name, category und image_url. Das Skript speichert die erste Kennung in productId.
Get a product. GET /v1/products/{{productId}} liefert den vollständigen Datensatz: Produktinformationen, Formulierungsmerkmale und mit INCI-Datensätzen verknüpfte Inhaltsstoffe. Die Tests prüfen Struktur und Reihenfolge einzelner Listen, Abschnitte und Set-Bestandteile. Die Inhaltsstoffdokumentation beschreibt diese Felder.
Schritt 5: Filter, Stapelabrufe und Inhaltsstoffabfragen ausprobieren
Der Ordner Products zeigt drei gefilterte Suchen: duftstofffreie Pflegeprodukte, Produkte mit einem Inhaltsstoff über has_ingredient und Produkte ohne bestimmte Inhaltsstoffe über excludes_ingredient. Letzteres akzeptiert bis zu zehn durch Kommas getrennte Kennungen. Ändern Sie die Parameter im Reiter Params und senden Sie die Anfrage erneut.
Batch verwendet POST und einen JSON-Body mit 1 bis 50 Kennungen. Die vollständigen Datensätze werden in einer Antwort zurückgegeben. Fügen Sie Kennungen aus einer Suche hinzu, um eine Routine nachzubilden.
Der Ordner Ingredients sucht nach Referenzbezeichnungen und Synonymen. Beispielsweise finden Sie mit vitamin b3 Niacinamide. Der detaillierte Datensatz enthält verfügbare CAS- und EG-Nummern. Zum Filtern von Produkten verwenden Sie die Kennung id, die die API für den jeweiligen Inhaltsstoff zurückgibt.
Schritt 6: Fehler gezielt beobachten
Die Anfragen im letzten Ordner sind so angelegt, dass sie fehlschlagen oder ein leeres Ergebnis liefern. Ein erfolgreicher Test bedeutet, dass die API wie erwartet geantwortet hat:
| Anfrage | Antwort | Behandlung in Ihrer Anwendung |
|---|---|---|
| Fehlender API-Schlüssel | 403, Invalid or missing API key | Prüfen Sie, ob apiKey vorhanden und gültig ist. |
Suche ohne Treffer, q=asdfghjkl | 200, results: [], has_more: false | Zeigen Sie an, dass keine Ergebnisse gefunden wurden, ohne dieselbe Suche automatisch zu wiederholen. |
Suche nur mit Symbolen, q=??? | 400, q contains no searchable characters | Bitten Sie um einen Suchbegriff mit Buchstaben oder Ziffern. |
Seite außerhalb des Limits, page=99 | 400 | Erlaubt sind die Seiten 1 bis 51. Beenden Sie den Abruf, wenn has_more falsch ist. |
| Ungültiges Format der Produktkennung | 400 | Verwenden Sie eine gültige UUID. |
| Unbekannte Kennung | 404 | Zeigen Sie an, dass der Datensatz nicht gefunden wurde. |
Leeres ids-Array | 400 | Der Stapel muss zwischen 1 und 50 Kennungen enthalten. |
Sie können auch 429 erhalten, wenn eine Frequenzgrenze oder das Testkontingent erreicht ist. Vergrößern Sie bei einer Frequenzbegrenzung die Abstände zwischen Anfragen. Wenn das Testkontingent aufgebraucht ist, können Sie den kostenpflichtigen Tarif aktivieren oder das Ende der Testphase abwarten. Eine Barcode-Suche liefert 403, wenn Ihr Tarif sie nicht enthält. Die Dokumentation beschreibt die Fehler im Detail.
Von Postman zum eigenen Code
Über die Schaltfläche Code mit dem Symbol </> können Sie eine Anfrage als curl, JavaScript, Python oder in einer anderen Sprache kopieren. Speichern Sie den Schlüssel auf Ihrem Server in einer Umgebungsvariablen. Binden Sie ihn nicht in Code ein, der an Browser oder mobile Apps ausgeliefert wird. Unser Leitfaden für Hautpflegeempfehlungen zeigt, wie Sie die Aufrufe miteinander verbinden.
Häufige Fragen
Funktioniert die Collection während der Testphase?
Ja, innerhalb des Kontingents von insgesamt 100 Anfragen in sieben Tagen. Wählen Sie einen Tarif mit Barcode-Suche, um diesen Endpunkt zu testen. Während der Testphase zählt ein Stapelabruf als eine Anfrage; in einem kostenpflichtigen Tarif wird jedes angefragte Element auf Ihren Verbrauch angerechnet.
Warum funktioniert Health ohne Schlüssel?
Es handelt sich um eine öffentliche Verfügbarkeitsprüfung. Alle /v1-Endpunkte benötigen den Header x-api-key.
Kann man die gesamte Collection ausführen?
Ja, mit Run collection. Der Collection Runner sendet die Anfragen der Reihe nach und sammelt die Ergebnisse. Die Tests im Fehlerordner sollten erfolgreich sein, da sie genau diese Fehlercodes erwarten.
Enthält die Datei meinen Schlüssel?
Die heruntergeladene Datei enthält eine leere Variable apiKey. Halten Sie Ihren lokalen Wert privat und prüfen Sie jeden Export, bevor Sie ihn teilen.
Ihre Integration vorbereiten
Importieren Sie die Collection und hinterlegen Sie Ihren Schlüssel. Gehen Sie anschließend die Ordner durch und prüfen Sie dabei die Antworten und Testergebnisse. Die Dokumentation erklärt jedes Feld, und das Dashboard zeigt Ihren Verbrauch.

