# API QRavate

> QR codes dynamiques, règles de redirection, changements programmés, statistiques et webhooks. Version 1.0.0. URL de base : `https://www.qravate.com/api/v1`. Spécification OpenAPI : https://www.qravate.com/docs/openapi.json. Documentation en ligne : https://www.qravate.com/docs.

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](https://www.qravate.com/app/api) 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 :

```bash
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` :

```http
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](https://www.qravate.com/app/api) ; 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.

```bash
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 :

```json
{ "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.

```json
{
  "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](https://www.qravate.com/app/api) 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 :

```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.

```js
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](https://www.qravate.com/ai).

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](https://www.qravate.com/app/connections).

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](https://www.qravate.com/ai)).

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

## Espace

Vérifier une clé et lire l’espace de travail lié.

### Espace lié à la clé

`GET /me`

Vérifie la clé et renvoie l’espace et le plan. Sert de test de connexion aux connecteurs.

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/me" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Espace lié à la clé.

```json
{
  "workspace": {
    "id": "w_3k9d2a",
    "name": "Boulangerie Martin",
    "plan": "Pro"
  }
}
```

**Erreurs possibles** : 401, 403, 429 (voir « Erreurs »).

## QR codes

Créer, lire, modifier, mettre en pause et supprimer des QR codes dynamiques, et télécharger leur image.

### Lister les QR codes

`GET /qr`

Du plus récent au plus ancien, hors QR codes supprimés. Pagination par curseur : voir « Pagination ».

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `search` | requête | string | non | Recherche dans le nom et la destination. |
| `state` | requête | string | non | Filtre sur l’état. Valeurs : `active`, `paused`, `blocked`. |
| `limit` | requête | integer | non | Nombre d’éléments par page. Par défaut : `50`. De 1 à 200. |
| `cursor` | requête | string | non | `next_cursor` de la page précédente. |

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/qr" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Une page de QR codes.

```json
{
  "data": [
    {
      "id": "q_8f2k1d0c",
      "code": "aB3x9Q",
      "name": "Affiche vitrine",
      "type": "url",
      "destination": "https://exemple.fr/offre",
      "page": null,
      "state": "active",
      "short_url": "https://qravate.page/aB3x9Q",
      "folder_id": null,
      "rules": [],
      "rules_clock": "paris",
      "utm": null,
      "served_destination": "https://exemple.fr/offre",
      "gs1": null,
      "created_at": "2026-11-14T09:30:00.000Z",
      "updated_at": "2026-11-14T09:30:00.000Z"
    }
  ],
  "next_cursor": null
}
```

**Erreurs possibles** : 401, 403, 429 (voir « Erreurs »).

### Créer un QR code

`POST /qr`

Crée un QR code dynamique qui redirige vers `destination`, ou qui affiche une page hébergée (`page`). Émet `qr.created`.

**Corps JSON** (`QrCreate`)

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui | Nom interne du QR code. 120 caractères au plus. |
| `destination` | string (uri) | non | URL de destination (http ou https). Contrôlée par l’anti-abus. |
| `page` | HostedPage | non | Voir l’objet `HostedPage`. |
| `folder_id` | string | non | Dossier où ranger le QR code. |
| `design` | Design | non | Voir l’objet `Design`. |
| `domain_id` | string | non | Domaine personnalisé vérifié, à la place du domaine de scan. |
| `custom_path` | string | non | Chemin sur le domaine personnalisé (lettres, chiffres, tirets, points et barres obliques). Par défaut, le code court. |
| `utm` | boolean \| Utm | non | `true` pour les valeurs par défaut, un objet pour les personnaliser. Par défaut : `false`. |
| `rules` | Rule[] | non | Voir l’objet `Rule`. |
| `rules_clock` | string | non | Valeurs : `paris`, `scanner`. Par défaut : `"paris"`. |
| `gs1` | Gs1 | non | Voir l’objet `Gs1`. |

Autre exemple, avec des règles :

```json
{
  "name": "Application",
  "destination": "https://exemple.fr/app",
  "rules": [
    {
      "name": "iPhone",
      "when": {
        "os": [
          "ios"
        ]
      },
      "to": [
        {
          "url": "https://apps.apple.com/app/id000"
        }
      ]
    },
    {
      "name": "Android",
      "when": {
        "os": [
          "android"
        ]
      },
      "to": [
        {
          "url": "https://play.google.com/store/apps/details?id=fr.exemple"
        }
      ]
    }
  ]
}
```

Autre exemple, page de liens :

```json
{
  "name": "Carte de visite",
  "page": {
    "kind": "links",
    "title": "Nous suivre",
    "links": [
      {
        "label": "Site",
        "url": "https://exemple.fr"
      }
    ]
  }
}
```

Autre exemple, produit gs1 digital link :

```json
{
  "name": "Confiture 250 g",
  "destination": "https://exemple.fr/confiture",
  "gs1": {
    "gtin": "3760123456784",
    "links": [
      {
        "type": "gs1:recallStatus",
        "url": "https://exemple.fr/rappel"
      }
    ]
  }
}
```

Autre exemple, avec un design :

```json
{
  "name": "Flyer",
  "destination": "https://exemple.fr",
  "design": {
    "fg": "#15162b",
    "moduleShape": "rounded",
    "eyeShape": "rounded",
    "logo": {
      "icon": "menu",
      "size": 0.2,
      "zone": "round"
    },
    "frame": {
      "style": "bottom",
      "text": "Voir le menu"
    }
  }
}
```

**Exemple**

```bash
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","utm":true}'
```

**Réponse 201** : QR code créé.

```json
{
  "data": {
    "id": "q_8f2k1d0c",
    "code": "aB3x9Q",
    "name": "Affiche vitrine",
    "type": "url",
    "destination": "https://exemple.fr/offre",
    "page": null,
    "state": "active",
    "short_url": "https://qravate.page/aB3x9Q",
    "folder_id": null,
    "rules": [],
    "rules_clock": "paris",
    "utm": null,
    "served_destination": "https://exemple.fr/offre",
    "gs1": null,
    "created_at": "2026-11-14T09:30:00.000Z",
    "updated_at": "2026-11-14T09:30:00.000Z"
  }
}
```

**Erreurs possibles** : 400, 401, 403, 422, 429 (voir « Erreurs »).

### Lire un QR code

`GET /qr/{id}`

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/qr/q_8f2k1d0c" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Le QR code.

```json
{
  "data": {
    "id": "q_8f2k1d0c",
    "code": "aB3x9Q",
    "name": "Affiche vitrine",
    "type": "url",
    "destination": "https://exemple.fr/offre",
    "page": null,
    "state": "active",
    "short_url": "https://qravate.page/aB3x9Q",
    "folder_id": null,
    "rules": [],
    "rules_clock": "paris",
    "utm": null,
    "served_destination": "https://exemple.fr/offre",
    "gs1": null,
    "created_at": "2026-11-14T09:30:00.000Z",
    "updated_at": "2026-11-14T09:30:00.000Z"
  }
}
```

**Erreurs possibles** : 401, 403, 404, 429 (voir « Erreurs »).

### Modifier un QR code

`PATCH /qr/{id}`

Change la destination, le nom, le dossier, le design, l’état, les règles ou les UTM. Le code imprimé ne change pas. Émet `qr.destination_changed` ou `qr.state_changed` selon le cas.

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |

**Corps JSON** (`QrUpdate`)

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | non | 120 caractères au plus. |
| `destination` | string (uri) | non | Nouvelle destination, effective en une minute environ. |
| `page` | HostedPage | non | Voir l’objet `HostedPage`. |
| `folder_id` | string \| null | non |  |
| `design` | Design | non | Voir l’objet `Design`. |
| `state` | string | non | Met en pause ou réactive le QR code. Valeurs : `active`, `paused`. |
| `rules` | Rule[] | non | Remplace toutes les règles. Une liste vide les retire. Voir l’objet `Rule`. |
| `rules_clock` | string | non | Valeurs : `paris`, `scanner`. |
| `utm` | boolean \| Utm | non |  |
| `gs1` | Gs1 \| null | non | Remplace le produit GS1 et ses liens ; `null` le retire. L’adresse encodée change : retéléchargez le code. |

Autre exemple, mettre en pause :

```json
{
  "state": "paused"
}
```

Autre exemple, test a/b :

```json
{
  "rules": [
    {
      "name": "Test A/B",
      "when": {},
      "to": [
        {
          "url": "https://exemple.fr/a",
          "weight": 50
        },
        {
          "url": "https://exemple.fr/b",
          "weight": 50
        }
      ]
    }
  ]
}
```

Autre exemple, utm personnalisés :

```json
{
  "utm": {
    "source": "flyer",
    "medium": "qr",
    "campaign": "printemps"
  }
}
```

**Exemple**

```bash
curl -X PATCH "https://www.qravate.com/api/v1/qr/q_8f2k1d0c" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{"destination":"https://exemple.fr/nouvelle-offre"}'
```

**Réponse 200** : QR code modifié.

```json
{
  "data": {
    "id": "q_8f2k1d0c",
    "code": "aB3x9Q",
    "name": "Affiche vitrine",
    "type": "url",
    "destination": "https://exemple.fr/nouvelle-offre",
    "page": null,
    "state": "active",
    "short_url": "https://qravate.page/aB3x9Q",
    "folder_id": null,
    "rules": [],
    "rules_clock": "paris",
    "utm": null,
    "served_destination": "https://exemple.fr/nouvelle-offre",
    "gs1": null,
    "created_at": "2026-11-14T09:30:00.000Z",
    "updated_at": "2026-11-14T09:30:00.000Z"
  }
}
```

**Erreurs possibles** : 400, 401, 403, 404, 409, 422, 429 (voir « Erreurs »).

### Supprimer un QR code

`DELETE /qr/{id}`

Le QR code cesse de rediriger. Il reste restaurable 30 jours depuis l’application, puis il est effacé ; son code n’est jamais réattribué. Émet `qr.state_changed`.

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |

**Exemple**

```bash
curl -X DELETE "https://www.qravate.com/api/v1/qr/q_8f2k1d0c" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : QR code supprimé.

```json
{
  "data": {
    "deleted": true,
    "restorable_days": 30
  }
}
```

**Erreurs possibles** : 401, 403, 404, 429 (voir « Erreurs »).

### Image SVG

`GET /qr/{id}/image.svg`

Image vectorielle du QR code avec son design et son logo, prête à imprimer à toute taille.

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/qr/q_8f2k1d0c/image.svg" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Image SVG.

Corps : l’image, en `image/svg+xml`.

**Erreurs possibles** : 401, 403, 404, 429 (voir « Erreurs »).

## Changements programmés

Programmer une nouvelle destination à une date donnée, appliquée dans le quart d’heure.

### Lister les changements programmés

`GET /qr/{id}/schedules`

Changements en attente d’abord, du plus proche au plus lointain, puis l’historique (100 au plus).

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/qr/q_8f2k1d0c/schedules" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Changements programmés.

```json
{
  "data": [
    {
      "id": "s_41c9e2",
      "qr_id": "q_8f2k1d0c",
      "run_at": "2026-12-01T07:00:00.000Z",
      "destination": "https://exemple.fr/noel",
      "status": "pending",
      "error": null,
      "created_at": "2026-11-14T09:35:00.000Z",
      "done_at": null
    }
  ]
}
```

**Erreurs possibles** : 401, 403, 404, 429 (voir « Erreurs »).

### Programmer un changement de destination

`POST /qr/{id}/schedules`

La nouvelle destination s’applique dans le quart d’heure qui suit `run_at`. D’une minute à deux ans à l’avance ; 5 changements en attente au plus par QR code. Réservé aux QR codes qui redirigent vers une URL.

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |

**Corps JSON**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `run_at` | string (date-time) | oui | ISO 8601 avec fuseau. |
| `destination` | string (uri) | oui |  |

**Exemple**

```bash
curl -X POST "https://www.qravate.com/api/v1/qr/q_8f2k1d0c/schedules" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{"run_at":"2026-12-01T08:00:00+01:00","destination":"https://exemple.fr/noel"}'
```

**Réponse 201** : Changement programmé.

```json
{
  "data": {
    "id": "s_41c9e2",
    "qr_id": "q_8f2k1d0c",
    "run_at": "2026-12-01T07:00:00.000Z",
    "destination": "https://exemple.fr/noel",
    "status": "pending",
    "error": null,
    "created_at": "2026-11-14T09:35:00.000Z",
    "done_at": null
  }
}
```

**Erreurs possibles** : 400, 401, 403, 404, 409, 422, 429 (voir « Erreurs »).

### Annuler un changement programmé

`DELETE /qr/{id}/schedules/{schedule_id}`

Seul un changement en attente (`pending`) peut être annulé.

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |
| `schedule_id` | chemin | string | oui | Identifiant du changement programmé. |

**Exemple**

```bash
curl -X DELETE "https://www.qravate.com/api/v1/qr/q_8f2k1d0c/schedules/s_41c9e2" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Changement annulé.

```json
{
  "data": {
    "cancelled": true
  }
}
```

**Erreurs possibles** : 401, 403, 404, 409, 429 (voir « Erreurs »).

## Statistiques

Scans par jour, pays, ville, appareil, système, navigateur, langue et règle.

### Statistiques d’un QR code

`GET /qr/{id}/stats`

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du QR code (`id`). |
| `from` | requête | string (date) | non | Premier jour (AAAA-MM-JJ, heure de Paris). Par défaut, il y a 29 jours. |
| `to` | requête | string (date) | non | Dernier jour inclus. Par défaut, aujourd’hui. |

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/qr/q_8f2k1d0c/stats" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Statistiques de la période.

```json
{
  "data": {
    "from": "2026-11-01",
    "to": "2026-11-03",
    "days": [
      {
        "day": "2026-11-01",
        "scans": 42,
        "uniques": 37
      },
      {
        "day": "2026-11-02",
        "scans": 18,
        "uniques": 16
      },
      {
        "day": "2026-11-03",
        "scans": 25,
        "uniques": 22
      }
    ],
    "total": 85,
    "uniques": 75,
    "dims": {
      "country": [
        {
          "value": "FR",
          "scans": 71
        },
        {
          "value": "BE",
          "scans": 14
        }
      ],
      "city": [
        {
          "value": "Lyon",
          "scans": 40
        },
        {
          "value": "Bruxelles",
          "scans": 14
        }
      ],
      "device": [
        {
          "value": "mobile",
          "scans": 80
        },
        {
          "value": "tablet",
          "scans": 5
        }
      ],
      "os": [
        {
          "value": "ios",
          "scans": 47
        },
        {
          "value": "android",
          "scans": 38
        }
      ],
      "browser": [
        {
          "value": "safari",
          "scans": 45
        },
        {
          "value": "chrome",
          "scans": 40
        }
      ],
      "language": [
        {
          "value": "fr",
          "scans": 76
        },
        {
          "value": "en",
          "scans": 9
        }
      ],
      "rule": [
        {
          "value": "Menu anglais",
          "scans": 9
        }
      ]
    }
  }
}
```

**Erreurs possibles** : 400, 401, 403, 404, 429 (voir « Erreurs »).

### Statistiques de l’espace

`GET /stats`

Tous les QR codes de l’espace, sur la période.

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `from` | requête | string (date) | non | Premier jour (AAAA-MM-JJ, heure de Paris). Par défaut, il y a 29 jours. |
| `to` | requête | string (date) | non | Dernier jour inclus. Par défaut, aujourd’hui. |

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/stats" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Statistiques de la période.

```json
{
  "data": {
    "from": "2026-11-01",
    "to": "2026-11-03",
    "days": [
      {
        "day": "2026-11-01",
        "scans": 42,
        "uniques": 37
      },
      {
        "day": "2026-11-02",
        "scans": 18,
        "uniques": 16
      },
      {
        "day": "2026-11-03",
        "scans": 25,
        "uniques": 22
      }
    ],
    "total": 85,
    "uniques": 75,
    "dims": {
      "country": [
        {
          "value": "FR",
          "scans": 71
        },
        {
          "value": "BE",
          "scans": 14
        }
      ],
      "city": [
        {
          "value": "Lyon",
          "scans": 40
        },
        {
          "value": "Bruxelles",
          "scans": 14
        }
      ],
      "device": [
        {
          "value": "mobile",
          "scans": 80
        },
        {
          "value": "tablet",
          "scans": 5
        }
      ],
      "os": [
        {
          "value": "ios",
          "scans": 47
        },
        {
          "value": "android",
          "scans": 38
        }
      ],
      "browser": [
        {
          "value": "safari",
          "scans": 45
        },
        {
          "value": "chrome",
          "scans": 40
        }
      ],
      "language": [
        {
          "value": "fr",
          "scans": 76
        },
        {
          "value": "en",
          "scans": 9
        }
      ],
      "rule": [
        {
          "value": "Menu anglais",
          "scans": 9
        }
      ]
    }
  }
}
```

**Erreurs possibles** : 400, 401, 403, 429 (voir « Erreurs »).

## Webhooks

Abonner une URL aux événements `qr.created`, `qr.destination_changed`, `qr.state_changed`, `scans.threshold`. Format et signature : voir « Webhooks » dans l’introduction.

### Lister les webhooks

`GET /webhooks`

**Exemple**

```bash
curl -X GET "https://www.qravate.com/api/v1/webhooks" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Webhooks de l’espace.

```json
{
  "data": [
    {
      "id": "h_7d1e0b",
      "url": "https://exemple.fr/hooks/qravate",
      "events": "qr.created,scans.threshold",
      "scan_threshold": 1000,
      "source": "api",
      "disabled_at": null,
      "created_at": "2026-11-14T09:40:00.000Z"
    }
  ]
}
```

**Erreurs possibles** : 401, 403, 429 (voir « Erreurs »).

### Abonner un webhook

`POST /webhooks`

Abonne une URL en https (REST hook). Le `secret` de signature n’est renvoyé qu’à la création.

**Corps JSON**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `url` | string (uri) | oui | URL en https. |
| `events` | string[] | oui | Valeurs : `qr.created`, `qr.destination_changed`, `qr.state_changed`, `scans.threshold`. |
| `scan_threshold` | integer | non | Nombre de scans qui déclenche `scans.threshold`. De 1 à …. |
| `source` | string | non | Origine affichée dans l’application. Par défaut : `"api"`. 20 caractères au plus. |

**Exemple**

```bash
curl -X POST "https://www.qravate.com/api/v1/webhooks" \
  -H "Authorization: Bearer sk_…" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemple.fr/hooks/qravate","events":["qr.created","scans.threshold"],"scan_threshold":1000}'
```

**Réponse 201** : Webhook créé.

```json
{
  "data": {
    "id": "h_7d1e0b",
    "secret": "whsec_9f8e7d6c5b4a3f2e1d0c9b8a",
    "events": [
      "qr.created",
      "scans.threshold"
    ]
  }
}
```

**Erreurs possibles** : 400, 401, 403, 429 (voir « Erreurs »).

### Désabonner un webhook

`DELETE /webhooks/{id}`

**Paramètres**

| Nom | Où | Type | Obligatoire | Description |
|---|---|---|---|---|
| `id` | chemin | string | oui | Identifiant du webhook. |

**Exemple**

```bash
curl -X DELETE "https://www.qravate.com/api/v1/webhooks/q_8f2k1d0c" \
  -H "Authorization: Bearer sk_…"
```

**Réponse 200** : Webhook supprimé.

```json
{
  "data": {
    "deleted": true
  }
}
```

**Erreurs possibles** : 401, 403, 429 (voir « Erreurs »).

# Événements de webhook

Envoyés en `POST` JSON à l’URL abonnée, signés par l’en-tête `X-Webhook-Signature` (voir « Webhooks »).

## qr.created

Un QR code est créé, depuis l’application, l’API, un import ou un assistant IA. `data` est le QR code.

```json
{
  "event": "qr.created",
  "created_at": "2026-11-14T10:02:11.000Z",
  "data": {
    "id": "q_8f2k1d0c",
    "code": "aB3x9Q",
    "name": "Affiche vitrine",
    "type": "url",
    "destination": "https://exemple.fr/offre",
    "page": null,
    "state": "active",
    "short_url": "https://qravate.page/aB3x9Q",
    "folder_id": null,
    "rules": [],
    "rules_clock": "paris",
    "utm": null,
    "served_destination": "https://exemple.fr/offre",
    "gs1": null,
    "created_at": "2026-11-14T09:30:00.000Z",
    "updated_at": "2026-11-14T09:30:00.000Z"
  }
}
```

## qr.destination_changed

La destination ou la page hébergée change, y compris par un changement programmé. `data` est le QR code modifié.

```json
{
  "event": "qr.destination_changed",
  "created_at": "2026-11-14T10:02:11.000Z",
  "data": {
    "id": "q_8f2k1d0c",
    "code": "aB3x9Q",
    "name": "Affiche vitrine",
    "type": "url",
    "destination": "https://exemple.fr/nouvelle-offre",
    "page": null,
    "state": "active",
    "short_url": "https://qravate.page/aB3x9Q",
    "folder_id": null,
    "rules": [],
    "rules_clock": "paris",
    "utm": null,
    "served_destination": "https://exemple.fr/offre",
    "gs1": null,
    "created_at": "2026-11-14T09:30:00.000Z",
    "updated_at": "2026-11-14T09:30:00.000Z"
  }
}
```

## qr.state_changed

Un QR code est mis en pause, réactivé ou supprimé (`state: deleted`). `data` est le QR code.

```json
{
  "event": "qr.state_changed",
  "created_at": "2026-11-14T10:02:11.000Z",
  "data": {
    "id": "q_8f2k1d0c",
    "code": "aB3x9Q",
    "name": "Affiche vitrine",
    "type": "url",
    "destination": "https://exemple.fr/offre",
    "page": null,
    "state": "paused",
    "short_url": "https://qravate.page/aB3x9Q",
    "folder_id": null,
    "rules": [],
    "rules_clock": "paris",
    "utm": null,
    "served_destination": "https://exemple.fr/offre",
    "gs1": null,
    "created_at": "2026-11-14T09:30:00.000Z",
    "updated_at": "2026-11-14T09:30:00.000Z"
  }
}
```

## 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.

```json
{
  "event": "scans.threshold",
  "created_at": "2026-11-14T10:02:11.000Z",
  "data": {
    "qr": {
      "id": "q_8f2k1d0c",
      "code": "aB3x9Q",
      "name": "Affiche vitrine",
      "type": "url",
      "destination": "https://exemple.fr/offre",
      "page": null,
      "state": "active",
      "short_url": "https://qravate.page/aB3x9Q",
      "folder_id": null,
      "rules": [],
      "rules_clock": "paris",
      "utm": null,
      "served_destination": "https://exemple.fr/offre",
      "gs1": null,
      "created_at": "2026-11-14T09:30:00.000Z",
      "updated_at": "2026-11-14T09:30:00.000Z"
    },
    "threshold": 1000,
    "total_scans": 1012
  }
}
```

# Objets

## Error

Corps de toutes les réponses en erreur.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `error` | object | oui |  |

## Workspace

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `workspace` | object | non |  |

## QrCode

Un QR code dynamique.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string | non | Identifiant d’API, à passer dans les chemins `/qr/{id}`. |
| `code` | string | non | Partie courte de l’adresse encodée. Jamais réattribuée. |
| `name` | string | non | Nom interne, visible seulement dans votre espace. 120 caractères au plus. |
| `type` | string | non | `url` : redirige vers `destination`. `page` : affiche une page hébergée. Valeurs : `url`, `page`. |
| `destination` | string \| null (uri) | non | Destination principale (QR de type `url`). |
| `page` | HostedPage \| null | non | Page hébergée (QR de type `page`). |
| `state` | string | non | État du QR code. Voir « QR codes et états » dans l’introduction. Valeurs : `active`, `paused`, `deleted`, `blocked`. |
| `short_url` | string (uri) | non | Adresse encodée dans le QR code, sur le domaine de scan ou votre domaine personnalisé. |
| `folder_id` | string \| null | non | Dossier du QR code. |
| `rules` | Rule[] | non | Règles de redirection, dans l’ordre d’évaluation. Voir l’objet `Rule`. |
| `rules_clock` | string | non | Heure des conditions de jour, d’heure et de date. Valeurs : `paris`, `scanner`. |
| `utm` | Utm \| null | non | Paramètres UTM ajoutés à la destination, ou `null`. |
| `served_destination` | string \| null (uri) | non | Adresse réellement ouverte au scan, UTM compris, hors règles. |
| `gs1` | Gs1 \| null | non | Produit GS1 Digital Link, ou `null`. Avec un produit, `short_url` est l’adresse GS1 Digital Link (`…/01/<GTIN>`). |
| `created_at` | string (date-time) | non |  |
| `updated_at` | string (date-time) | non |  |

## QrCreate

Indiquez `destination` pour un QR qui redirige, ou `page` pour une page hébergée.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui | Nom interne du QR code. 120 caractères au plus. |
| `destination` | string (uri) | non | URL de destination (http ou https). Contrôlée par l’anti-abus. |
| `page` | HostedPage | non | Voir l’objet `HostedPage`. |
| `folder_id` | string | non | Dossier où ranger le QR code. |
| `design` | Design | non | Voir l’objet `Design`. |
| `domain_id` | string | non | Domaine personnalisé vérifié, à la place du domaine de scan. |
| `custom_path` | string | non | Chemin sur le domaine personnalisé (lettres, chiffres, tirets, points et barres obliques). Par défaut, le code court. |
| `utm` | boolean \| Utm | non | `true` pour les valeurs par défaut, un objet pour les personnaliser. Par défaut : `false`. |
| `rules` | Rule[] | non | Voir l’objet `Rule`. |
| `rules_clock` | string | non | Valeurs : `paris`, `scanner`. Par défaut : `"paris"`. |
| `gs1` | Gs1 | non | Voir l’objet `Gs1`. |

## QrUpdate

Seuls les champs présents sont modifiés.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | non | 120 caractères au plus. |
| `destination` | string (uri) | non | Nouvelle destination, effective en une minute environ. |
| `page` | HostedPage | non | Voir l’objet `HostedPage`. |
| `folder_id` | string \| null | non |  |
| `design` | Design | non | Voir l’objet `Design`. |
| `state` | string | non | Met en pause ou réactive le QR code. Valeurs : `active`, `paused`. |
| `rules` | Rule[] | non | Remplace toutes les règles. Une liste vide les retire. Voir l’objet `Rule`. |
| `rules_clock` | string | non | Valeurs : `paris`, `scanner`. |
| `utm` | boolean \| Utm | non |  |
| `gs1` | Gs1 \| null | non | Remplace le produit GS1 et ses liens ; `null` le retire. L’adresse encodée change : retéléchargez le code. |

## Gs1

Produit GS1 Digital Link (plans Pro et Max). Le QR suit la norme : redirection 307, `?linkType=` pour un type de lien, `?linkType=all` pour l’ensemble des liens (application/linkset+json), langue selon le téléphone.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `gtin` | string | oui | GTIN de 8, 12, 13 ou 14 chiffres, clé de contrôle vérifiée. Rendu sur 14 chiffres. Un seul QR actif par GTIN dans l’espace. |
| `links` | object[] | non | Liens typés, en plus de `destination` (le lien par défaut). |
| `forward` | boolean | non | Ajoute `lot`, `serial` et `expiry` lus dans l’adresse scannée à la page ouverte. Par défaut : `false`. |

## Rule

La première règle active dont toutes les conditions sont remplies l’emporte.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string | non | Attribué par le serveur. |
| `name` | string | non | Nom affiché dans les statistiques (dimension `rule`). |
| `active` | boolean | non | Par défaut : `true`. |
| `when` | RuleConditions | non | Voir l’objet `RuleConditions`. |
| `to` | RuleDestination[] | oui | Une destination, ou de 2 à 4 avec `weight` pour un test A/B (plan Pro). Voir l’objet `RuleDestination`. |

## RuleConditions

Toutes les conditions présentes doivent être remplies. Un objet vide s’applique toujours.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `device` | string[] | non | Valeurs : `mobile`, `tablet`, `desktop`. |
| `os` | string[] | non | Valeurs : `ios`, `android`, `windows`, `macos`, `linux`, `other`. |
| `app` | string[] | non | Application dans laquelle le lien s’ouvre. Valeurs : `instagram`, `facebook`, `messenger`, `linkedin`, `tiktok`, `snapchat`, `google`, `wechat`, `line`, `browser`. |
| `lang` | string[] | non | Langues du téléphone (`fr`, `en`…). |
| `country` | string[] | non | Pays ISO 3166-1 alpha-2. |
| `weekday` | integer[] | non | 1 = lundi … 7 = dimanche. |
| `time` | object | non | Plage horaire HH:MM. |
| `date` | object | non | Période, bornes incluses. |

## RuleDestination

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `url` | string (uri) | oui |  |
| `weight` | integer | non | Part du trafic, en %. La somme des poids vaut 100. De 1 à 99. |

## Utm

Paramètres UTM. Une destination qui contient déjà un `utm_*` n’est jamais modifiée.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `source` | string | non | Par défaut : `"qravate"`. |
| `medium` | string | non | Par défaut : `"qr"`. |
| `campaign` | string | non | Par défaut, le nom du QR code. |
| `content` | string | non |  |

## Design

Apparence du QR code. Tous les champs sont facultatifs ; une valeur invalide reprend la valeur par défaut.

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `fg` | string | non | Couleur des modules. Par défaut : `"#000000"`. |
| `bg` | string | non | Couleur du fond. Par défaut : `"#ffffff"`. |
| `transparent` | boolean | non | Fond transparent. Par défaut : `false`. |
| `gradient` | object \| null | non | Dégradé sur les modules. |
| `moduleShape` | string | non | Valeurs : `square`, `rounded`, `dot`, `diamond`, `stripes`, `fluid`. Par défaut : `"square"`. |
| `eyeShape` | string | non | Contour des trois repères. Valeurs : `square`, `rounded`, `circle`, `leaf`. Par défaut : `"square"`. |
| `eyeInner` | string | non | Centre des repères. Valeurs : `square`, `rounded`, `circle`, `diamond`. Par défaut : `"square"`. |
| `eyeColor` | string \| null | non | Couleur des repères ; celle des modules par défaut. |
| `logo` | object \| null | non | Logo central : une icône prédéfinie (`icon`), dessinée de la couleur des yeux, ou un logo ajouté depuis l’application. Taille en part de la largeur (0,10 à 0,24). |
| `frame` | object | non | Cadre avec appel à l’action. |
| `ecc` | string | non | Correction d’erreur, relevée automatiquement si le design l’exige. Valeurs : `L`, `M`, `Q`, `H`. Par défaut : `"M"`. |
| `margin` | integer | non | Marge autour du code, en modules. Par défaut : `4`. De 0 à 6. |
| `corners` | string | non | Valeurs : `square`, `round`. Par défaut : `"square"`. |

## HostedPage

Page servie sur le domaine de scan, sans script ni cookie. Les pages PDF se créent depuis l’application (envoi du fichier).

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `kind` | string | oui | Valeurs : `menu`, `links`, `vcard`, `pdf`. |
| `title` | string | oui | 120 caractères au plus. |
| `description` | string | non | 1000 caractères au plus. |
| `color` | string | non | Couleur d’accent. |
| `sections` | object[] | non | `menu` : sections et plats. |
| `links` | object[] | non | `links` : liste de liens. |
| `contact` | object | non | `vcard` : fiche contact, enregistrable dans le carnet d’adresses. |

## Schedule

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string | non |  |
| `qr_id` | string | non |  |
| `run_at` | string (date-time) | non | Date prévue, en UTC. |
| `destination` | string (uri) | non |  |
| `status` | string | non | Valeurs : `pending`, `applied`, `failed`, `cancelled`. |
| `error` | string \| null | non | Raison de l’échec (`failed`). |
| `created_at` | string (date-time) | non |  |
| `done_at` | string \| null (date-time) | non |  |

## Stats

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `from` | string (date) | non | Début réel de la période, après application de l’historique du plan. |
| `to` | string (date) | non |  |
| `days` | object[] | non | Un élément par jour de Paris, jours sans scan compris. |
| `total` | integer | non | Scans sur la période. |
| `uniques` | integer | non | Somme des visiteurs uniques quotidiens, estimés sans cookie. |
| `dims` | object | non | Répartition des scans, de la valeur la plus fréquente à la moins fréquente. |

## Webhook

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `id` | string | non |  |
| `url` | string (uri) | non |  |
| `events` | string | non | Événements, séparés par des virgules. |
| `scan_threshold` | integer \| null | non |  |
| `source` | string | non | Origine de l’abonnement : `api`, `zapier`, `make`, `n8n`… |
| `disabled_at` | string \| null (date-time) | non | Désactivé après 20 échecs ou une réponse 410. |
| `created_at` | string (date-time) | non |  |
