Développeurs
Référence API et intégrations
Tout ce qu'il vous faut pour appeler l'API Business, gérer vos clés et recevoir des webhooks.
Authentification
L'API Business authentifie chaque requête à l'aide d'une clé API. Envoyez-la dans l'en-tête X-Api-Key ou sous forme de jeton Bearer dans l'en-tête Authorization.
Les clés commencent par le préfixe qrg_ et ne sont affichées qu'une seule fois, lors de leur création. Conservez-les en lieu sûr : il est impossible de récupérer une clé par la suite.
Les requêtes sans clé valide renvoient 401. Une clé sans l'autorisation requise reçoit 403 avec l'erreur insufficient_scope. Les ressources hors de votre espace de travail renvoient 404, comme si elles n'existaient pas.
URL de base
Tous les endpoints de l'API Business se trouvent sous le préfixe /v1.
Par exemple, listez vos QR codes à l'adresse https://qr-global.com/api/v1/qr-codes.
- URL de base résolue
- https://qr-global.com
Endpoints
Tous les endpoints se trouvent sous /api/v1 et exigent une clé disposant de l'autorisation indiquée.
| Méthode | Chemin | Autorisation | Fonction |
|---|---|---|---|
| GET | /qr-codes | qr:read | Lister les QR codes (filtres : type, search, folder_id, tag, archived) |
| POST | /qr-codes | qr:write | Créer un QR code |
| POST | /qr-codes/bulk | qr:write | Créer jusqu'à 100 QR codes en une fois |
| GET | /qr-codes/{id} | qr:read | Obtenir un QR code |
| PUT | /qr-codes/{id} | qr:write | Modifier un QR code, son dossier et ses étiquettes |
| DELETE | /qr-codes/{id} | qr:write | Supprimer un QR code |
| GET | /qr-codes/{id}/image | qr:read | Générer l'image (PNG ou SVG) |
| GET | /qr-codes/{id}/stats | analytics:read | Statistiques de scan |
| GET | /qr-codes/{id}/scans | analytics:read | Journal des scans |
| GET | /folders | qr:read | Lister les dossiers |
| GET | /tags | qr:read | Lister les étiquettes |
| GET | /webhooks | webhooks:manage | Lister les abonnements aux webhooks |
| POST | /webhooks | webhooks:manage | S'abonner à des événements |
| DELETE | /webhooks/{id} | webhooks:manage | Se désabonner |
Une description lisible par machine (OpenAPI 3.1) pour Postman, les générateurs de code et les outils no-code : Télécharger openapi.json
Clés API
Créez et révoquez vos clés sur la page Clés API de votre tableau de bord.
Chaque clé appartient à votre espace de travail et hérite de la limite de requêtes de votre forfait.
La révocation d'une clé prend effet immédiatement.
Autorisations (scopes)
Lors de la création d'une clé, accordez-lui un accès complet ou seulement les autorisations nécessaires à une intégration. Une clé sans une autorisation reçoit 403 avec l'erreur insufficient_scope et required_scope dans la réponse.
qr:read— Lire les QR codes- Lister et consulter les QR codes, leurs images, dossiers et étiquettes.
qr:write— Gérer les QR codes- Créer des QR codes (y compris en masse), les modifier, les déplacer entre dossiers, les étiqueter et les supprimer.
analytics:read— Lire les statistiques- Statistiques de scan et journal des scans de chaque QR code.
webhooks:manage— Gérer les webhooks- Abonner des endpoints à des événements et les désabonner (Zapier, Make).
Les clés créées avant l'introduction des autorisations conservent un accès complet. L'accès complet couvre aussi les autorisations ajoutées plus tard.
Exemples
Des commandes curl à copier-coller pour démarrer. Remplacez YOUR_API_KEY par une clé de la page Clés API.
Lister les QR codes
curl -sS -H "X-Api-Key: YOUR_API_KEY" -H "Accept: application/json" \ "https://qr-global.com/api/v1/qr-codes"
Créer un QR code
Envoyez le type de QR et son contenu ; le serveur génère et enregistre le code.
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"type":"url","content":"https://example.com","display_name":"Example link"}'Générer une image
Récupérez un fichier PNG ou SVG prêt à l'emploi — passez ?format=png
curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=png&size=512" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.png # SVG (vector, no size limit on scale): curl -sS "https://qr-global.com/api/v1/qr-codes/123/image?format=svg" \ -H "X-Api-Key: YOUR_API_KEY" -o qr.svg
Exemple de payload de webhook
{
"event": "qr.scan.created",
"timestamp": "2026-04-03T12:00:00+00:00",
"data": {
"qr_code_id": 7,
"qr_code_uuid": "9b2f0c1e-4d4a-4f7e-9a51-2a7c3c1d8e10",
"type": "url",
"scan_id": 42,
"country": "UA",
"device_type": "mobile",
"scanned_at": "2026-04-03T12:00:00+00:00"
}
}Statistiques de scan
GET /qr-codes/{id}/stats renvoie les totaux, les visiteurs uniques, les principaux pays, les appareils, les navigateurs et les scans par jour. GET /qr-codes/{id}/scans renvoie le journal des scans, du plus récent au plus ancien, 50 par page (per_page jusqu'à 100).
Les deux acceptent from et to (une date comme 2026-10-01 ou un horodatage complet) ainsi que timezone (UTC par défaut). Une date sans heure couvre toute la journée dans ce fuseau horaire.
Seule la période d'historique de votre forfait est disponible : les scans plus anciens sont supprimés. Les adresses IP et les user agents des visiteurs ne sont jamais renvoyés.
Statistiques de scan sur une période
curl -sS "https://qr-global.com/api/v1/qr-codes/123/stats?from=2026-10-01&to=2026-10-31&timezone=Europe/Kyiv" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Journal des scans, deuxième page
curl -sS "https://qr-global.com/api/v1/qr-codes/123/scans?per_page=100&page=2" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Dossiers et étiquettes
GET /folders et GET /tags listent les dossiers et les étiquettes de votre espace de travail. Passez folder_id et tags (slugs des étiquettes) lorsque vous créez ou modifiez un QR code : folder_id null retire le code de son dossier, et tags remplace l'ensemble des étiquettes.
Filtrez la liste des QR codes avec ?folder_id= ou ?tag=.
Déplacer un QR code dans un dossier et l'étiqueter
curl -sS -X PUT "https://qr-global.com/api/v1/qr-codes/123" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"folder_id": 4,
"tags": [
"campaign",
"priority"
]
}'Création en masse
POST /qr-codes/bulk crée jusqu'à 100 QR codes en une seule requête. Il faut un forfait incluant la création en masse, comme pour l'import CSV du tableau de bord, et votre limite de QR codes actifs s'applique.
Chaque élément est traité séparément : la réponse liste chaque élément avec le statut created (et le nouveau code) ou failed (avec error et errors). Ne renvoyez pas tout le lot, seulement les éléments en échec.
Créer deux QR codes
curl -sS -X POST "https://qr-global.com/api/v1/qr-codes/bulk" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"codes": [
{
"type": "url",
"content": "https://example.com/spring",
"display_name": "Spring flyer",
"tags": [
"campaign"
]
},
{
"type": "url",
"content": "https://example.com/menu",
"display_name": "Table menu",
"folder_id": 4
}
]
}'Abonnements aux webhooks (REST hooks)
Zapier, Make et vos propres services peuvent s'abonner à des événements via l'API : POST /webhooks avec url et events, puis DELETE /webhooks/{id} pour se désabonner. Ce sont les mêmes endpoints que sur la page Webhooks.
La réponse à POST contient secret, affiché une seule fois : utilisez-le pour vérifier l'en-tête X-Webhook-Signature. Si vous n'envoyez pas votre propre secret (16 caractères minimum), nous en générons un.
Événements : qr.scan.created, subscription.updated, payment.succeeded, lead.captured, rsvp.received, feedback.received, poll.voted. L'abonnement nécessite un forfait avec webhooks ; le désabonnement fonctionne toujours. Un espace de travail peut compter jusqu'à 25 endpoints.
S'abonner aux scans
curl -sS -X POST "https://qr-global.com/api/v1/webhooks" \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.zapier.com/hooks/catch/123/abc/",
"events": [
"qr.scan.created"
]
}'Se désabonner
curl -sS -X DELETE "https://qr-global.com/api/v1/webhooks/42" \ -H "X-Api-Key: YOUR_API_KEY" \ -H "Accept: application/json"
Webhooks
Les webhooks envoient les événements à votre endpoint dès qu'ils se produisent : plus besoin d'interroger l'API en boucle.
Configurez vos endpoints sur la page Webhooks de votre tableau de bord.
Chaque livraison est signée et, en cas d'échec, relancée avec un délai exponentiel.
L'événement scan se déclenche lorsqu'une personne scanne l'un de vos QR codes.
Consultez les tentatives de livraison, les payloads et les réponses dans le journal des livraisons.
Renvoyez un statut 2xx pour accuser réception d'une livraison ; tout autre statut est considéré comme un échec.
Suivi des conversions
Les conversions indiquent au test A/B quelle destination génère des commandes ou des inscriptions, et pas seulement des scans. Avec l'optimisation automatique, le trafic bascule vers la variante qui convertit le mieux.
Ajoutez le script à la page que le visiteur voit après la conversion : confirmation de commande, page de remerciement ou de succès. Il fonctionne sur n'importe quel domaine et ne nécessite pas de clé API.
Extrait
<script src="https://qr-global.com/c.js" async></script>
- Chaque scan ajoute à l'URL de destination un paramètre signé qrg_v, qui rattache la conversion au code QR et à la variante.
- Le script conserve le jeton dans un cookie propriétaire pendant 30 jours : la conversion compte même si le visiteur consulte d'abord d'autres pages.
- Chaque scan compte une seule fois : recharger la page de remerciement n'ajoute pas de conversion.
- Fonctionne pour les codes QR qui redirigent vers une page http(s).
Exports
Exportez vos QR codes, scans, emplacements et votre activité au format CSV depuis la page Exports.
Les exports utilisent la session de votre tableau de bord, et non une clé API : ouvrez-les en étant connecté.
Conseils et erreurs courantes
- 401 Unauthorized — la clé API est absente ou invalide. Vérifiez l'en-tête X-Api-Key.
- 403 Forbidden — la clé ne dispose pas de l'autorisation requise (insufficient_scope) ou votre forfait n'inclut pas la fonctionnalité (api_access_required, bulk_not_available, webhooks_not_available).
- 404 Not Found — la ressource n'existe pas ou appartient à un autre espace de travail.
- 429 Too Many Requests — vous avez atteint la limite par minute de votre forfait. Attendez le nombre de secondes indiqué dans l'en-tête Retry-After.
- Certaines fonctionnalités (comme les webhooks) dépendent de votre forfait. Passez à un forfait supérieur si un endpoint renvoie une erreur de fonctionnalité.
- Aucune livraison de webhook pour l'instant ? Scannez l'un de vos QR codes pour en déclencher une.
- Les livraisons de webhooks échouées sont relancées automatiquement ; vous pouvez aussi les relancer manuellement depuis le journal des livraisons.
- Les membres de l'équipe agissent au sein de votre espace de travail ; les clés et les données sont rattachées au propriétaire de l'espace.