Création d'un QR Code via l'API REST : Guide avec des exemples curl

Étape 1 : créer la clé

Dans le tableau de bord, sous Compte, section « Accès pour CLI, scripts et agents », vous créez une clé. Pour les premières tentatives, « lecture seule » suffit. Choisissez une durée de vie courte, par exemple 30 jours. La clé commence par sqr_live_ et ne s'affiche qu'une seule fois. Enregistrez-la en tant que variable d'environnement pour qu'elle ne figure pas dans l'historique de votre shell, par exemple via votre gestionnaire de mots de passe.

Étape 2 : La première demande

L'API se trouve à l'adresse https://sameqr.com/api/v1. La clé doit être placée dans l'en-tête Authorization, jamais dans l'URL :

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/konto
curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr

La première demande affiche votre compte, votre forfait et vos limites ; la seconde affiche vos codes avec l'identifiant, le nom, la cible, les étiquettes, le nombre de scans et l'état _rev.

Étape 3 : Création d'un code

Pour créer, vous avez besoin d'une deuxième clé avec « lire + écrire ». Avec une clé en lecture seule, l'API répond aux demandes de modification par 403 et le code NUR_LESEN. Un nouveau code nécessite au moins un nom et une cible :

curl -X POST https://sameqr.com/api/v1/qr \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Speisekarte","targetUrl":"https://example.com/karte"}'

Scannez le nouveau code avec votre téléphone avant de continuer. Pour la création, votre adresse e-mail doit être confirmée, et le code est décompté du quota de votre forfait.

Étape 4 : Modification de la cible

Les modifications de cible sont particulièrement protégées. Vous avez besoin d'une clé « complète » et vous envoyez l'état actuel du code comme en-tête X-Confirm. L'état est fourni par la demande de lecture :

curl -H "Authorization: Bearer $SAMEQR_API_KEY" https://sameqr.com/api/v1/qr/<id>

curl -X PATCH https://sameqr.com/api/v1/qr/<id> \
  -H "Authorization: Bearer $SAMEQR_API_KEY" -H "Content-Type: application/json" \
  -H "X-Confirm: <stand>" \
  -d '{"targetUrl":"https://example.com/karte-neu"}'

Seuls les champs envoyés sont modifiés. Si l'état diffère parce que quelqu'un a modifié le code entre-temps, rien n'est écrasé. Via l'API, il y a au maximum 10 modifications de cible par heure et 30 par jour ; dans le tableau de bord, cette limite n'existe pas. Dans le forfait gratuit, le nombre de modifications de cible par code est limité.

Étape 5 : Comprendre les erreurs et les limites

Les erreurs reviennent toujours sous la même forme : un objet error avec status, code et message. Évaluez-les dans votre programme, au lieu de continuer simplement.

• 401 : La clé est manquante, incorrecte, expirée ou révoquée.
• 403 : La clé ne dispose pas du niveau requis, ou votre forfait ne permet pas l'action.
• 400 avec BESTAETIGUNG_FEHLT : Pour la modification de cible, hors ligne ou suppression, l'en-tête X-Confirm avec l'état actuel est manquant.
• 409 : Quelqu'un a modifié le code en cours de route.
• 429 : Trop de demandes. Par clé, 120 par minute, par heure 60 dans le tarif gratuit, 300 dans Start, 1.000 dans Pro et 5.000 dans Agentur.

Toutes les demandes sont décrites dans /api/v1/openapi.json, le guide se trouve sur sameqr.com/entwickler.

Conclusion : pourquoi Same-QR

L'API REST de Same-QR est épurée, bien documentée et incluse dans tous les forfaits. Elle peut tout faire ce que le tableau de bord peut faire, protège les codes imprimés avec confirmation et limites contre les modifications accidentelles de cible, permet les clés en trois niveaux et répond avec des erreurs compréhensibles.

Lancez-vous tout de suite : inscrivez-vous gratuitement sur sameqr.com, deux codes QR dynamiques sont gratuits pour toujours. L’API, la CLI et le serveur MCP sont inclus dans chaque offre, la documentation se trouve sur sameqr.com/entwickler.

Questions fréquentes