VBUW Produktdatenbank-API

Bitte melden Sie sich an, um die API-Dokumentation einzusehen.

Datenschutzerklärung Impressum
Postman Collection verfügbar — Importieren Sie alle API-Endpunkte direkt in Postman, um die Schnittstelle schnell zu testen.

Authentifizierung

Die API verwendet den OAuth 2.0 Client Credentials-Flow zur Authentifizierung. Alle Endpunkte ausser dem Token-Endpunkt erfordern einen gültigen Bearer-Token.

Ablauf

  1. Zugangsdaten erhalten – Sie erhalten Ihre client_id und client_secret per E-Mail vom VBUW.
  2. Token anfordern – Senden Sie einen POST-Request an /api/v1/token mit Ihren Zugangsdaten.
  3. Bearer-Token verwenden – Senden Sie den Token im Authorization-Header bei allen weiteren Anfragen.
  4. Token erneuern – Nach Ablauf (standardmäßig 3600 Sekunden) fordern Sie einen neuen Token an.

POST /api/v1/token Öffentlich

Fordert einen Zugangs-Token über den Client-Credentials-Flow an.

Parameter

ParameterTypBeschreibung
grant_type PflichtstringMuss client_credentials sein
client_id PflichtstringIhre Client-ID
client_secret PflichtstringIhr Client-Secret

Erfolgreiche Antwort 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Fehlerantwort 401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials."
}

Code-Beispiele

curl -X POST https://checker.vbuw-online.de/api/v1/token \
  -d "grant_type=client_credentials" \
  -d "client_id=IHRE_CLIENT_ID" \
  -d "client_secret=IHR_CLIENT_SECRET"
$ch = curl_init('https://checker.vbuw-online.de/api/v1/token');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POSTFIELDS     => http_build_query([
        'grant_type'    => 'client_credentials',
        'client_id'     => 'IHRE_CLIENT_ID',
        'client_secret' => 'IHR_CLIENT_SECRET',
    ]),
]);
$response = json_decode(curl_exec($ch), true);
$token = $response['access_token'];
import requests

resp = requests.post("https://checker.vbuw-online.de/api/v1/token", data={
    "grant_type": "client_credentials",
    "client_id": "IHRE_CLIENT_ID",
    "client_secret": "IHR_CLIENT_SECRET",
})
token = resp.json()["access_token"]
const resp = await fetch("https://checker.vbuw-online.de/api/v1/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "client_credentials",
    client_id: "IHRE_CLIENT_ID",
    client_secret: "IHR_CLIENT_SECRET",
  }),
});
const { access_token } = await resp.json();

Ausprobieren

Token wird mit Ihren gespeicherten Zugangsdaten angefordert.

GET /api/v1/products Bearer Token

Durchsucht die Produktdatenbank per Fuzzy-Suche (Mindestübereinstimmung 75%). Ergebnisse werden nach Übereinstimmung absteigend sortiert.

Query-Parameter

ParameterTypBeschreibung
q PflichtstringSuchbegriff
limitintegerMaximale Anzahl Ergebnisse (Standard: 50, Max: 200)
offsetintegerOffset für Paginierung (Standard: 0)

Erfolgreiche Antwort 200 OK

{
  "total": 3,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "match": 98.5,
      "id": 1234,
      "title": "Coca-Cola Classic 0,33l",
      "designation": "Erfrischungsgetränk",
      "manufacturer": "Coca-Cola Europacific Partners Deutschland GmbH",
      "producer": "Coca-Cola",
      "url": "https://example.com/product/1234",
      "ingredients": "Wasser, Zucker, Kohlensäure, Farbstoff E 150d, ...",
      "nutrition_facts": "Brennwert 180 kJ / 42 kcal, Fett 0 g, ...",
      "warnings": null,
      "caffeine": "ja",
      "alcohol": "nein",
      "storage_usage": "Kühl und trocken lagern.",
      "origin": "Deutschland",
      "filling_quantity": "330 ml",
      "last_modified": "2026-03-12T14:30:00+00:00"
    }
  ]
}

Code-Beispiele

curl -H "Authorization: Bearer IHR_TOKEN" \
  "https://checker.vbuw-online.de/api/v1/products?q=coca+cola"
