Documentation développeur

Deux façons d'intégrer H-QR dans ton propre projet : l'API REST (ci-dessous) pour ton code, ou le serveur MCP pour les assistants IA (voir §3).

1. Obtenir une clé API

1

Crée un compte

Gratuit, par email ou Google — s'inscrire.

2

Va sur ton profil

/profile → section "Clés API" → "Nouvelle clé".

3

Copie-la (une seule fois)

Elle ne sera plus jamais affichée en clair. Utilise-la en en-tête Authorization: Bearer.

# Chaque requête authentifiée ressemble à ça : curl -H "Authorization: Bearer hqr_live_xxxxxxxx" ...

Sans clé, un appel reste possible en anonyme sur les routes de génération de base (voir quotas ci-dessous) — utile pour un premier essai rapide.

2. Quotas par plan

PlanRequêtes API / moisBatch max
Anonyme (sans compte)~60/heure par IP sur generate, moins sur batch/animate/social5
Gratuit50010
Pro20 000500
Business200 0002000

3. Le serveur MCP — pour les assistants IA

MCP (Model Context Protocol) permet à un assistant IA comme Claude d'appeler directement des outils. Avec H-QR, tu peux littéralement écrire dans Claude : "génère-moi un QR premium noir/or pour mon restaurant avec mon logo" — et obtenir l'image, sans jamais toucher à du code.

"Il faut installer quelque chose chez moi ?"

Non. Le serveur MCP H-QR est hébergé, à l'adresse https://votre-domaine/api/mcp — c'est cette URL que tu ajoutes à Claude, exactement comme un lien. Aucun npm install, aucun serveur à faire tourner chez toi.

Sans clé API : accès anonyme, limité par IP (mêmes quotas que l'API REST anonyme, voir §2). Avec ta clé API (Authorization: Bearer hqr_live_xxx, la même que pour l'API REST) : les appels comptent dans le quota de ton plan, comme n'importe quel appel API.

Option A — Claude Code (ligne de commande)

# Sans authentification (accès anonyme, limité par IP) claude mcp add --transport http h-qr https://votre-domaine/api/mcp # Avec ta clé API (quota de ton plan, pas de limite IP) claude mcp add --transport http h-qr https://votre-domaine/api/mcp -H "Authorization: Bearer hqr_live_xxxxxxxx"

Le nom exact du flag pour les en-têtes personnalisés peut varier selon la version de Claude Code — vérifie avec claude mcp add --help si la commande ci-dessus est refusée.

Option B — Claude.ai / Claude Desktop (interface graphique)

Réglages → Connecteurs (Connectors) → Ajouter un connecteur personnalisé → colle l'URL https://votre-domaine/api/mcp. Si l'interface propose un champ d'en-têtes personnalisés, ajoutes-y ta clé API de la même façon (Authorization: Bearer hqr_live_xxx) ; sinon, utilise l'accès anonyme ou passe par Claude Code pour un accès authentifié garanti.

Ensuite : que dire à Claude ?

Rien de spécial à apprendre — décris simplement ce que tu veux, en français normal. Exemples de prompts à copier tels quels :

Génère-moi un QR code vers https://mon-site.com avec le preset "violet_dream" et mon logo au centre. Fais-moi 5 QR codes différents pour ces 5 liens, tous avec un style hexagone doré. Liste-moi tous les presets disponibles et choisis-en un qui correspond à un restaurant japonais chic. Vérifie que ce QR reste bien scannable avant que je l'imprime sur 1000 flyers.

Claude choisit lui-même le bon tool parmi les 6 exposés (generate_qr_code, batch_generate, validate_scannability, generate_social_asset, generate_animated_qr, list_presets), remplit les bons paramètres, et t'affiche directement l'image dans la conversation.

Auto-hébergement (avancé)

Le dossier mcp-server/ du dépôt contient une version 100% locale (stdio, npm install + claude mcp add), pour qui préfère faire tourner sa propre instance plutôt que d'utiliser le MCP hébergé. Voir mcp-server/README.md. C'est un cas d'usage avancé, pas la voie recommandée pour un utilisateur standard.

