L’API du label GARAN génère des labels conformes à l’annexe II du règlement (UE) 2025/1960 à partir de trois informations : durée de la garantie en années, marque et référence du modèle. Chaque nouvelle combinaison coûte un crédit ; les appels répétés pour la même combinaison sont gratuits. Les labels individuels créés avec le générateur du site restent gratuits.

Authentification

Chaque requête transmet la clé d’accès dans l’en-tête Authorization: Bearer gl_…. Vous générez la clé dans votre espace client (en allemand), après vous être connecté avec votre adresse e-mail. Une nouvelle clé remplace la précédente. Ne la placez jamais dans du code source public ni dans du code exécuté dans le navigateur : utilisez-la uniquement côté serveur.

Créer un label

POST https://www.garantielabel.app/api/v1/labels avec un corps JSON :

Champ	Obligatoire	Description
`jahre`	Oui	Durée de la garantie, plus de 2, en années entières ou demi-années : `"5"`, `"2,5"`
`marke`	Oui	Nom du producteur qui offre la garantie, 40 caractères au maximum
`modell`	Oui	Référence du modèle, 24 caractères au maximum
`variante`	Non	`full-colour` (par défaut), `nested` (imbriqué, en ligne uniquement) ou `full-bw` (noir et blanc, hors ligne uniquement)

Réponse en JSON : {"svg": "<svg …", "neu_berechnet": true, "guthaben": 99, "id": "…"}. Avec l’en-tête Accept: image/svg+xml, vous recevez directement le fichier SVG ; le solde et la facturation figurent alors dans les en-têtes X-Guthaben et X-Neu-Berechnet.

Exemples

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":"Exemple","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_CLE"), "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["jahre" => "5", "marke" => "Exemple", "modell" => "MX-500"]),
]);
$label = json_decode(curl_exec($ch), true);
file_put_contents("GARAN-MX-500.svg", $label["svg"]);

JavaScript (Node.js)

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

Consulter le solde

GET https://www.garantielabel.app/api/konto avec la même clé renvoie {"angemeldet": true, "email": "…", "guthaben": 99, "labels": 1}.

Erreurs

Statut	Signification
400	Données invalides, par exemple une durée de deux ans ou moins. Le message figure dans le champ `fehler`.
401	Clé absente ou inconnue.
402	Plus de crédit disponible. Un nouveau pack recharge la même clé.
409	Le même label a été demandé simultanément. Renvoyez la requête : il ne sera débité qu’une fois.
413, 415	Requête de plus de 8 Ko ou non envoyée en JSON.
429	Trop de requêtes : 600 par minute et 30 000 par jour et par compte au maximum. Patientez un instant, puis renvoyez la requête.

Ce que contient le label

L’API utilise la maquette originale de la Commission européenne et remplace uniquement les trois champs autorisés, avec la police Inter intégrée. Le fichier SVG est autonome et ne dépend d’aucun fichier externe.

Structure du label GARAN avec les trois champs modifiables

API du label GARAN