$ch = curl_init('https://checker.vbuw-online.de/api/v1/products?' . http_build_query([
    'q'     => 'coca cola',
    'limit' => 50,
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer IHR_TOKEN',
    ],
]);
$response = json_decode(curl_exec($ch), true);
$products = $response['data'];
import requests

resp = requests.get("https://checker.vbuw-online.de/api/v1/products", params={
    "q": "coca cola",
    "limit": 50,
}, headers={
    "Authorization": "Bearer IHR_TOKEN",
})
products = resp.json()["data"]
const params = new URLSearchParams({ q: "coca cola", limit: "50" });
const resp = await fetch(`https://checker.vbuw-online.de/api/v1/products?${params}`, {
  headers: { "Authorization": "Bearer IHR_TOKEN" },
});
const { data: products } = await resp.json();

Ausprobieren

GET /api/v1/products/{id} Bearer Token

Gibt ein einzelnes Produkt anhand seiner ID zurück.

Pfad-Parameter

ParameterTypBeschreibung
id PflichtintegerDie Produkt-ID

Erfolgreiche Antwort 200 OK

{
  "data": {
    "id": 1234,
    "title": "Coca-Cola Classic 0,33l",
    "designation": "Erfrischungsgetränk",
    "manufacturer": "Coca-Cola Europacific Partners Deutschland GmbH",
    "producer": "Coca-Cola",
    "url": "https://example.com/product/1234",
    "ingredients": "Wasser, Zucker, Kohlensäure, Farbstoff E 150d, ...",
    "nutrition_facts": "Brennwert 180 kJ / 42 kcal, Fett 0 g, ...",
    "warnings": null,
    "caffeine": "ja",
    "alcohol": "nein",
    "storage_usage": "Kühl und trocken lagern.",
    "origin": "Deutschland",
    "filling_quantity": "330 ml",
    "last_modified": "2026-03-12T14:30:00+00:00"
  }
}

Fehlerantwort 404 Not Found

{
  "error": "not_found",
  "error_description": "Product not found."
}

Code-Beispiele

curl -H "Authorization: Bearer IHR_TOKEN" \
  "https://checker.vbuw-online.de/api/v1/products/1234"
$productId = 1234;
$ch = curl_init("https://checker.vbuw-online.de/api/v1/products/{$productId}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer IHR_TOKEN',
    ],
]);
$response = json_decode(curl_exec($ch), true);
$product = $response['data'];
import requests

product_id = 1234
resp = requests.get(f"https://checker.vbuw-online.de/api/v1/products/{product_id}", headers={
    "Authorization": "Bearer IHR_TOKEN",
})
product = resp.json()["data"]
const productId = 1234;
const resp = await fetch(`https://checker.vbuw-online.de/api/v1/products/${productId}`, {
  headers: { "Authorization": "Bearer IHR_TOKEN" },
});
const { data: product } = await resp.json();

Ausprobieren

GET /api/v1/manufacturers Bearer Token

Listet alle aktiven Hersteller mit Produktanzahl auf.

Erfolgreiche Antwort 200 OK

{
  "total": 15,
  "data": [
    {
      "id": 1,
      "title": "Coca-Cola Europacific Partners Deutschland GmbH",
      "producer": "Coca-Cola",
      "product_count": 24
    }
  ]
}

Code-Beispiele

curl -H "Authorization: Bearer IHR_TOKEN" \
  "https://checker.vbuw-online.de/api/v1/manufacturers"
$ch = curl_init('https://checker.vbuw-online.de/api/v1/manufacturers');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer IHR_TOKEN',
    ],
]);
$response = json_decode(curl_exec($ch), true);
$manufacturers = $response['data'];
import requests

resp = requests.get("https://checker.vbuw-online.de/api/v1/manufacturers", headers={
    "Authorization": "Bearer IHR_TOKEN",
})
manufacturers = resp.json()["data"]
const resp = await fetch("https://checker.vbuw-online.de/api/v1/manufacturers", {
  headers: { "Authorization": "Bearer IHR_TOKEN" },
});
const { data: manufacturers } = await resp.json();

Ausprobieren

Keine Parameter erforderlich.

GET /api/v1/manufacturers/{id}/products Bearer Token

Gibt die paginierte Produktliste eines Herstellers zurück.

Pfad-Parameter

ParameterTypBeschreibung
id PflichtintegerDie Hersteller-ID

Query-Parameter