4. Endpoints de l'API REST

POST/api/qr/generate

Génère un QR code. C'est l'endpoint principal — PNG par défaut, ou SVG vectoriel pur.

Auth : Optionnel (anonyme limité par IP, illimité avec compte/clé)

ParamètreTypeDescription
text *stringTexte ou URL à encoder
presetstringUn des 21 presets (voir /pricing ou la galerie du dashboard)
stylestringsquare | dots | rounded | classy | diamond | triangle | star | hexagon | plus | ring | squircle | icon
icon_namestringSi style='icon' : car, user, tree, leaf, heart, star, sun, music, crown, diamond, shield, bolt, gear, cloud, camera, gift, flag, paw, check
fg_color / bg_colorstring (hex)Couleurs unies
gradientstring[]2+ couleurs hex pour un dégradé
gradient_directionstringhorizontal | vertical | diagonal | diagonal-reverse | radial
effectobject{ type: 'wave'|'glitch'|'mosaic', ... } — voir mcp-server/README.md
logoobject{ base64, sizeRatio, shape } — logo au centre
frameobject{ style, color, thickness, radius, label } — cadre décoratif
formatstringpng (défaut) ou svg

curl

curl -X POST https://votre-domaine/api/qr/generate \
  -H "Authorization: Bearer hqr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"https://example.com","preset":"ocean","format":"svg"}'

JavaScript

const res = await fetch("/api/qr/generate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "https://example.com", preset: "ocean" }),
});
const { data, mimeType } = await res.json();
// data = image en base64 → <img src={`data:${mimeType};base64,${data}`} />

Réponse

{
  "data": "iVBORw0KGgoAAAANSUhEUgA...",
  "mimeType": "image/png",
  "format": "png"
}
POST/api/qr/batch

Génère plusieurs QR en une seule requête. Pratique pour une série de badges, tables de restaurant, etc.

Auth : Recommandé (limite anonyme : 5 items max)

ParamètreTypeDescription
items *arrayListe d'objets, mêmes champs que /generate. Max selon le plan : 5 (anonyme), 10 (Free), 500 (Pro), 2000 (Business).

curl

curl -X POST https://votre-domaine/api/qr/batch \
  -H "Authorization: Bearer hqr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"text":"https://a.com"},{"text":"https://b.com"}]}'

JavaScript

const res = await fetch("/api/qr/batch", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ items: [{ text: "https://a.com" }, { text: "https://b.com" }] }),
});
const { results } = await res.json();

Réponse

{
  "results": [
    { "text": "https://a.com", "data": "...", "mimeType": "image/png", "format": "png" },
    { "text": "https://b.com", "data": "...", "mimeType": "image/png", "format": "png" }
  ]
}
POST/api/qr/validate

Génère un QR puis le redécode réellement (comme un smartphone) pour te donner un score de fiabilité avant impression.

Auth : Optionnel

ParamètreTypeDescription
text *stringMêmes champs que /generate

curl

curl -X POST https://votre-domaine/api/qr/validate \
  -H "Content-Type: application/json" \
  -d '{"text":"https://example.com","logo":{"base64":"...","sizeRatio":0.3}}'

JavaScript

const res = await fetch("/api/qr/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "https://example.com" }),
});
const { score, matches, issues } = await res.json();

Réponse

{
  "data": "...",
  "mimeType": "image/png",
  "score": 96,
  "matches": true,
  "issues": []
}
POST/api/qr/social

Compose le QR dans un visuel prêt pour Instagram/LinkedIn/X (story, post carré, bannière).

Auth : Compte requis pour Free (consomme 1 crédit Ultra) · illimité Pro/Business · quelques essais anonymes

ParamètreTypeDescription
text *stringContenu du QR
social_template *stringstory-9-16 | post-square | banner-linkedin | banner-twitter
title / subtitlestringTextes affichés sur le visuel
background_gradientstring[]2 couleurs hex pour le fond

