QRavateDocs

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

  1. 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.
  2. Vérifiez la clé avec GET /me, qui renvoie l’espace et le plan liés.
  3. 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.

StatutCodeSignification
400invalid_requestParamètre manquant ou invalide, JSON mal formé.
401unauthorizedClé absente, invalide ou révoquée.
403plan_requiredLe plan de l’espace n’inclut pas l’API.
403plan_limitLimite du plan atteinte (QR codes, règles, changements programmés).
403read_onlyAbonnement terminé : l’espace est en lecture seule.
403blockedQR code bloqué par l’équipe anti-abus.
404not_foundQR code, changement programmé ou ressource introuvable dans cet espace.
409deletedQR code supprimé : restaurez-le depuis l’application.
422destination_blockedDestination présente sur une liste de sites dangereux.
429rate_limitedPlus 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).

ÉtatAu scan
activeRedirige vers la destination, ou applique les règles.
pausedAffiche une page « QR code temporairement indisponible », sans rediriger.
deletedSupprimé, restaurable 30 jours depuis l’application, puis effacé.
blockedBloqué 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"
}
ConditionValeurs
devicemobile, tablet, desktop
osios, android, windows, macos, linux, other
appinstagram, facebook, messenger, linkedin, tiktok, snapchat, google, wechat, line, browser
langCodes de langue (fr, en…)
countryCodes pays ISO 3166-1 (FR, BE…)
weekday1 = 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énementEnvoyé quand
qr.createdUn QR code est créé (application, API, import ou assistant IA).
qr.destination_changedLa destination ou la page hébergée change, y compris par un changement programmé.
qr.state_changedUn QR code est mis en pause, réactivé ou supprimé.
scans.thresholdUn 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éthodeCheminAction
Espace
GET/meEspace lié à la clé
QR codes
GET/qrLister les QR codes
POST/qrCré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.svgImage SVG
Changements programmés
GET/qr/{id}/schedulesLister les changements programmés
POST/qr/{id}/schedulesProgrammer un changement de destination
DELETE/qr/{id}/schedules/{schedule_id}Annuler un changement programmé
Statistiques
GET/qr/{id}/statsStatistiques d’un QR code
GET/statsStatistiques de l’espace
Webhooks
GET/webhooksLister les webhooks
POST/webhooksAbonner un webhook
DELETE/webhooks/{id}Désabonner un webhook