L'API dell'etichetta GARAN crea etichette conformi all'allegato II del regolamento (UE) 2025/1960 a partire da tre dati: durata della garanzia in anni, marchio e identificativo del modello. Ogni nuova combinazione costa un credito; richiamare la stessa combinazione è gratuito. I 3 crediti iniziali di un nuovo account funzionano anche tramite API, se non sono già stati usati per etichette create senza registrazione; i crediti sono gli stessi per sito web, caricamento CSV e API.
Autenticazione
Ogni richiesta contiene la chiave di accesso nell'intestazione Authorization: Bearer gl_…. Crei la chiave nell'area account del generatore dopo aver effettuato l'accesso con il tuo indirizzo e-mail. Una nuova chiave sostituisce quella precedente. Non inserirla mai in codice sorgente pubblico o nel codice del browser; usala solo lato server.
Creare un'etichetta
POST https://www.garantielabel.app/api/v1/labels con un corpo JSON:
| Campo | Obbligatorio | Descrizione |
|---|---|---|
jahre | Sì | Durata della garanzia in anni, più di 2, anni interi o mezzi anni: "5", "2.5" o "2,5" |
marke | Sì | Nome del produttore che offre la garanzia, fino a 40 caratteri |
modell | Sì | Identificativo del modello, fino a 24 caratteri |
variante | No | full-colour (predefinita), nested (solo online) o full-bw (bianco e nero, solo offline) |
Risposta in JSON: {"svg": "<svg …", "neu_berechnet": true, "guthaben": 99, "id": "…"}. guthaben è il tuo saldo crediti residuo e neu_berechnet indica se l'etichetta è stata appena creata e addebitata. Con l'intestazione Accept: image/svg+xml ricevi direttamente il file SVG; saldo e addebito si trovano allora nelle intestazioni X-Guthaben e X-Neu-Berechnet.
Esempi
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":"Esempio","modell":"MX-500"}' \
-o GARAN-MX-500.svgPHP
$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_API_KEY"), "Content-Type: application/json"],
CURLOPT_POSTFIELDS => json_encode(["jahre" => "5", "marke" => "Esempio", "modell" => "MX-500"]),
]);
$label = json_decode(curl_exec($ch), true);
file_put_contents("GARAN-MX-500.svg", $label["svg"]);JavaScript (Node.js)
const response = await fetch("https://www.garantielabel.app/api/v1/labels", {
method: "POST",
headers: { Authorization: `Bearer ${process.env.GARAN_API_KEY}`, "Content-Type": "application/json" },
body: JSON.stringify({ jahre: "5", marke: "Esempio", modell: "MX-500" }),
});
const { svg, guthaben } = await response.json();Controllare il saldo
GET https://www.garantielabel.app/api/konto con la stessa chiave restituisce {"angemeldet": true, "email": "…", "guthaben": 99, "labels": 1}.
Errori
| Stato | Significato |
|---|---|
| 400 | Dati non validi, ad esempio due anni o meno. Il messaggio si trova in fehler, nella lingua dell'intestazione x-sprache o Accept-Language (de, en, fr, pl, es, it, nl), altrimenti in tedesco. |
| 401 | Chiave mancante o sconosciuta. |
| 402 | Crediti esauriti. Un nuovo pacchetto ricarica la stessa chiave. |
| 409 | La stessa etichetta è stata richiesta contemporaneamente. Ripeti la richiesta; viene addebitata una sola volta. |
| 413, 415 | Richiesta più grande di 8 KB o non inviata in JSON. |
| 429 | Troppe richieste: al massimo 600 al minuto e 30.000 al giorno per account. Attendi un momento e riprova. |
Cosa contiene l'etichetta
L'API usa il modello originale della Commissione europea e sostituisce solo i tre campi modificabili, con il font Inter incorporato. Il file SVG è autonomo e non richiede file esterni.
I crediti per l'API sono venduti in pacchetti a partire da 4,90 € netti, solo alle imprese e senza abbonamento; prezzi e acquisto sono sulla pagina del generatore. Gli stessi crediti valgono nel generatore di etichette GARAN di questo sito, dove le prime 3 etichette sono gratuite.
