API de codes QR: comment intégrer la génération dans votre app

L'API de codigo-qr.es a deux tiers.

Endpoint public (sans compte):

`POST /api/v1/qr/render` génère un QR statique et renvoie l'image en base64. Limite: 50 requêtes par jour par IP.

Endpoints Pro (nécessitent une API key):

| Méthode | Chemin | Utilisation | |---------|--------|-------------| | `GET` | `/api/v1/qr` | Lister tous vos codes QR | | `POST` | `/api/v1/qr` | Créer un QR statique ou dynamique | | `GET` | `/api/v1/qr/{id}` | Détails d'un code QR | | `PATCH` | `/api/v1/qr/{id}` | Modifier destination ou nom | | `DELETE` | `/api/v1/qr/{id}` | Supprimer un code QR | | `GET` | `/api/v1/qr/{id}/image` | Télécharger l'image PNG ou SVG | | `GET` | `/api/v1/qr/{id}/stats` | Statistiques de scans |

Toutes les réponses Pro suivent `{ "data": {...}, "error": null }`. En cas d'erreur, `data` est null et `error` contient `code` et `message`.

Étape 1. Créez un compte sur codigo-qr.es.

Étape 2. Activez le plan Pro. L'API complète est exclusive Pro à 5,99€/mois.

Étape 3. Allez sur /panel/compte et cliquez sur «Générer API key». Le token s'affiche une seule fois. Sauvegardez-le dans un gestionnaire de mots de passe ou une variable d'environnement.

Ajoutez ce header à chaque requête:

```bash curl https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_votre_token" ```

Si la clé n'est pas valide ou si le plan a expiré, l'API retourne `401 UNAUTHORIZED` ou `403 PLAN_REQUIRED`. Vous pouvez révoquer la clé à tout moment depuis le tableau de bord; elle cesse de fonctionner immédiatement.

L'endpoint public est le moyen le plus rapide de tester l'API ou de générer des QR simples depuis un script sans gérer l'authentification:

```bash curl -X POST https://codigo-qr.es/api/v1/qr/render \ -H "Content-Type: application/json" \ -d '{"value":"https://votredomaine.com","format":"png","size":512}' ```

Paramètres:

- `value` (obligatoire): le contenu du QR. Peut être une URL, du texte, un email ou des données WiFi.
• `format`: `"png"` (par défaut) ou `"svg"`
• `size`: `256`, `512` (par défaut) ou `1024`

La réponse renvoie l'image en base64 dans l'enveloppe JSON:

```json { "data": { "image": "iVBORw0KGgo...", "format": "png", "size": 512 }, "error": null } ```

Si vous dépassez 50 requêtes par jour depuis la même IP, vous recevez `429 RATE_LIMITED` avec le header `Retry-After` indiquant quand le compteur se réinitialise.

Un QR dynamique encode une URL courte fixe (`/r/{slug}`) mais sa destination finale peut être modifiée à tout moment. Le code imprimé, lui, ne change jamais.

Créer un QR dynamique:

```bash curl -X POST https://codigo-qr.es/api/v1/qr \ -H "Authorization: Bearer cqr_votre_token" \ -H "Content-Type: application/json" \ -d '{ "label": "Menu restaurant mai", "type": "url", "value": "https://votrerestaurant.com/menu-mai", "is_dynamic": true, "tracking_mode": "redirect" }' ```

Changer la destination sans réimprimer:

```bash curl -X PATCH https://codigo-qr.es/api/v1/qr/{id} \ -H "Authorization: Bearer cqr_votre_token" \ -H "Content-Type: application/json" \ -d '{"destination": "https://votrerestaurant.com/menu-juin"}' ```

Télécharger l'image du QR:

```bash curl -o mon-qr.png \ "https://codigo-qr.es/api/v1/qr/{id}/image?format=png&size=1024" \ -H "Authorization: Bearer cqr_votre_token" ```

Voir les statistiques de scans:

```bash curl "https://codigo-qr.es/api/v1/qr/{id}/stats?period=30d" \ -H "Authorization: Bearer cqr_votre_token" ```

Réponse: ```json { "data": { "total": 312, "period": "30d", "by_day": [{"date": "2026-05-01", "count": 18}], "by_country": [{"country": "FR", "count": 270}] }, "error": null } ```

L'API est utile quand le volume ou l'automatisation rendent impossible la génération manuelle de QR depuis le tableau de bord.

E-commerce: QR sur bons de livraison et factures

L'ERP génère le PDF du bon de livraison. Avec un appel à `POST /api/v1/qr`, il obtient un QR qui pointe vers l'URL de suivi de la commande. Si l'URL change, `PATCH /api/v1/qr/{id}` met à jour la destination sans rien régénérer ni réimprimer.

Restaurants: menu par table depuis le TPV

Le système de caisse crée un QR par table à l'ouverture du service. Il pointe vers le menu du jour, que le chef met à jour dans le CMS. Le QR sur la table ne change jamais, seule la destination change. Plus besoin de replastifier les menus chaque semaine.

Événements: billets personnalisés en masse

Un système de billetterie génère un QR unique par billet avec `POST /api/v1/qr` et l'intègre dans le PDF. À l'entrée, le scanner vérifie le QR en lisant `GET /api/v1/qr/{id}` pour confirmer sa validité.

Logistique: colis avec suivi

Chaque colis reçoit un QR qui pointe vers sa page de suivi. Le client le scanne depuis l'enveloppe et voit le statut en temps réel. Les scans sont enregistrés dans `GET /api/v1/qr/{id}/stats`.

L'API applique des limites de fréquence pour garantir la disponibilité.

Tier public (`/api/v1/qr/render`):
• Limite: 50 requêtes par jour par IP
• Fenêtre: 24 heures
• Sans inscription requise

Tier Pro (endpoints avec API key):
• Limite: 60 requêtes par minute par utilisateur
• Sans limite journalière totale

En cas de dépassement, l'API retourne `429 Too Many Requests` avec ces headers:

``` X-RateLimit-Limit: 60 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1747612800 Retry-After: 43 ```

`X-RateLimit-Reset` est le timestamp Unix auquel le compteur se réinitialise. `Retry-After` correspond aux secondes restantes jusqu'à ce moment.

Voir la documentation complète de l'API pour tous les paramètres et réponses d'erreur.