L’API

L’API est servie par le même Cloudflare Worker qui résout vos liens, sur l’origine Kilo QR. Aujourd’hui, cela signifie que les requêtes vont vers qr2r.com sous le préfixe /api :

https://qr2r.com/api

Chaque chemin de ces guides est relatif à cette base - /links signifie https://qr2r.com/api/links. Un moyen rapide de confirmer qu’une clé fonctionne est la racine de l’API, qui renvoie votre identité :

{ "api": "qr2r", "version": 0, "user": { "uid": 42, "email": "", "admin": false } }

Envoyez votre clé comme jeton bearer dans l’en-tête Authorization. La clé est vérifiée avant le cookie de session, si bien qu’un client d’API reste sur un seul mode d’authentification sans qu’un cookie de navigateur périmé se glisse.

Authorization: Bearer qr2r_live_1a2b3c…

Les clés commencent par qr2r_live_ (ou qr2r_test_ pour une clé en mode dev). Ce préfixe qr2r_ est un identifiant d’infrastructure qui n’a délibérément pas été renommé - la même raison pour laquelle le domaine est encore qr2r.com. Vous générez une clé dans le tableau de bord, sous API keys ; le jeton complet est affiché une seule fois à la création, et Kilo ne stocke que son hachage SHA-256, alors mettez-le directement dans un gestionnaire de secrets. Une requête sans clé valide (et sans session) est refusée :

{ "error": "unauthorized" }

Une clé porte l’un ou les deux de deux scopes. Une clé de lecture ne peut appeler que des méthodes sûres - GET, HEAD, OPTIONS. Une clé d’écriture est en plus autorisée à POST, PUT, PATCH et DELETE. Une tentative d’écriture avec une clé en lecture seule est refusée :

{ "error": "insufficient_scope", "required": "write" }

Les scopes sont toute l’histoire des permissions d’une clé : une clé peut gérer des liens, des règles et lire des analyses, mais elle ne peut jamais gérer des membres, la facturation ou d’autres clés - ces actions restent liées à une session interactive. Donnez à une intégration une clé de lecture quand tout ce qu’elle fait est de tirer des chiffres.

Chaque réponse d’erreur est un objet JSON avec une chaîne error, plus des champs supplémentaires là où ils aident. Les échecs de validation portent la liste complète des problèmes sous issues :

{ "error": "invalid_body", "issues": [ /* zod issues */ ] }

Les codes que vous rencontrerez le plus :

• 400 invalid_body - le corps de la requête a échoué à la validation.
• 401 unauthorized - clé manquante ou invalide.
• 402 plan_required - la fonctionnalité nécessite une offre supérieure (porte feature).
• 403 insufficient_scope / forbidden - la clé ne peut pas exécuter cette méthode ou action.
• 404 not_found - pas de tel lien, règle ou domaine dans votre espace de travail.
• 409 - un conflit, tel que name_taken ou cap_reached.
• 422 destination_unsafe - la destination a échoué à la vérification de sécurité.
• 429 rate_limited - trop de requêtes (voir ci-dessous).

Les requêtes authentifiées sont limitées en débit. Le seau général autorise 60 requêtes par minute par utilisateur. En plus, une clé d’API obtient son propre plafond par clé et par minute, tiré de la limite api_rpm de votre offre. Franchissez l’un ou l’autre et la réponse est :

{ "error": "rate_limited", "retry_after": 42 }

La valeur retry_after (envoyée aussi comme en-tête Retry-After) est le nombre de secondes jusqu’à ce que la fenêtre se réinitialise. Patientez d’autant et réessayez.

Une clé en main, le guide suivant parcourt les endpoints de liens un appel à la fois.