API QRavate
QR codes dynamiques, règles de redirection, changements programmés, statistiques et webhooks.
URL de base : https://www.qravate.com/api/v1 · Spécification : OpenAPI 3.1 · Toute la documentation pour une IA : docs.md
L’API REST de QRavate crée des QR codes dynamiques, change leur destination après impression, programme des changements et lit les statistiques de scans. Elle reçoit et renvoie du JSON, utilise les codes HTTP habituels et s’authentifie par clé secrète.
Elle est incluse à partir du plan Pro. Les mêmes règles que l’application s’appliquent : limites du plan, contrôle anti-abus des destinations, isolation entre espaces de travail.
Démarrage rapide
- Dans votre espace, ouvrez API et webhooks et créez une clé. Elle commence par
sk_et ne s’affiche qu’une fois : rangez-la dans un gestionnaire de secrets. - Vérifiez la clé avec
GET /me, qui renvoie l’espace et le plan liés. - Créez votre premier QR code :
curl -X POST https://www.qravate.com/api/v1/qr \
-H "Authorization: Bearer sk_…" \
-H "Content-Type: application/json" \
-d '{"name":"Affiche vitrine","destination":"https://exemple.fr/offre"}'
La réponse contient short_url, l’adresse encodée dans le QR code, et id, à réutiliser dans les autres appels. Téléchargez l’image avec GET /qr/{id}/image.svg, imprimez-la, puis changez la destination quand vous voulez avec PATCH /qr/{id} : le code imprimé ne change pas.
Authentification
Chaque requête porte la clé dans l’en-tête Authorization :
Authorization: Bearer sk_…
L’en-tête X-API-Key: sk_… est aussi accepté, pour les outils qui ne savent pas envoyer de jeton « Bearer ». Une clé donne accès à un seul espace de travail, en lecture et en écriture. Elle se révoque à tout moment depuis API et webhooks ; une clé révoquée répond 401 immédiatement.
N’appelez jamais l’API depuis un navigateur ou une application mobile avec votre clé : elle serait lisible par tous. Passez par votre serveur.
Limites de débit
120 requêtes par minute et par clé, et 300 créations de QR codes par heure et par espace. Au-delà, l’API répond 429 avec le code rate_limited : attendez quelques secondes avant de réessayer, en espaçant les tentatives (attente exponentielle).
Les limites du plan s’appliquent aussi : nombre de QR codes dynamiques, de règles par QR code, de changements programmés et durée d’historique des statistiques. Une limite atteinte répond 403 avec le code plan_limit.
Pagination
GET /qr renvoie au plus limit éléments (50 par défaut, 200 au plus), du plus récent au plus ancien, et next_cursor. Pour la page suivante, repassez cette valeur dans cursor. next_cursor vaut null sur la dernière page.
curl "https://www.qravate.com/api/v1/qr?limit=100&cursor=2026-10-02T09:14:00.000Z" -H "Authorization: Bearer sk_…"
Erreurs
Une erreur répond avec un statut HTTP 4xx et un corps de la même forme :
{ "error": { "code": "plan_limit", "message": "Limite de votre plan atteinte (500 QR codes dynamiques)." } }
message est rédigé en français pour être montré tel quel ; code est stable et sert à vos traitements.
| Statut | Code | Signification |
|---|---|---|
| 400 | invalid_request | Paramètre manquant ou invalide, JSON mal formé. |
| 401 | unauthorized | Clé absente, invalide ou révoquée. |
| 403 | plan_required | Le plan de l’espace n’inclut pas l’API. |
| 403 | plan_limit | Limite du plan atteinte (QR codes, règles, changements programmés). |
| 403 | read_only | Abonnement terminé : l’espace est en lecture seule. |
| 403 | blocked | QR code bloqué par l’équipe anti-abus. |
| 404 | not_found | QR code, changement programmé ou ressource introuvable dans cet espace. |
| 409 | deleted | QR code supprimé : restaurez-le depuis l’application. |
| 422 | destination_blocked | Destination présente sur une liste de sites dangereux. |
| 429 | rate_limited | Plus de 120 requêtes par minute. |
QR codes et états
Un QR code a un id (identifiant d’API) et un code (la partie courte de short_url). Il redirige vers une URL (type: url) ou affiche une page hébergée (type: page : menu, PDF, carte de contact ou liste de liens).
| État | Au scan |
|---|---|
active | Redirige vers la destination, ou applique les règles. |
paused | Affiche une page « QR code temporairement indisponible », sans rediriger. |
deleted | Supprimé, restaurable 30 jours depuis l’application, puis effacé. |
blocked | Bloqué par l’équipe anti-abus ; seul le support peut le débloquer. |
Un changement de destination, d’état ou de règles s’applique partout en une minute environ.
Règles de redirection
rules est une liste ordonnée : la première règle active dont toutes les conditions sont remplies l’emporte, sinon la destination principale s’applique. Une liste vide retire les règles.
{
"rules": [
{ "name": "App Store", "when": { "os": ["ios"] }, "to": [{ "url": "https://apps.apple.com/…" }] },
{ "name": "Menu anglais", "when": { "lang": ["en"], "time": { "from": "11:30", "to": "15:00" } }, "to": [{ "url": "https://exemple.fr/en" }] },
{ "name": "Test A/B", "when": {}, "to": [{ "url": "https://exemple.fr/a", "weight": 50 }, { "url": "https://exemple.fr/b", "weight": 50 }] }
],
"rules_clock": "paris"
}
| Condition | Valeurs |
|---|---|
device | mobile, tablet, desktop |
os | ios, android, windows, macos, linux, other |
app | instagram, facebook, messenger, linkedin, tiktok, snapchat, google, wechat, line, browser |
lang | Codes de langue (fr, en…) |
country | Codes pays ISO 3166-1 (FR, BE…) |
weekday | 1 = lundi … 7 = dimanche |
time | { "from": "HH:MM", "to": "HH:MM" } |
date | { "from": "AAAA-MM-JJ", "to": "AAAA-MM-JJ" }, bornes incluses |
rules_clock choisit l’heure des conditions weekday, time et date : paris (par défaut) ou scanner, le fuseau de la personne qui scanne. De 2 à 4 destinations avec weight (somme 100) font un test A/B, à partir du plan Pro. Chaque destination passe le contrôle anti-abus. Nombre de règles par QR code : 5 avec Essentiel, 10 avec Pro et Max.
Paramètres UTM
utm vaut true pour ajouter utm_source=qravate&utm_medium=qr et le nom du QR code en utm_campaign, un objet { source, medium, campaign, content } pour les personnaliser, false pour les retirer. Ils sont désactivés par défaut dans l’API, pour ne pas changer l’URL finale d’une intégration existante.
Une destination qui contient déjà un paramètre utm_* n’est jamais modifiée. served_destination donne l’adresse réellement ouverte au scan.
Changements programmés
POST /qr/{id}/schedules programme une nouvelle destination à une date donnée (ISO 8601 avec fuseau, par exemple 2026-06-21T08:00:00+02:00). Le changement s’applique dans le quart d’heure qui suit, d’une minute à deux ans à l’avance, 5 changements en attente au plus par QR code. Un changement échoué passe à failed, avec la raison dans error.
Statistiques
GET /stats et GET /qr/{id}/stats acceptent from et to (AAAA-MM-JJ, jours de Paris, 30 derniers jours par défaut). La période est ramenée à l’historique du plan : 365 jours avec Essentiel, 3 ans avec Pro et Max.
La réponse donne les scans et les visiteurs uniques jour par jour, leurs totaux, et la répartition par pays, ville, appareil, système, navigateur, langue et règle appliquée. Les visiteurs uniques sont estimés sans cookie ni identifiant stocké.
Webhooks
Les webhooks préviennent votre serveur d’un événement, sans scruter l’API. Abonnez une URL en https depuis API et webhooks ou avec POST /webhooks.
| Événement | Envoyé quand |
|---|---|
qr.created | Un QR code est créé (application, API, import ou assistant IA). |
qr.destination_changed | La destination ou la page hébergée change, y compris par un changement programmé. |
qr.state_changed | Un QR code est mis en pause, réactivé ou supprimé. |
scans.threshold | Un QR code atteint scan_threshold scans au total ; vérifié toutes les heures, une seule fois par QR code et par webhook. |
Aucun événement n’est envoyé à chaque scan. Chaque envoi est un POST JSON :
{ "event": "qr.destination_changed", "created_at": "2026-11-14T10:02:11.000Z", "data": { "id": "…", "code": "aB3x9Q", "destination": "https://exemple.fr/nouvelle-offre" } }
Vérifier la signature
L’en-tête X-Webhook-Signature: t=1763114531,v1=5d41… signe chaque envoi. v1 est le HMAC-SHA256 hexadécimal de t + "." + corps brut, avec le secret du webhook (renvoyé une seule fois à sa création). Refusez un envoi dont la signature ne correspond pas, ou dont t a plus de cinq minutes.
import { createHmac, timingSafeEqual } from 'node:crypto';
export function verify(rawBody, header, secret) {
const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
const expected = createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}
Réponses et nouvelles tentatives
Répondez 2xx en moins de 10 secondes. Après 20 échecs consécutifs, le webhook est désactivé : recréez-le une fois votre serveur réparé. Répondez 410 pour vous désabonner : c’est ce que font Zapier et Make quand un scénario est supprimé.
Assistants IA (MCP)
Le serveur MCP, https://www.qravate.com/mcp, branche Claude, ChatGPT, Le Chat, Gemini CLI, Cursor ou tout client compatible. Le mode d’emploi pas à pas est sur la page QR code et IA.
Il crée des QR codes avec un design (style, couleurs, icône ou logo, texte d’appel), change une destination ou un design, programme un changement et lit les statistiques. La connexion passe par OAuth : aucune clé à copier, la personne peut créer son compte pendant la connexion, et l’accès en écriture se donne à part. Les fonctions liées à un plan (règles, comparaison, export, statistiques avancées) répondent avec le plan qui les inclut, et le nombre d’actions par jour dépend du plan (30 en Gratuit, 300 en Essentiel, 5 000 en Pro et Max). Les connexions se gèrent dans Assistants IA.
Sans connecteur, un assistant peut aussi donner un lien qui ouvre le générateur déjà rempli : https://www.qravate.com/generator#url=…&style=…&icon=…&cta=… (voir QR code et IA).
Les outils de création renvoient le QR code en SVG et une carte interactive (extension MCP Apps) : Claude et ChatGPT l’affichent dans la conversation, avec téléchargement PNG et SVG. Les icônes prédéfinies sont listées par l’outil list_design_options, et utilisables dans l’API avec design.logo.icon.
Zapier, n8n et Make
Les connecteurs Zapier, n8n et Make utilisent cette API et la même clé : déclencheurs sur les événements des webhooks, actions pour créer un QR code, changer sa destination, le mettre en pause ou lire ses statistiques. Ils s’abonnent et se désabonnent seuls avec POST /webhooks et DELETE /webhooks/{id}.
Versions
L’API est en version 1, dans le chemin /api/v1. Nous pouvons ajouter des champs aux réponses, des paramètres facultatifs et des événements de webhook sans changer de version : ignorez les champs que vous ne connaissez pas. Un changement incompatible passera par une version 2, annoncée à l’avance par e-mail aux propriétaires de clés.
Référence
| Méthode | Chemin | Action |
|---|---|---|
| Espace | ||
| GET | /me | Espace lié à la clé |
| QR codes | ||
| GET | /qr | Lister les QR codes |
| POST | /qr | Créer un QR code |
| GET | /qr/{id} | Lire un QR code |
| PATCH | /qr/{id} | Modifier un QR code |
| DELETE | /qr/{id} | Supprimer un QR code |
| GET | /qr/{id}/image.svg | Image SVG |
| Changements programmés | ||
| GET | /qr/{id}/schedules | Lister les changements programmés |
| POST | /qr/{id}/schedules | Programmer un changement de destination |
| DELETE | /qr/{id}/schedules/{schedule_id} | Annuler un changement programmé |
| Statistiques | ||
| GET | /qr/{id}/stats | Statistiques d’un QR code |
| GET | /stats | Statistiques de l’espace |
| Webhooks | ||
| GET | /webhooks | Lister les webhooks |
| POST | /webhooks | Abonner un webhook |
| DELETE | /webhooks/{id} | Désabonner un webhook |