API etykiety GARAN tworzy etykiety zgodne z załącznikiem II do rozporządzenia (UE) 2025/1960 na podstawie trzech danych: okresu gwarancji w latach, marki i identyfikatora modelu. Każda nowa kombinacja kosztuje jeden kredyt, ponowne pobranie tej samej kombinacji jest bezpłatne. Pojedyncze etykiety w generatorze na stronie pozostają bezpłatne.

Uwierzytelnianie

Każde zapytanie zawiera klucz dostępu w nagłówku Authorization: Bearer gl_…. Klucz wygenerujesz w koncie generatora (po niemiecku) po zalogowaniu się adresem e-mail. Nowy klucz zastępuje dotychczasowy. Nie umieszczaj go w publicznym kodzie źródłowym ani w kodzie przeglądarki, używaj go wyłącznie po stronie serwera.

Tworzenie etykiety

POST https://www.garantielabel.app/api/v1/labels z treścią JSON:

Pole	Wymagane	Opis
`jahre`	Tak	Okres gwarancji, więcej niż 2, pełne lub połówki lat: `"5"`, `"2,5"` (z przecinkiem)
`marke`	Tak	Nazwa producenta udzielającego gwarancji, maksymalnie 40 znaków
`modell`	Tak	Identyfikator modelu, maksymalnie 24 znaki
`variante`	Nie	`full-colour` (domyślnie), `nested` (wbudowana, tylko online) lub `full-bw` (czarno-biała, tylko offline)

Odpowiedź w formacie JSON: {"svg": "<svg …", "neu_berechnet": true, "guthaben": 99, "id": "…"}. Z nagłówkiem Accept: image/svg+xml otrzymasz bezpośrednio plik SVG; saldo i rozliczenie znajdziesz wtedy w nagłówkach X-Guthaben i X-Neu-Berechnet.

Przykłady

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();

Sprawdzanie salda

GET https://www.garantielabel.app/api/konto z tym samym kluczem zwraca {"angemeldet": true, "email": "…", "guthaben": 99, "labels": 1}.

Błędy

Status	Znaczenie
400	Nieprawidłowe dane, np. dwa lata lub mniej. Opis błędu znajduje się w polu `fehler` (komunikaty są po niemiecku).
401	Brak klucza lub klucz nieznany.
402	Brak środków. Nowy pakiet doładowuje ten sam klucz.
409	Ta sama etykieta została zamówiona jednocześnie. Powtórz zapytanie; opłata zostanie pobrana tylko raz.
413, 415	Zapytanie większe niż 8 KB lub niewysłane jako JSON.
429	Za dużo zapytań: maksymalnie 600 na minutę i 30 000 dziennie na konto. Odczekaj chwilę i wyślij ponownie.

Co zawiera etykieta

API korzysta z oryginalnego wzoru Komisji Europejskiej i zastępuje tylko trzy dozwolone pola, z osadzoną czcionką Inter. Plik SVG jest kompletny i nie wymaga żadnych plików zewnętrznych.

Budowa etykiety GARAN z trzema polami do edycji

API etykiety GARAN