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
Copie-la (une seule fois)
Elle ne sera plus jamais affichée en clair. Utilise-la en en-tête Authorization: Bearer.
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
| Plan | Requêtes API / mois | Batch max |
|---|---|---|
| Anonyme (sans compte) | ~60/heure par IP sur generate, moins sur batch/animate/social | 5 |
| Gratuit | 500 | 10 |
| Pro | 20 000 | 500 |
| Business | 200 000 | 2000 |
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)
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 :
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
/api/qr/generateGé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ètre | Type | Description |
|---|---|---|
| text * | string | Texte ou URL à encoder |
| preset | string | Un des 21 presets (voir /pricing ou la galerie du dashboard) |
| style | string | square | dots | rounded | classy | diamond | triangle | star | hexagon | plus | ring | squircle | icon |
| icon_name | string | Si style='icon' : car, user, tree, leaf, heart, star, sun, music, crown, diamond, shield, bolt, gear, cloud, camera, gift, flag, paw, check |
| fg_color / bg_color | string (hex) | Couleurs unies |
| gradient | string[] | 2+ couleurs hex pour un dégradé |
| gradient_direction | string | horizontal | vertical | diagonal | diagonal-reverse | radial |
| effect | object | { type: 'wave'|'glitch'|'mosaic', ... } — voir mcp-server/README.md |
| logo | object | { base64, sizeRatio, shape } — logo au centre |
| frame | object | { style, color, thickness, radius, label } — cadre décoratif |
| format | string | png (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"
}/api/qr/batchGé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ètre | Type | Description |
|---|---|---|
| items * | array | Liste 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" }
]
}/api/qr/validateGé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ètre | Type | Description |
|---|---|---|
| text * | string | Mê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": []
}/api/qr/socialCompose 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ètre | Type | Description |
|---|---|---|
| text * | string | Contenu du QR |
| social_template * | string | story-9-16 | post-square | banner-linkedin | banner-twitter |
| title / subtitle | string | Textes affichés sur le visuel |
| background_gradient | string[] | 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 }/api/qr/animateGé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ètre | Type | Description |
|---|---|---|
| text * | string | Contenu du QR |
| frames | number | 2 à 48 (défaut 12) |
| delay_ms | number | Dé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 }/api/dynamic-linksCrée (POST) ou liste (GET) tes QR dynamiques — une URL de redirection modifiable après impression.
Auth : Compte requis (plan Pro+)
| Paramètre | Type | Description |
|---|---|---|
| targetUrl * | string | URL 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
| Code | Signification | Que faire |
|---|---|---|
| 400 | Requête invalide (champ requis manquant, ex: 'text') | Vérifie le corps JSON envoyé |
| 401 | Non authentifié (endpoint qui exige un compte) | Connecte-toi ou passe une clé API valide |
| 402 | Fonctionnalité 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 |
| 403 | Accès refusé (rôle ou plan insuffisant, ex: Brand Kit hors plan Business) | Vérifie ton plan sur /pricing |
| 429 | Trop 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é |
| 500 | Erreur serveur inattendue | Ré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.