ParameterTypBeschreibung
limitintegerMaximale Anzahl Ergebnisse (Standard: 50, Max: 200)
offsetintegerOffset für Paginierung (Standard: 0)

Erfolgreiche Antwort 200 OK

{
  "total": 24,
  "limit": 50,
  "offset": 0,
  "data": [
    {
      "id": 1234,
      "title": "Coca-Cola Classic 0,33l",
      "designation": "Erfrischungsgetränk",
      "manufacturer": "Coca-Cola Europacific Partners Deutschland GmbH",
      "producer": "Coca-Cola",
      "url": "https://example.com/product/1234",
      "ingredients": "Wasser, Zucker, Kohlensäure, Farbstoff E 150d, ...",
      "nutrition_facts": "Brennwert 180 kJ / 42 kcal, Fett 0 g, ...",
      "warnings": null,
      "caffeine": "ja",
      "alcohol": "nein",
      "storage_usage": "Kühl und trocken lagern.",
      "origin": "Deutschland",
      "filling_quantity": "330 ml",
      "last_modified": "2026-03-12T14:30:00+00:00"
    }
  ]
}

Code-Beispiele

curl -H "Authorization: Bearer IHR_TOKEN" \
  "https://checker.vbuw-online.de/api/v1/manufacturers/1/products?limit=50&offset=0"
$manufacturerId = 1;
$ch = curl_init("https://checker.vbuw-online.de/api/v1/manufacturers/{$manufacturerId}/products?" . http_build_query([
    'limit'  => 50,
    'offset' => 0,
]));
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer IHR_TOKEN',
    ],
]);
$response = json_decode(curl_exec($ch), true);
$products = $response['data'];
import requests

manufacturer_id = 1
resp = requests.get(f"https://checker.vbuw-online.de/api/v1/manufacturers/{manufacturer_id}/products", params={
    "limit": 50,
    "offset": 0,
}, headers={
    "Authorization": "Bearer IHR_TOKEN",
})
products = resp.json()["data"]
const manufacturerId = 1;
const params = new URLSearchParams({ limit: "50", offset: "0" });
const resp = await fetch(
  `https://checker.vbuw-online.de/api/v1/manufacturers/${manufacturerId}/products?${params}`,
  { headers: { "Authorization": "Bearer IHR_TOKEN" } }
);
const { data: products } = await resp.json();

Ausprobieren

Fehlercodes

Alle Fehlerantworten folgen dem gleichen Format:

{
  "error": "error_code",
  "error_description": "Menschenlesbare Beschreibung."
}
HTTP-StatusFehlercodeBeschreibung
400invalid_requestFehlende oder ungültige Parameter
400unsupported_grant_typeNur client_credentials wird unterstützt
401invalid_clientUngültige Zugangsdaten
401invalid_tokenToken fehlt, ist ungültig oder abgelaufen
404not_foundRessource nicht gefunden
403disclaimer_requiredDisclaimer muss akzeptiert werden
429rate_limit_exceededRate Limit überschritten (max. 120/Min. oder 2.000/Std.)

Rate Limiting

Alle authentifizierten API-Endpunkte unterliegen einem Rate Limiting pro Benutzer:

LimitZeitfensterBeschreibung
120pro MinuteMaximale Anfragen pro Minute und API-Benutzer
2.000pro StundeMaximale Anfragen pro Stunde und API-Benutzer

Response-Header

Jede API-Antwort enthält folgende Rate-Limit-Header:

HeaderBeschreibung
X-RateLimit-LimitMaximale Anzahl Anfragen im aktuellen Zeitfenster
X-RateLimit-RemainingVerbleibende Anfragen im aktuellen Zeitfenster
X-RateLimit-ResetUnix-Timestamp, wann das Zeitfenster zurückgesetzt wird

Bei Überschreitung

Wird das Limit überschritten, antwortet die API mit HTTP 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Maximum 120 requests per minute."
}

Der Retry-After-Header gibt die Wartezeit in Sekunden an, bevor neue Anfragen möglich sind.

Wir empfehlen, Ihren Token bis zum Ablauf zwischenzuspeichern und nicht bei jeder Anfrage einen neuen Token anzufordern.

Hersteller

Alle Hersteller mit freigegebenen Produkten in der Datenbank.

Hersteller werden geladen…

Produkte

Durchsuchen Sie die Produktdatenbank oder wählen Sie einen Hersteller aus der Liste oben.