Die GARAN-Label API erzeugt Labels nach Anhang II der Verordnung (EU) 2025/1960 aus drei Angaben: Garantiedauer in Jahren, Marke und Modellkennung. Jede neue Kombination kostet ein Credit, wiederholte Abrufe derselben Kombination sind kostenlos.

Authentifizierung

Jede Anfrage trägt den Zugangsschlüssel im Kopf Authorization: Bearer gl_…. Den Schlüssel erzeugen Sie im Generator, nachdem Sie sich mit Ihrer E-Mail angemeldet haben. Ein neuer Schlüssel ersetzt den bisherigen. Geben Sie ihn nicht in öffentlichen Quelltext oder Browser-Code, sondern nur serverseitig.

Label erstellen

POST https://www.garantielabel.app/api/v1/labels mit JSON-Rumpf:

Feld	Pflicht	Beschreibung
`jahre`	Ja	Garantiedauer, mehr als 2, ganze oder halbe Jahre: `"5"`, `"2,5"`
`marke`	Ja	Name des Herstellers, der die Garantie gibt, höchstens 40 Zeichen
`modell`	Ja	Modellkennung, höchstens 24 Zeichen
`variante`	Nein	`full-colour` (Standard), `nested` (geschachtelt, nur online) oder `full-bw` (schwarz-weiß, nur offline)

Antwort als JSON: {"svg": "<svg …", "neu_berechnet": true, "guthaben": 99, "id": "…"}. Mit dem Kopf Accept: image/svg+xml kommt direkt die SVG-Datei, Guthaben und Abrechnung stehen dann in den Köpfen X-Guthaben und X-Neu-Berechnet.

Beispiele

curl

curl -X POST https://www.garantielabel.app/api/v1/labels \
  -H "Authorization: Bearer gl_…" \
  -H "Accept: image/svg+xml" \
  -H "Content-Type: application/json" \
  -d '{"jahre":"5","marke":"Muster","modell":"MX-500"}' \
  -o GARAN-MX-500.svg

PHP

$ch = curl_init("https://www.garantielabel.app/api/v1/labels");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("GARAN_SCHLUESSEL"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["jahre" => "5", "marke" => "Muster", "modell" => "MX-500"]),
]);
$label = json_decode(curl_exec($ch), true);
file_put_contents("GARAN-MX-500.svg", $label["svg"]);

JavaScript (Node.js)

const antwort = await fetch("https://www.garantielabel.app/api/v1/labels", {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.GARAN_SCHLUESSEL}`, "Content-Type": "application/json" },
  body: JSON.stringify({ jahre: "5", marke: "Muster", modell: "MX-500" }),
});
const { svg, guthaben } = await antwort.json();

Guthaben abfragen

GET https://www.garantielabel.app/api/konto mit demselben Schlüssel liefert {"angemeldet": true, "email": "…", "guthaben": 99, "labels": 1, "gratisFrei": false}.

Fehler

Status	Bedeutung
400	Angaben ungültig, z. B. zwei Jahre oder weniger. Der Text steht in `fehler`.
401	Schlüssel fehlt oder ist unbekannt.
402	Kein Guthaben mehr. Ein neues Paket lädt denselben Schlüssel auf.
409	Dasselbe Label wurde gleichzeitig angefragt. Bitte die Anfrage wiederholen, es wird nur einmal abgebucht.
413, 415	Anfrage größer als 8 KB oder nicht als JSON gesendet.
429	Zu viele Anfragen: höchstens 600 je Minute und 30.000 je Tag und Konto. Kurz warten und erneut senden.

Was das Label enthält

Die API nutzt die Originalvorlage der EU-Kommission und ersetzt nur die drei freigegebenen Felder, mit eingebetteter Schrift Inter. Die SVG-Datei ist in sich geschlossen und braucht keine externen Dateien.

Aufbau des GARAN-Labels mit den drei änderbaren Feldern

GARAN-Label API