curl

curl -X POST https://votre-domaine/api/qr/social \
  -H "Authorization: Bearer hqr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"https://example.com","social_template":"post-square","title":"Scanne-moi"}'

JavaScript

const res = await fetch("/api/qr/social", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "https://example.com", social_template: "post-square" }),
});

Réponse

{ "data": "...", "mimeType": "image/png", "remainingCredits": 9 }
POST/api/qr/animate

Génère un GIF animé en boucle (effet wave qui pulse, ou icônes qui se réorganisent).

Auth : Compte requis (consomme 1 crédit Ultra sur plan Free) · illimité Pro/Business

ParamètreTypeDescription
text *stringContenu du QR
framesnumber2 à 48 (défaut 12)
delay_msnumberDélai entre frames (défaut 90)

curl

curl -X POST https://votre-domaine/api/qr/animate \
  -H "Authorization: Bearer hqr_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"text":"https://example.com","effect":{"type":"wave"},"frames":16}'

JavaScript

const res = await fetch("/api/qr/animate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: "https://example.com", effect: { type: "wave" } }),
});

Réponse

{ "data": "...", "mimeType": "image/gif", "remainingCredits": 9 }
POST / GET/api/dynamic-links

Crée (POST) ou liste (GET) tes QR dynamiques — une URL de redirection modifiable après impression.

Auth : Compte requis (plan Pro+)

ParamètreTypeDescription
targetUrl *stringURL de destination initiale (POST uniquement)

curl

curl -X POST https://votre-domaine/api/dynamic-links \
  -H "Cookie: hqr_token=..." \
  -H "Content-Type: application/json" \
  -d '{"targetUrl":"https://ma-destination.com"}'

JavaScript

const res = await fetch("/api/dynamic-links", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ targetUrl: "https://ma-destination.com" }),
});
const { link, redirectUrl } = await res.json();

Réponse

{ "link": { "id": "...", "slug": "aB3xQ2" }, "redirectUrl": "https://votre-domaine/r/aB3xQ2" }

5. Codes d'erreur

CodeSignificationQue faire
400Requête invalide (champ requis manquant, ex: 'text')Vérifie le corps JSON envoyé
401Non authentifié (endpoint qui exige un compte)Connecte-toi ou passe une clé API valide
402Fonctionnalité payante non débloquée (crédits Ultra épuisés, ou multi-logo hors plan)Achète le Pack Ultra ou passe à un plan supérieur — voir /pricing
403Accès refusé (rôle ou plan insuffisant, ex: Brand Kit hors plan Business)Vérifie ton plan sur /pricing
429Trop de requêtes (rate limit IP ou quota mensuel dépassé)Attends la fenêtre suivante, ou passe à un plan avec un quota plus élevé
500Erreur serveur inattendueRéessaie ; si ça persiste, contacte le support

Toute erreur renvoie { "error": "message lisible" }. Les erreurs 402 incluent aussi "needsUpgrade": true ou "needsCredits": true" pour que ton code puisse détecter automatiquement ce cas et rediriger l'utilisateur vers /pricing.

6. FAQ développeur

Comment j'obtiens une clé API ?

Crée un compte gratuit, va sur /profile, clique sur "Nouvelle clé". Elle s'affiche une seule fois — copie-la immédiatement. Toutes les routes /api/qr/* acceptent ensuite un en-tête Authorization: Bearer hqr_live_xxx.

Est-ce que je peux appeler l'API sans clé, juste pour tester ?

Oui. /api/qr/generate, /batch, /validate et /social acceptent des appels anonymes, limités par IP (voir le tableau des quotas plus haut). Pratique pour prototyper avant de créer un compte.

Quelle différence entre l'API REST et le serveur MCP ?

L'API REST est faite pour être appelée depuis ton propre code (backend, script, Zapier/n8n...). Le serveur MCP est fait pour être appelé directement par un assistant IA (Claude, etc.) en langage naturel, dans une conversation. Les deux utilisent le même moteur de rendu en dessous.